0_spec

Create a detailed spec for the following feature: $ARGUMENTS

$ARGUMENTS is an optional feature name or focus hint. The primary requirements source is .claude/input/.

Steps:

1. Read CLAUDE.md for project context and conventions
2. Read all files in .claude/context/ if the directory exists — these are long-lived project references (schemas, API docs, glossaries) 2b. Resolve linked work items — if the input or $ARGUMENTS mentions a ticket/issue ID (e.g. "Ticket 1234", "#1234", "1234.Improvement..."), try to fetch it using the project's configured work-item tracker. Check which MCP tools are available (Azure DevOps, Jira, Linear, GitHub Issues, or similar). If a tool is available, fetch the ticket with comments and linked items. Review resolved related/parent items: their linked commits, branches, and PRs point to prior work. Run git show <sha> or git log master..<branch> on those references and fold the actual implementation status into the spec. Doing this before codebase exploration prevents you from re-scoping work that is already done elsewhere. If no tracker MCP tool is available, skip this step.
3. Read all files in .claude/input/ if the directory exists — these are the raw requirements materials (docs, images, wireframes, PDFs). Treat them as the primary source of truth for what to build 3b. Historical pattern awareness — if the subagent prompt includes historical pattern analysis (from /ship Step 1b), use it to increase spec depth in problem areas. For example:
   • If prior features in this area had recurring validation issues → add an explicit "Input validation rules" subsection under Implementation notes listing every input, its type, its constraints, and what happens on invalid input
   • If prior features had recurring edge-cases issues → add an explicit "Edge cases" subsection listing boundary conditions, empty states, concurrent access scenarios, and off-by-one risks
   • If prior features had recurring types issues → add explicit type signatures in Implementation notes for all new/changed functions
   • If prior features had high review cycles (>2 avg) → write more granular test cases and tighter validation criteria
   • If no historical data is provided (standalone /0_spec run), skip this step — it changes nothing about the default behavior
4. Explore the codebase to understand the relevant architecture — find and read the files most likely affected by this feature 4b. Check completed work: Before deferring any scope (especially frontend) because a dependency "is not yet implemented", verify the actual completion status. If a work-item tracker was queried in Step 2b, resolved related/parent items expose linked commits and branches. Use git show <sha> or git log master..<branch> to inspect what was actually built. If no tracker is available, check git log for related branch names or commit messages. Never assume a dependency is missing — check first.
5. Identify: which files will change, what new files are needed, and what existing patterns to follow
6. Before writing the spec, surface any ambiguous requirements or missing decisions. Ask 2–3 targeted clarifying questions — use selectable answer options where possible to keep responses fast. Wait for answers before proceeding. Skip this step if the requirements are already unambiguous. 6b. For PRDs that involve UI/UX decisions or architectural patterns not explicitly stated in the requirements, always surface these as questions — even if the PRD appears complete. Mark them as "(Implementation choice — not in PRD)" so the user knows they are optional and can be skipped if Claude should decide freely. Examples: component selection, state management granularity, polling intervals, retry logic, file upload UX patterns, where to place cross-cutting concerns in the service layer. 6c. After writing the spec, explicitly state which decisions were made freely (not specified in the PRD) under a section called "Decisions made by Claude". This makes assumptions visible and prevents silent architectural drift.
7. Write the spec to .claude/specs/<kebab-case-feature-name>.md with these sections:
   • Goal: one-sentence summary
   • Requirements: bulleted list of what it must do
   • Out of scope: what it explicitly will not do
   • Affected files: list existing files that will change and why
   • New files: list any new files needed
   • Patterns to mirror: 2–3 specific existing files whose structure, naming, or style the implementation should follow — this is the codebase intelligence that lets /1_implement match conventions without exploring
   • Implementation notes: key decisions, edge cases to handle
   • UX concept (REQUIRED when the PRD includes a Frontend section — never silently drop frontend scope; if deferring, state the target PRD explicitly):
     • Component tree: hierarchical breakdown of components needed (leaf → container), noting which are new vs existing. Use indentation to show nesting.
     • Interaction flows: describe each distinct user journey as a numbered sequence of steps. For multi-step flows (wizards, forms, onboarding), include: trigger → intermediate states → success state → error/edge states. Use mermaid stateDiagram-v2 for complex flows with branching.
     • State & data flow: which component owns which state, what gets lifted, what goes into global store vs local state. Map data dependencies (e.g. "ResultsChart reads scores from Zustand store, computed by calculateScores() in scoring engine").
     • Responsive behavior: specify layout changes at breakpoints if the feature involves layout (e.g. "stack cards vertically below md"). Skip if not applicable.
     • Accessibility: required keyboard navigation, ARIA roles, focus management, screen reader considerations. At minimum: all interactive elements keyboard-reachable, form inputs labeled, error states announced.
     • Reuse check: list existing UI components/patterns in the codebase that can be reused or extended instead of built from scratch. Avoid creating new components when existing ones can be composed.
   • Validation criteria: explicit, observable conditions that confirm the feature is done (e.g. "navigating to /results shows a radar chart with 6 axes"); complement the test cases. These will be verified by both /1_implement and /3_fix — write them precisely enough to be checkable.
   • Test cases: describe expected behavior with enough specificity to write a failing test from each case — include inputs, expected outputs, and key error/edge cases. Include both pure-function tests (engine/logic) AND component-level rendering tests (e.g. "renders X when prop Y") — implementations consistently skip component tests when only logic tests are listed
   • Decisions made by Claude: list any architectural or implementation decisions that were not specified in the requirements, each with a risk classification — makes assumptions visible to the reviewer. Risk levels: (low) = naming, file structure, cosmetic choices; (medium) = state management, data flow, API shape; (high) = security, auth, data model, persistence strategy. High-risk decisions should be confirmed by the user before implementation proceeds.
8. After writing: count the total files listed under "Affected files" + "New files". If the total exceeds complexity_gate_max_files from CLAUDE.md (default: 10), add a ⚠ Complexity flag section noting that this feature may be too large for a single implementation session and suggesting decomposition into sub-specs.
9. Suggest to the user that they move the processed files from .claude/input/ to .claude/archive/ now that the spec is written.