design-doc-generate

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

<objective>
Generate design documents for Validate mode work items (Checkpoint 1).
</objective>

<triggers>
  - Work item has complexity: high
  - Work item has mode: validate
  - Design review required before implementation
</triggers>

<degrees_of_freedom>
  **LOW** — Follow the design doc structure precisely. Decisions must have rationale.
</degrees_of_freedom>

<llm critical="true">
  <mandate>Design doc MUST be approved before implementation</mandate>
  <mandate>Document DECISIONS with RATIONALE, not just choices</mandate>
  <mandate>Keep concise — enough detail to implement, no more</mandate>
  <mandate>Include risks upfront — don't hide complexity</mandate>
</llm>

<flow>
  <step n="1" title="Analyze Work Item">
    <action>Read work item from .specs-fire/intents/{intent-id}/work-items/{id}.md</action>
    <action>Identify key design decisions needed</action>
    <action>Assess domain modeling needs</action>
    <action>Identify integration points</action>
  </step>

  <step n="2" title="Gather Context">
    <action>Review project standards (.specs-fire/standards/)</action>
    <action>Check existing codebase patterns</action>
    <action>Identify similar implementations to reference</action>
  </step>

  <step n="3" title="Draft Key Decisions">
    <action>For each decision point:</action>
    <substep>Identify options considered</substep>
    <substep>Evaluate trade-offs</substep>
    <substep>Select recommended choice</substep>
    <substep>Document rationale</substep>

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

  <step n="4" title="Define Domain Model" if="has_domain_complexity">
    <action>Identify entities (things with identity)</action>
    <action>Identify value objects (immutable values)</action>
    <action>Identify domain events (if event-driven)</action>
    <action>Map relationships</action>
  </step>

  <step n="5" title="Design Technical Approach">
    <action>Create component diagram (ASCII)</action>
    <action>Define API contracts (if applicable)</action>
    <action>Specify database changes (if applicable)</action>
    <action>Document data flow</action>
  </step>

  <step n="6" title="Identify Risks">
    <action>List potential risks</action>
    <action>Assess impact (high/medium/low)</action>
    <action>Propose mitigations</action>

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

  <step n="7" title="Create Implementation Checklist">
    <action>Break down into implementation steps</action>
    <action>Order by dependency</action>
    <action>Keep granular but not excessive</action>
  </step>

  <step n="8" title="Present Design Doc">
    <checkpoint message="Design document ready for review">
      <output>
        # 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>
  </step>

  <step n="9" title="Handle Response">
    <check if="response == y">
      <action>Generate design doc using template: templates/design.md.hbs</action>
      <action>Save to: .specs-fire/intents/{intent-id}/work-items/{id}-design.md</action>
      <action>Mark checkpoint 1 as passed</action>
      <output>
        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>
  </step>
</flow>

<output_artifacts>

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

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