To Issues

Translate a complete spec into independently-grabbable issues using vertical slices (tracer bullets). This is a translation job — the spec is the source of truth, and ticket quality is measured by faithfulness to it.

If information needed to write a ticket is not in the spec, do not research it yourself and do not guess. Stop and flag the gap. The spec must be fixed before the ticket can be written.

Process

1. Read the spec

Read every document in docs/<feature>/. If the user points to an issue or external document, read that too.

Look specifically for:

• The feature overview and user journey
• The per-area specs (dashboard, ingest, etc.)
• The architecture.md — this should contain the interface contracts, third-party constraints, framework patterns, and codegen requirements. If it is missing or incomplete, flag this before proceeding.

2. Explore the codebase

Read the relevant parts of the codebase to fill in factual details the spec reasonably left implicit. This includes:

• Existing class names, method names, and file path conventions — so tickets use the project's real vocabulary
• Current method or type signatures where the spec says something like "match the existing pattern" — look up the actual signature and write it into the ticket
• Whether a given framework registration step is required — check how it's done for existing routes
• What a current response shape looks like, to verify the spec's proposed changes are consistent

The rule: if the codebase gives you a clear, unambiguous answer — use it. If it requires interpretation, a design choice, or involves conflicting signals — ask the user instead. Treat these like grill-me questions: one at a time, with your recommended answer, waiting for confirmation before proceeding.

If you find something in the codebase that contradicts or is missing from the spec, surface it explicitly. Do not silently resolve it.

3. Spec coverage check

Build a coverage map before drafting any tickets: walk through every feature, endpoint, component state, background job, and data lifecycle concern in the spec, and note which area of the implementation covers it.

Flag any uncovered spec element. Present the map to the user. Do not proceed until every element has an owner.

4. Draft vertical slices

Break the plan into tracer bullet issues. Each issue is a thin vertical slice that cuts through ALL relevant layers end-to-end — not a horizontal layer slice.

Slice types:

• AFK — can be implemented and merged by an autonomous agent without human input. Prefer these.
• HITL — requires a human decision before work can proceed. Any [HITL] marker in the spec must become a HITL block in a ticket.

Vertical slice rules:

• Each slice delivers a narrow but complete path through every layer it touches
• A completed slice is independently demoable or verifiable
• Prefer many thin slices over few thick ones
• When a slice defines an interface (a repository class, an endpoint, a component), include the complete interface as specified in architecture.md — not just the parts needed by that slice. Future slices and consumers will depend on it.

Dependency naming: When one slice blocks another, name the specific method, endpoint, or component that must exist — not just the ticket name. "Blocked by the schema ticket" is not sufficient. "Blocked by SkillInventoriesRepository.listHardPruneCandidatesOlderThan" is.

5. Quiz the user

Present the proposed breakdown as a numbered list. For each slice:

• Title: short descriptive name
• Type: HITL / AFK
• Blocked by: specific methods/endpoints from the blocking ticket
• Spec coverage: which spec sections this delivers

Ask:

• Does the granularity feel right?
• Are there any spec elements not covered by any slice?
• Are the dependency relationships correct?
• Should any slices be merged or split?
• Are there HITL markers in the spec that are not reflected as HITL blocks in the breakdown?

Iterate until approved.

6. Publish issues

Before publishing, confirm the target team and project with the user. Use the Linear MCP to look up available teams (mcp__linear-server__list_teams) and projects (mcp__linear-server__list_projects) so you can confirm you're publishing to the right place.

Publish in dependency order (blockers first) so you can reference real ticket IDs when writing "Blocked by" sections in later tickets. Use mcp__linear-server__save_issue for each ticket. After publishing each ticket, note its assigned ID — you will need it to fill in dependency references in subsequent tickets.

Labels: Map slice type to a Linear label — AFK → AFK, HITL → HITL. Look up label IDs with mcp__linear-server__list_labels before publishing and include them on each issue.

Blocking relations: After all issues are created, set blocking relationships using mcp__linear-server__create_issue_relation with type: "blocks", issueId set to the blocking issue's ID, and relatedIssueId set to the blocked issue's ID. Do this for every dependency pair identified in step 4.

Each ticket body must be self-contained: an autonomous agent reading it must be able to implement the slice without referencing any other document. Quotes from the spec should appear directly in the ticket — do not just link to the spec.

---

What to build

A concise description of this vertical slice — what it delivers end-to-end. Use the project's domain vocabulary.

Where the spec expresses a decision as a type shape, interface signature, or schema definition, include it here verbatim. These are the decision-rich parts — not a working prototype, just the parts that encode choices.

If there are open questions the agent must not answer autonomously, mark them [HITL: <question>]. The orchestrator will block on these until a human responds.

Interface contract

Copied from architecture.md. What this slice produces and what it consumes across ticket boundaries.

Produces:

• (list methods, endpoints, or components with signatures, as specified in the architecture doc)

Consumes:

• (list methods, endpoints, or components from other tickets that must exist first)

If nothing crosses ticket boundaries: "Self-contained."

Technical notes

Copied or quoted from architecture.md. Non-obvious constraints and required patterns for this slice.

If architecture.md is thorough, this section is largely a paste from it — filtered to the constraints relevant to this slice. Do not add constraints here that are not in the spec; if something is missing from architecture.md, flag it rather than patching it here.

If no special constraints apply to this slice: "No special constraints."

Spec reference

Verbatim quote of the spec section(s) this slice implements. Include the document name and enough surrounding context that the quote is unambiguous.

If there is no spec document: "No spec — requirements described in 'What to build' above."

Acceptance criteria

• The described behavior is implemented end-to-end
• All methods and endpoints listed in the Interface Contract section exist and match the specified signatures
• No placeholder text, debug output, or TODO comments are visible in the shipped UI or API responses
• cd apps/backend && bun run lint && bun run test passes (or apps/frontend if frontend-only, or both if the slice spans both)
• (Add any slice-specific criteria derived from the spec here)

Blocked by

• (Specific method or endpoint name) from (Ticket reference)

Or "None — can start immediately."

---

Do NOT close or modify any parent issue. Do NOT create tickets for work that is already complete. Do NOT make design decisions autonomously — if something requires judgment rather than lookup, ask the user first.