#683 - Rename to-prd/to-issues to to-spec/to-tickets, refresh from upstream

.claude/skills/log-future-addition/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: log-future-addition
-description: File a single out-of-scope idea, feature, or improvement as one un-triaged GitHub issue. Use whenever the user raises something that would be a good future addition to the app but is out of scope for the current work ("we could also…", "would be nice to…", "let's do that later") — offer to log it. For a fleshed-out feature use to-prd; to break an existing plan into tickets use to-issues.
+description: File a single out-of-scope idea, feature, or improvement as one un-triaged GitHub issue. Use whenever the user raises something that would be a good future addition to the app but is out of scope for the current work ("we could also…", "would be nice to…", "let's do that later") — offer to log it. For a fleshed-out feature use to-spec; to break an existing plan into tickets use to-tickets.
 ---
 
 # Log Future Addition
 
 Capture one rough, out-of-scope idea as a single un-triaged GitHub issue, so a good thought is not lost when it surfaces mid-work.
 
-This is the lightweight counterpart to `to-prd`. Use it for a **brief, quick idea** — anything already thought through belongs in `to-prd` (a spec) or a `grill-with-docs` session. It is NOT for breaking down plans; that is `to-issues`.
+This is the lightweight counterpart to `to-spec`. Use it for a **brief, quick idea** — anything already thought through belongs in `to-spec` (a spec) or a `grill-with-docs` session. It is NOT for breaking down plans; that is `to-tickets`.
 
 Issue tracker conventions (title, labels, backticks, assignment) live in `docs/agents/issue-tracker.md`. The `Idea` term is defined in `docs/agents/glossary.md`. Do not duplicate those here — link and follow.
 
@@ -16,7 +16,7 @@ Issue tracker conventions (title, labels, backticks, assignment) live in `docs/a
 - An out-of-scope idea comes up in conversation and you want to keep it without derailing the current work.
 - You have a one-line feature/bug/improvement scrap and just want it on the tracker.
 
-If the input is really a plan or spec — multiple features, acceptance criteria, phased work, or simply long and detailed — say so and point the user to `to-prd` (one PRD issue) or `to-issues` (many tracer-bullet issues). Suggest, do not hard-refuse; the user can override.
+If the input is really a plan or spec — multiple features, acceptance criteria, phased work, or simply long and detailed — say so and point the user to `to-spec` (one spec issue) or `to-tickets` (many tracer-bullet issues). Suggest, do not hard-refuse; the user can override.
 
 ## Two-stage consent
 

.claude/skills/to-prd/SKILL.md → .claude/skills/to-spec/SKILL.md

@@ -1,25 +1,24 @@
 ---
-name: to-prd
-description: Turn the current conversation context into a PRD and publish it to the project issue tracker. Use when user wants to create a PRD from the current context.
+name: to-spec
+description: Turn the current conversation into a spec and publish it to the project issue tracker — no interview, just synthesis of what you've already discussed.
+disable-model-invocation: true
 ---
 
-This skill takes the current conversation context and codebase understanding and produces a PRD. Do NOT interview the user — just synthesize what you already know.
+This skill takes the current conversation context and codebase understanding and produces a spec (you may know this document as a PRD). Do NOT interview the user — just synthesize what you already know.
 
 Issue tracker conventions live in `docs/agents/issue-tracker.md`; the triage label vocabulary lives in `docs/agents/triage-labels.md`.
 
 ## Process
 
-1. Explore the repo to understand the current state of the codebase, if you haven't already. Use the project's domain glossary vocabulary throughout the PRD, and respect any ADRs in the area you're touching.
+1. Explore the repo to understand the current state of the codebase, if you haven't already. Use the project's domain glossary vocabulary throughout the spec, and respect any ADRs in the area you're touching.
 
-2. Sketch out the major modules you will need to build or modify to complete the implementation. Actively look for opportunities to extract deep modules that can be tested in isolation.
+2. Sketch out the seams at which you're going to test the feature. Existing seams should be preferred to new ones. Use the highest seam possible. If new seams are needed, propose them at the highest point you can. The fewer seams across the codebase, the better — the ideal number is one.
 
-A deep module (as opposed to a shallow module) is one which encapsulates a lot of functionality in a simple, testable interface which rarely changes.
+Check with the user that these seams match their expectations.
 
-Check with the user that these modules match their expectations. Check with the user which modules they want tests written for.
+3. Write the spec using the template below, then publish it to the project issue tracker. Apply the `ready-for-agent` triage label - no need for additional triage.
 
-3. Write the PRD using the template below, then publish it to the project issue tracker. Apply the `ready-for-agent` triage label - no need for additional triage.
-
-<prd-template>
+<spec-template>
 
 ## Problem Statement
 
@@ -67,10 +66,10 @@ A list of testing decisions that were made. Include:
 
 ## Out of Scope
 
-A description of the things that are out of scope for this PRD.
+A description of the things that are out of scope for this spec.
 
 ## Further Notes
 
 Any further notes about the feature.
 
-</prd-template>
+</spec-template>

.claude/skills/to-tickets/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: to-tickets
+description: Break a plan, spec, or the current conversation into a set of tracer-bullet tickets, each declaring its blocking edges, published to the project issue tracker. Use when the user wants to convert a plan into issues, create implementation tickets, or break down work into issues.
+disable-model-invocation: true
+---
+
+# To Tickets
+
+Break a plan, spec, or conversation into a set of **tickets** — tracer-bullet vertical slices, each declaring the tickets that **block** it.
+
+Issue tracker conventions live in `docs/agents/issue-tracker.md`; the triage label vocabulary lives in `docs/agents/triage-labels.md`.
+
+## Process
+
+### 1. Gather context
+
+Work from whatever is already in the conversation context. If the user passes a reference (a spec path, an issue number or URL) as an argument, fetch it and read its full body and comments.
+
+### 2. Explore the codebase (optional)
+
+If you have not already explored the codebase, do so to understand the current state of the code. Ticket titles and descriptions should use the project's domain glossary vocabulary, and respect ADRs in the area you're touching.
+
+Look for opportunities to prefactor the code to make the implementation easier. "Make the change easy, then make the easy change."
+
+### 3. Draft vertical slices
+
+Break the work into **tracer bullet** tickets.
+
+Slices may be **HITL** or **AFK**. HITL slices require human interaction, such as an architectural decision or a design review. AFK slices can be implemented and merged without human interaction. Prefer AFK over HITL where possible.
+
+<vertical-slice-rules>
+
+- Each slice cuts a narrow but COMPLETE path through every layer (schema, API, UI, tests) — vertical, NOT a horizontal slice of one layer
+- A completed slice is demoable or verifiable on its own
+- Each slice is sized to fit in a single fresh context window
+- Prefer many thin slices over few thick ones
+- Any prefactoring should be done first
+
+</vertical-slice-rules>
+
+Give each ticket its **blocking edges** — the other tickets that must complete before it can start. A ticket with no blockers can start immediately.
+
+**Wide refactors are the exception to vertical slicing.** A **wide refactor** is one mechanical change — rename a column, retype a shared symbol — whose **blast radius** fans across the whole codebase, so a single edit breaks thousands of call sites at once and no vertical slice can land green. Don't force it into a tracer bullet; sequence it as **expand–contract**. First expand: add the new form beside the old so nothing breaks. Then migrate the call sites over in batches sized by blast radius (per package, per directory), each batch its own ticket blocked by the expand, keeping CI green batch to batch because the old form still exists. Finally contract: delete the old form once no caller remains, in a ticket blocked by every migrate batch. When even the batches can't stay green alone, keep the sequence but let them share an integration branch that all block a final integrate-and-verify ticket — green is promised only there.
+
+### 4. Quiz the user
+
+Present the proposed breakdown as a numbered list. For each ticket, show:
+
+- **Title**: short descriptive name
+- **Type**: HITL / AFK
+- **Blocked by**: which other tickets (if any) must complete first
+- **What it delivers**: the end-to-end behaviour this ticket makes work
+
+Ask the user:
+
+- Does the granularity feel right? (too coarse / too fine)
+- Are the blocking edges correct — does each ticket only depend on tickets that genuinely gate it?
+- Should any tickets be merged or split further?
+- Are the correct slices marked HITL and AFK?
+
+Iterate until the user approves the breakdown.
+
+### 5. Publish the tickets to the issue tracker
+
+Publish the approved tickets to the project issue tracker (GitHub Issues — see `docs/agents/issue-tracker.md`). Publish one issue per ticket in dependency order (blockers first) so each ticket's blocking edges can reference real issue identifiers. Use GitHub's native sub-issue / blocking relationship where it fits; otherwise set each ticket's "Blocked by" to the blocking issues. Apply the `ready-for-agent` triage label unless instructed otherwise — the tickets are agent-grabbable by construction.
+
+Do NOT close or modify any parent issue.
+
+<issue-template>
+
+## Parent
+
+A reference to the parent issue on the issue tracker (if the source was an existing issue, otherwise omit this section).
+
+## What to build
+
+The end-to-end behaviour this ticket makes work, from the user's perspective — not layer-by-layer implementation.
+
+## Acceptance criteria
+
+- [ ] Criterion 1
+- [ ] Criterion 2
+- [ ] Criterion 3
+
+## Blocked by
+
+- A reference to each blocking ticket, or "None — can start immediately".
+
+</issue-template>
+
+Avoid specific file paths or code snippets — they go stale fast. Exception: if a prototype produced a snippet that encodes a decision more precisely than prose can (state machine, reducer, schema, type shape), inline it and note briefly that it came from a prototype. Trim to the decision-rich parts — not a working demo, just the important bits.
+
+Work the frontier one ticket at a time, clearing context between tickets.

CLAUDE.md

@@ -50,7 +50,7 @@ Frontend and backend conventions live alongside their code and auto-load when ed
 
 ## Agent skills
 
-Workflow skills (commit, open-pr, update-pr, address-pr-comments, run-local, verify-telemetry, verify-graph) and Matt Pocock's engineering and issue-authoring skills live in `.claude/skills/`. The AI issue-authoring flow is `grill-with-docs → to-prd → to-issues → triage`. See `docs/adr/0002-misc-adopt-matt-pocock-skills.md`. The `caveman` terse mode is on by default in this repo as a pilot — see the Communication section above.
+Workflow skills (commit, open-pr, update-pr, address-pr-comments, run-local, verify-telemetry, verify-graph) and Matt Pocock's engineering and issue-authoring skills live in `.claude/skills/`. The AI issue-authoring flow is `grill-with-docs → to-spec → to-tickets → triage`. See `docs/adr/0002-misc-adopt-matt-pocock-skills.md` and `docs/adr/0003-misc-rename-to-spec-to-tickets.md`. The `caveman` terse mode is on by default in this repo as a pilot — see the Communication section above.
 
 ### Issue tracker
 

docs/adr/0002-misc-adopt-matt-pocock-skills.md

@@ -1,5 +1,7 @@
 # Adopt Matt Pocock's agent skills for AI-driven issue authoring
 
+> **Amended by [ADR-0003](0003-misc-rename-to-spec-to-tickets.md).** The `to-prd` and `to-issues` skills named throughout this ADR were later renamed to `to-spec` and `to-tickets` (tracking Matt Pocock's upstream renames) and refreshed with upstream content. Read the old skill names below as their current equivalents; the two-path rationale is unchanged.
+
 Argos adopts Matt Pocock's `grill-with-docs → to-prd → to-issues → triage` skill flow as the AI-driven path for issue authoring and triage. The legacy `create-ticket` and `brainstorm-ticket` skills retire. Humans continue to author issues via Argos's GitHub form templates (`task.yml`, `bug-form.yml`, `feature-request.yml`, `epic.yml`); AI authors via Matt's baked-in body shapes filed through `gh issue create --body`. The `ready-for-agent` triage label distinguishes AI-filed issues.
 
 ## Considered Options

docs/adr/0003-misc-rename-to-spec-to-tickets.md

@@ -0,0 +1,25 @@
+# Rename to-prd → to-spec and to-issues → to-tickets, refreshed from upstream
+
+Argos renames its two AI issue-authoring skills to track Matt Pocock's upstream renames and folds in the upstream content improvements, while preserving Argos-specific customizations. `to-prd` becomes `to-spec`; `to-issues` becomes `to-tickets`. The AI issue-authoring flow is now `grill-with-docs → to-spec → to-tickets → triage`. This amends [ADR-0002](0002-misc-adopt-matt-pocock-skills.md); the two-path rationale (humans author via GitHub form templates, AI authors via Matt's body shapes) is unchanged.
+
+## Considered Options
+
+- Rename only, keep the customized skill bodies as-is.
+- Rename plus selectively adopt only the non-conflicting upstream additions.
+- Rename plus fold in the full upstream content (chosen).
+
+## Why rename and fold
+
+- Upstream renamed the skills so "spec" is the single through-line term (`to-spec` still opens "you may know this document as a PRD" for discoverability), and merged `to-plan` + `to-issues` into one `to-tickets`. Keeping the old names left our copies as stale forks diverging from a source we still pull from.
+- The upstream content carries real improvements worth having: the **wide-refactor / expand–contract** sequence for a mechanical change whose blast radius breaks vertical slicing; a **prefactoring** step ("make the change easy, then make the easy change"); single-fresh-context-window slice sizing; and `disable-model-invocation: true` so these user-invoked flow skills don't fire autonomously.
+- `to-spec` adopts upstream's **seam** framing for step 2 (test at the highest, fewest seams) in place of our earlier deep-module framing. Deep-module vocabulary now lives with `codebase-design` upstream; this keeps `to-spec` focused on where tests go.
+
+## Consequences
+
+- `.claude/skills/to-prd/` → `.claude/skills/to-spec/`; `.claude/skills/to-issues/` → `.claude/skills/to-tickets/` (directory, frontmatter `name`, and `description` all updated).
+- Argos customizations are preserved through the fold: both skills keep pointing at `docs/agents/issue-tracker.md` and `docs/agents/triage-labels.md` rather than upstream's `/setup-matt-pocock-skills` (which Argos does not vendor); `to-tickets` keeps the **HITL / AFK** slice classification in its rules and quiz; and `to-tickets` publishes only to Argos's GitHub Issues tracker, dropping upstream's tracker-agnostic local-file (`tickets.md`) path.
+- `to-tickets` ends on the "work the frontier one ticket at a time" note without upstream's hard `/implement` reference, since Argos has not yet vendored the `implement` skill.
+- References updated in `CLAUDE.md` (flow string), `docs/agents/glossary.md` (Tracer-bullet, Spec/PRD, Idea entries), `docs/agents/issue-tracker.md` (body-shape ownership line), and `.claude/skills/log-future-addition/SKILL.md` (three pointers).
+- ADR-0002 gains an amendment banner pointing here; its body keeps the historical `to-prd` / `to-issues` names.
+
+See `docs/adr/0002-misc-adopt-matt-pocock-skills.md`, `docs/agents/issue-tracker.md`, `docs/agents/glossary.md`.