design-doc-generate Skill

<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>

Agent Skills: design-doc-generate

Install this agent skill to your local

Skill Files