git:20260808.d7f6561 to git:20260827.12933dd

1 added, 3 removed. Audit A to A.

---

name: tech-spec:create

- disable-model-invocation: true

- description: |

- Create a technical specification through interactive planning and expert review. Use when starting a new feature or project that needs documented architecture, implementation approach, and design decisions. Invoke with product requirements (PRD, brief, or similar).

+ description: Write a technical specification for a feature or project from product requirements.

---

# Create Technical Specification

## Workflow

### Gather Inputs

Ask the user to provide:

- **Product requirements**: PRD, product brief, or similar. Accept local files (`@path/to/file.md`), URLs (fetch via appropriate tools), or pasted content.

- **Project tracking context**: A project, epic, or initiative in their task management system (Linear, GitHub, Jira, etc.). Use available MCP tools to fetch details.

- **Output path**: Where to write the spec (e.g., `tmp/feature-tech-spec.md`).

Be flexible about input sources. Don't assume specific tools or formats.

### Explore Codebases

Discuss with the user which repositories need exploration:

- Suggest likely candidates based on the project scope

- Ask the user to confirm or identify additional repos

- Dispatch background explore agents for breadth-first discovery while the user is away

Scan for:

- Relevant existing patterns and conventions

- Database schemas and models

- API structure and routing

- Frontend component architecture

- Infrastructure and deployment configuration

### Planning Interview

Interview the user through `AskUserQuestion`, batching up to 4 questions per call by topic and refining later batches based on prior answers. Guide the interview toward:

- Requirements clarification

- Scope boundaries (what's in, what's out)

- Technical constraints

- Integration points

- Rollout strategy

### Write Initial Draft

Write incrementally to the output file, section by section. Use the template structure from [references/template.md](references/template.md).

For architecture diagrams, always use `mermaid:diagram` for correct syntax and rendering.

### Expert Review

Invoke `tech-spec:review` on the draft spec.

### Iterate

Refine until the user is satisfied. Long sessions with incremental changes create drift—validate consistency before concluding:

- **Stale references**: Scope changes in one section may leave dangling references elsewhere

- **Contradictions**: Later decisions may conflict with earlier sections

- **Orphaned details**: Implementation details that no longer match the architecture

- **Milestone alignment**: Ensure milestones still reflect the current scope

Also address:

- Expanding under-specified sections

- Adding missing edge cases or error handling

- Refining milestones for incremental delivery

## Design Decisions Table

Captures architecture trade-offs:

|----------|--------|--------------|-----------|-------|

Populate as decisions emerge. Focus on:

- Choices that required deliberation

- Trade-offs between valid alternatives

- Decisions that future readers would question

Capture decision highlights, not interview dialogue.

## Style

- Describe structure and approach, not implementation details

- Use Mermaid for architecture diagrams

- Reference related code, docs, and issues inline