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
Invoke interview:plan to clarify requirements. 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:
| Decision | Choice | Alternatives | Rationale | Notes | |----------|--------|--------------|-----------|-------| | Brief description | What we chose | What we didn't | Why this choice | Caveats, follow-ups |
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