design-doc-generate - SKILL.md Agent Skill

name: design-doc-generate description: Generate design documents for Validate mode work items (Checkpoint 1). Required for high-complexity items. version: 1.0.0

Generate design documents for Validate mode work items (Checkpoint 1). - Work item has complexity: high - Work item has mode: validate - Design review required before implementation **LOW** — Follow the design doc structure precisely. Decisions must have rationale. Design doc MUST be approved before implementation Document DECISIONS with RATIONALE, not just choices Keep concise — enough detail to implement, no more Include risks upfront — don't hide complexity Read work item from .specs-fire/intents/{intent-id}/work-items/{id}.md Identify key design decisions needed Assess domain modeling needs Identify integration points Review project standards (.specs-fire/standards/) Check existing codebase patterns Identify similar implementations to reference For each decision point: Identify options considered Evaluate trade-offs Select recommended choice Document rationale

<output_format>
  | Decision | Choice | Rationale |
  |----------|--------|-----------|
  | ... | ... | ... |
</output_format>

Identify entities (things with identity) Identify value objects (immutable values) Identify domain events (if event-driven) Map relationships Create component diagram (ASCII) Define API contracts (if applicable) Specify database changes (if applicable) Document data flow List potential risks Assess impact (high/medium/low) Propose mitigations

<output_format>
  | Risk | Impact | Mitigation |
  |------|--------|------------|
  | ... | ... | ... |
</output_format>

Break down into implementation steps Order by dependency Keep granular but not excessive # Design: {work-item-title}

    ## Summary
    {brief description}

    ## Key Decisions
    {decisions table}

    ## Technical Approach
    {component diagram, API contracts}

    ## Risks
    {risks table}

    ## Implementation Checklist
    {ordered steps}

    ---
    This is Checkpoint 1 of Validate mode.

    Approve design? [Y/n/edit]
  </output>
</checkpoint>

Generate design doc using template: templates/design.md.hbs Save to: .specs-fire/intents/{intent-id}/work-items/{id}-design.md Mark checkpoint 1 as passed Design approved. Ready for implementation planning.

    Route to Builder for Checkpoint 2 (implementation plan)? [Y/n]
  </output>
</check>
<check if="response == edit">
  <ask>What changes are needed?</ask>
  <action>Incorporate feedback</action>
  <goto step="8"/>
</check>
<check if="response == n">
  <output>Design rejected. What concerns need to be addressed?</output>
  <action>Gather feedback, revise approach</action>
  <goto step="3"/>
</check>

Artifact	Location	Template
Design Doc	`.specs-fire/intents/{intent-id}/work-items/{id}-design.md`	`./templates/design.md.hbs`

Work item analyzed for design decisions Key decisions documented with rationale Domain model defined (if applicable) Technical approach specified Risks identified with mitigations Implementation checklist created Design doc approved at checkpoint Design doc saved to correct location