Sdd Writer Iterative

Prerequisites

Before activating, ensure:

1. Clear task description -- the user has described what they want (even if vague, Phase 1 will clarify)
2. Repository access -- ability to read files in the repo to ground the design
3. Success criteria defined -- either from the user or inferred in Phase 1
4. Output directory exists -- docs/design/ (create if missing)

SDD Structure Specification

Every SDD MUST contain exactly these 15 sections in this order:

Section 1: Executive Summary

• Content: 2-3 paragraphs for non-technical stakeholders
• Audience: Product managers, designers, non-engineers
• Tone: No jargon; explain WHAT, WHY, and HIGH-LEVEL HOW
• Length: 150-300 words

Section 2: Problem Statement

• Content: Current pain points, user/business impact, cost of inaction
• Format: Narrative with quantitative impact where possible
• Must answer: "What happens if we don't build this?"

Section 3: Goals / Non-Goals

• Goals: 3-5 items using RFC 2119 language (MUST/SHOULD/MAY)
• Priority: P0 (must-have), P1 (should-have), P2 (nice-to-have)
• Non-Goals: Frame as "This SDD does NOT cover..."
• Purpose: Prevent scope creep; each goal must be testable

Section 4: Functional Requirements

• Format: Structured requirement IDs

FR-001: [MUST] <description>
  - Input: <trigger>
  - Output: <expected result>
  - Acceptance: <verification method>

FR-002: [SHOULD] <description>
  - Input: <trigger>
  - Output: <expected result>
  - Acceptance: <verification method>

Section 5: Non-Functional Requirements

• Categories to cover:
  • Performance: Lighthouse score targets, load time budgets
  • Accessibility: WCAG 2.1 AA compliance
  • Responsiveness: Breakpoints (375px, 768px, 1024px+)
  • Browser support: Modern evergreen browsers
  • Dark mode: Must work with CSS custom property system
  • SEO: Metadata requirements

Section 6: Assumptions & Constraints

Section 7: Proposed Solution

• Required elements:
  • Architecture overview with component hierarchy
  • Data flow description
  • TypeScript interface definitions
  • Technology choices with justification
  • File paths for new/modified files
  • At least one Mermaid diagram

Mermaid diagram template:

```mermaid
graph TD
    A[Page Component] --> B[Section Component]
    B --> C[Sub-component 1]
    B --> D[Sub-component 2]
    C --> E[shadcn/ui primitive]
```

Repo patterns to reference:

Section 8: Security / Privacy / Compliance

• XSS prevention (sanitize user-facing content)
• Dependency security (pnpm audit)
• External link safety (rel="noopener noreferrer", target="_blank")
• Content Security Policy considerations
• No sensitive data in client bundle

Section 9: Observability & Operations

• Error boundaries for graceful failure
• pnpm build validation (no build errors)
• Lighthouse performance/accessibility scores
• Console error monitoring in development
• loading.tsx and error.tsx for user feedback

Section 10: Rollout / Migration Plan

• Feature branch workflow: feature/<short-name> from main
• PR with description referencing the SDD
• Migration steps if modifying existing pages/components
• Rollback: revert PR if issues found
• No feature flags needed for static site features

Section 11: Testing Strategy

Section 12: Risks & Mitigations

• Minimum 3 risks required
• Be realistic, not alarmist
• Include technical AND process risks

Section 13: Open Questions

OQ-001: <question>
  - Context: <why this matters>
  - Proposed resolution: <suggestion>
  - Owner: <who answers -- usually "Raph" or "TBD">

HARD RULE: Never invent facts. If uncertain, add an Open Question.

Section 14: Appendix

• Alternative approaches considered (with rejection reasons)
• Reference links (documentation, examples, inspiration)
• Additional Mermaid diagrams if needed
• Research notes

Section 15: Iteration History

• Empty in SDD v1
• After Loop 1: Full critique log, decision table, list of modified sections
• After Loop 2: Full critique log, decision table, list of modified sections

Iterative Review Process

Overview

Two self-review loops transform SDD v1 into SDD v3 (final):

SDD v1 (draft) --> Loop 1 (20 critiques) --> SDD v2 --> Loop 2 (20 critiques) --> SDD v3 (final)

Critique Point Template

Each critique must include all four fields:

Critique #<N>:
  Section: <number>. <section name>
  Issue: <specific problem or gap identified>
  Risk/Impact: <what could go wrong if not addressed>
  Suggestion: <concrete, actionable improvement>

Accept/Reject Decision Criteria

ACCEPT if the critique:

REJECT if the critique:

Decision Table Format

Each loop produces a 20-row decision table:

Loop Documentation Template

After each loop, append to Section 15:

### Loop <N> (SDD v<N> -> v<N+1>)

**Date**: <YYYY-MM-DD>
**Reviewer persona**: Principal Engineer

#### Critiques

<all 20 critique points>

#### Decision Table

<20-row table>

#### Summary
- Accepted: <N>/20
- Rejected: <N>/20
- Sections modified: <list>

#### Accepted Changes Applied
<brief description of each change made>

Process Flow

Phase 1: Infer Intent
    |
    v
Phase 2: Read Repo Context
    |
    v
Phase 3: Write SDD v1 (15 sections)
    |
    v
Phase 4: Loop 1 -- 20 critiques --> accept/reject --> SDD v2
    |
    v
Phase 5: Loop 2 -- 20 NEW critiques --> accept/reject --> SDD v3
    |
    v
Phase 6: Save to docs/design/ + Generate Summary

Grounding in Repository Context

What to Look For

Grounding Rules

• ALWAYS read existing files before proposing new patterns
• PREFER reusing existing patterns over inventing new ones
• DOCUMENT why a new pattern is needed when deviating
• REFERENCE specific file paths in the Proposed Solution section

File Output Convention

Path: docs/design/<YYYY-MM-DD>-<short-title>.md

If docs/design/ does not exist, create it before saving.

Completion Summary Template

## SDD Generation Summary

| Metric | Value |
|--------|-------|
| Loops completed | 2 |
| Loop 1: Critiques generated | 20 |
| Loop 1: Accepted | <N> |
| Loop 1: Rejected | <N> |
| Loop 2: Critiques generated | 20 |
| Loop 2: Accepted | <N> |
| Loop 2: Rejected | <N> |
| Total critiques | 40 |
| Total accepted | <N> |
| Total rejected | <N> |
| Acceptance rate | <N>% |

### Rejection Themes
| Category | Count | Examples |
|----------|-------|---------|
| Out of scope | <N> | ... |
| Premature optimization | <N> | ... |
| Stylistic preference | <N> | ... |
| Lacks evidence | <N> | ... |
| Already addressed | <N> | ... |

### Output
- **File**: docs/design/<filename>.md
- **Sections**: 15
- **Diagrams**: <N>
- **Open Questions**: <N>
- **Functional Requirements**: <N>
- **Risks Identified**: <N>

Hard Rules

1. Exactly 2 review loops, no more, no less
2. Exactly 20 critique points per loop (40 total)
3. Apply ONLY accepted items; rejected items MUST NOT modify the SDD
4. Document both loops with full iteration history in Section 15
5. No hallucinations; unknowns go in Open Questions (Section 13)
6. At least one Mermaid diagram required in Section 7
7. Save to docs/design/<YYYY-MM-DD>-<short-title>.md
8. Generate the completion summary with statistics
9. All 15 sections required; no skipping, combining, or reordering
10. Ground in repo context; check existing patterns before proposing new ones

Success Criteria

• All 6 phases completed in order
• Repository context read (not assumed) in Phase 2
• All 15 SDD sections present with meaningful content
• At least one Mermaid diagram in Section 7
• Loop 1: exactly 20 critiques with full decision table
• Loop 2: exactly 20 NEW critiques with full decision table
• Only accepted changes applied to the SDD
• Full iteration history in Section 15
• Final SDD saved to correct path
• Completion summary with statistics and rejection themes

Anti-Patterns

DON'T

• Skip or combine review loops
• Generate more or fewer than 20 critiques per loop
• Apply rejected changes to the SDD
• Invent information when uncertain
• Accept or reject all critiques (aim for thoughtful mix)
• Write empty or placeholder sections
• Skip the Mermaid diagram
• Forget to save the file
• Forget to generate the summary
• Reuse Loop 1 critiques in Loop 2

DO

• Follow all 6 phases in order
• Ground designs in actual repo file reads
• Document uncertainties in Open Questions
• Make thoughtful accept/reject decisions with reasoning
• Include testable acceptance criteria
• Reference real file paths and patterns
• Create the output directory if needed
• Produce the full completion summary

Related Skills