spec_writer

Spec Writer

State file: .claude/swe-state/{ticket-id}.json

Orchestrate Stage 2: explore codebase, generate spec, review-fix loop, produce implementation plan, review-fix loop.

Usage

/spec_writer <ticket-id>

Read stages.intake.ticket_file from state to locate the ticket. If stages.intake.completed is not true, tell the user to run /ticket_intake first.

---

2A: Codebase Exploration

Read ticket.json and extract title, description, acceptance_criteria, labels.

Select explorers based on labels:

Ticket Type	Explorers	Count
Bug fix (bug, fix, bugfix)	Entity + Test + Pattern	3
New feature (feature, enhancement)	Entity + Dependency + Pattern + Test + Integration	5
Refactor (refactor, cleanup, tech-debt)	Entity + Dependency + Pattern	3
API change (api, endpoint, rest, graphql)	Entity + Dependency + Integration	3
Default	Entity + Dependency + Pattern + Test	4

Spawn all selected explorers as subagent_type: Explore with max_turns: 10 in a SINGLE message. Each gets:

Explore the codebase to find {topic} relevant to this ticket.
Ticket: {title} — {description}
Find: {search items}
Output a structured "{Section Name}" section.

Explorer	Topic	Search Items	Output Section
Entity	entities	models, schemas, types, interfaces, fields, relationships	Entity Map
Dependency	dependencies	import chains, API boundaries, blast radius	Dependency Graph
Pattern	patterns	similar implementations, conventions, file organization	Existing Patterns
Test	test landscape	test structure, fixtures, mocks, coverage gaps	Test Landscape
Integration	integrations	external services, APIs, databases, config, env vars	External Integrations

Merge outputs into .claude/specs/{ticket-id}-context.md (path from stages.spec.context_file in state).

---

Review-Fix Loop

This loop is used twice in this skill — once for the spec (2B↔2C) and once for the impl plan (2D↔2E). The steps are identical; only the parameters change.

Parameters

	Spec loop (2B↔2C)	Impl plan loop (2D↔2E)
document	stages.spec.spec_file	stages.spec.impl_plan_file
author_agent	full-orchestration:SpecArchitect	full-orchestration:ImplPlanner
iteration_field	stages.spec.spec_review_iterations	stages.spec.impl_review_iterations
next phase	2D: Implementation Planning	Stage 3

Steps

Start with iteration = 0.

Step 1 — Review: Increment iteration. Run /spec_review {document path from state}. On failure, retry once. If second failure, skip to Step 5 with a warning that review could not complete.

Step 2 — Check convergence: If /spec_review reports 0 OPEN comments, the document has converged. Skip to Step 5 for cleanup and user gate.

Step 3 — Fix: Spawn the author agent to address comments:

subagent_type: {author_agent}
max_turns: 15
prompt: |
  State file: .claude/swe-state/{ticket-id}.json
  Read state to locate the document under review, context_file,
  and stages.intake.ticket_file.

  Review comments have been added to the document. For each
  comment marked OPEN:
  1. Understand the reviewer's concern
  2. Reference the ticket and codebase context as needed
  3. Modify the relevant section to address it
  4. Change the comment status from OPEN to RESOLVED

  Do NOT delete comments. Do NOT add new content beyond
  addressing the comments. Do NOT change sections with no comments.

  When done, report: number of comments addressed, any you
  couldn't resolve (with explanation).

Step 4 — Update state: Set {iteration_field} = iteration in the state file. If iteration < 5, go back to Step 1.

Step 5 — Cleanup: Read the document. If capped with OPEN comments, extract all > **[...|OPEN]** lines and save as a list for the user gate. Remove all blockquote comment lines matching > **[...|RESOLVED]** or > **[...|OPEN]**. Write the cleaned file back.

Step 6 — User gate: Present the clean document. If OPEN comments remained at cap, show the extracted list separately. User chooses:

• Approve → proceed to {next phase}
• Request changes → user provides direction, spawn {author_agent} with the Step 3 prompt plus user direction appended. Set iteration = min(iteration, 4) so there is at least 1 review pass after a user-requested revision. Go back to Step 1.

If iteration reaches 5 with OPEN comments remaining, report: "{N} OPEN comments remain after 5 rounds." Then proceed to Step 5.

---

2B: Spec Generation

subagent_type: full-orchestration:SpecArchitect
max_turns: 15
prompt: |
  State file: .claude/swe-state/{ticket-id}.json
  Read state to locate: stages.intake.ticket_file, stages.spec.context_file,
  and stages.spec.spec_file.
  Read the ticket and context, then write the spec to the spec_file path.

After SpecArchitect completes, run the Review-Fix Loop with the Spec parameters.

---

2D: Implementation Planning

subagent_type: full-orchestration:ImplPlanner
max_turns: 15
prompt: |
  State file: .claude/swe-state/{ticket-id}.json
  Read state to locate: stages.spec.spec_file, stages.spec.context_file,
  and stages.spec.impl_plan_file.
  Read the spec and context, then write the implementation plan to
  the impl_plan_file path.

After ImplPlanner completes, run the Review-Fix Loop with the Impl plan parameters.

---

Update State

Set stages.spec.completed = true. All file paths are already in state from initialization.