luanmorenommaciel/agentspec/sdd-design

SDD Design — Architecture and Technical Specification (Phase 2)

Transform a validated DEFINE document into a comprehensive DESIGN document: system architecture with diagrams, key decisions with rationale (inline ADRs), an agent-matched file manifest, KB-grounded code patterns, and a testing strategy.

This skill owns the Phase 2 methodology. The design-agent is the executor (identity, tools, boundaries); the /design command is the entrypoint (argument surface and command-only flags). Contract-grade facts — inputs, outputs, status transitions — are canonical in ${CLAUDE_PLUGIN_ROOT}/sdd/architecture/WORKFLOW_CONTRACTS.yaml.

Inputs and Outputs

No DEFINE, no design. If requirements are missing or incomplete, stop and route to sdd-define first.

Knowledge Architecture

KB-FIRST RESOLUTION IS MANDATORY, NOT OPTIONAL.

┌─────────────────────────────────────────────────────────────────────┐
│  KNOWLEDGE RESOLUTION ORDER                                          │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  1. KB PATTERN LOADING (from DEFINE's KB domains)                   │
│     └─ Read: ${CLAUDE_PLUGIN_ROOT}/kb/{domain}/patterns/*.md → Code patterns      │
│     └─ Read: ${CLAUDE_PLUGIN_ROOT}/kb/{domain}/concepts/*.md → Best practices     │
│     └─ Read: ${CLAUDE_PLUGIN_ROOT}/kb/{domain}/quick-reference.md → Quick lookup  │
│                                                                      │
│  2. AGENT DISCOVERY (for file manifest)                             │
│     └─ Glob: ${CLAUDE_PLUGIN_ROOT}/agents/**/*.md → Available agents              │
│     └─ Extract: Role, capabilities, keywords from each              │
│     └─ Match: Files to agents based on purpose                      │
│                                                                      │
│  3. CONFIDENCE ASSIGNMENT                                            │
│     ├─ KB patterns + agent match found    → 0.95 → Design with KB   │
│     ├─ KB patterns only                   → 0.85 → Design, note gaps│
│     ├─ Agent match only                   → 0.80 → Design, validate │
│     └─ No KB, no agent match              → 0.70 → Research first   │
│                                                                      │
│  4. MCP VALIDATION (for novel patterns)                             │
│     └─ MCP docs tool (e.g., context7, ref) → Official docs          │
│     └─ MCP search tool (e.g., exa, tavily) → Production examples    │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

Design Confidence Matrix

Process

Step 1: Load Context

Read(.claude/sdd/features/DEFINE_{FEATURE}.md)   # problem, users, success criteria, acceptance tests
Read(${CLAUDE_PLUGIN_ROOT}/sdd/templates/DESIGN_TEMPLATE.md)   # artifact shape
Read(CLAUDE.md)                                  # project conventions
 
# Explore codebase for patterns:
Glob(**/*.py) | head -20
Grep("class |def ") | sample

Then load KB patterns from the domains named in the DEFINE (resolution order above) and assign a confidence score from the matrix. Validate novel patterns via MCP before relying on them; at 0.70, research before designing.

Step 2: Create Architecture

Design the solution:

┌─────────────────────────────────────────────────────────┐
│                   SYSTEM OVERVIEW                        │
├─────────────────────────────────────────────────────────┤
│  [Input] → [Component A] → [Component B] → [Output]     │
│              ↓                 ↓                        │
│         [Storage]         [External API]                │
└─────────────────────────────────────────────────────────┘

Step 3: Document Decisions (Inline ADRs)

For each significant choice:

### Decision: {Name}
 
| Attribute | Value |
|-----------|-------|
| **Status** | Accepted |
| **Date** | YYYY-MM-DD |
 
**Context:** Why this decision was needed
 
**Choice:** What we're doing
 
**Rationale:** Why this approach
 
**Alternatives Rejected:**
1.Option A - rejected because X
2.Option B - rejected because Y
 
**Consequences:**
-Trade-off we accept
-Benefit we gain

At least one decision must carry full rationale. Decisions are permanent — record the "why", not just the "what".

Step 4: Create the File Manifest (Agent Matching)

Discover specialists, then list every file the build will create or modify:

1. Glob ${CLAUDE_PLUGIN_ROOT}/agents/**/*.md to discover available agents
2. Extract role, capabilities, and keywords from each
3. Match files to agents:

Every file gets an agent or an explicit (general) fallback. Record the reasoning in the template's Agent Assignment Rationale section.

Step 5: Define Code Patterns

1. Load patterns from the KB domains
2. Adapt to the project's existing conventions (grep the codebase)
3. Provide copy-paste ready snippets for each key pattern

# Pattern: Handler structure (from ${CLAUDE_PLUGIN_ROOT}/kb/{domain}/patterns/{pattern}.md)
from config import load_config
def handler(request):
    """Entry point following KB pattern."""
    config = load_config()
    result = process(request, config)
    return {"status": "ok"}

Step 6: Plan the Testing Strategy

The strategy must cover every acceptance test in the DEFINE.

Step 7: Save, Update Statuses, Hand Off

1. Run the quality gate below, then write .claude/sdd/features/DESIGN_{FEATURE_NAME}.md following the template.
2. Update the DEFINE document — mandatory. Per the status transitions in WORKFLOW_CONTRACTS.yaml, when the design phase completes:

Skipping this leaves a stale "Ready for Design" status behind.

1. Hand off: suggest /build .claude/sdd/features/DESIGN_{FEATURE_NAME}.md as the next step.

Pipeline Architecture (Data Engineering Context)

When the DEFINE contains data engineering context — sources, volumes, freshness SLAs, schema contracts — the DESIGN must also include pipeline-specific sections:

1. Detect the DE context in the DEFINE
2. Load KB patterns from the airflow, streaming, data-modeling, and dbt domains
3. Fill the template's "Pipeline Architecture (if applicable)" sections: DAG diagram, partition strategy, incremental strategy, schema evolution plan, data quality gates

The section shapes (tables and diagram formats) are defined in DESIGN_TEMPLATE.md — follow them, do not invent variants.

Quality Gate

Every item must pass before the phase is declared complete:

PRE-FLIGHT CHECK
├─ [ ] KB patterns loaded from DEFINE's domains
├─ [ ] ASCII architecture diagram created and clear
├─ [ ] At least one decision with full rationale (inline ADR)
├─ [ ] Complete file manifest (all files listed)
├─ [ ] Agent assigned to each file (or marked general)
├─ [ ] Code patterns are syntactically correct and copy-paste ready
├─ [ ] Testing strategy covers acceptance tests
├─ [ ] No shared dependencies across deployable units
├─ [ ] No circular dependencies in the architecture
└─ [ ] DEFINE status updated to "✅ Complete (Designed)"

Contract Gate

Before handing off to /build, validate the document just written against this phase's contract — artifact DESIGN_{FEATURE_NAME}.md, phase design:

${CLAUDE_PLUGIN_ROOT}/tools/spec-linter/spec-lint .claude/sdd/features/DESIGN_{FEATURE_NAME}.md --phase design \
  --contracts-file ${CLAUDE_PLUGIN_ROOT}/sdd/architecture/WORKFLOW_CONTRACTS.yaml

Run it as ${CLAUDE_PLUGIN_ROOT}/tools/spec-linter/USAGE.md documents, and act on the verdict exactly as defined there. The exit-code contract and verdict semantics are owned by that document and by the contract_enforcement block (exit_code_contract, verdict_semantics) of ${CLAUDE_PLUGIN_ROOT}/sdd/architecture/WORKFLOW_CONTRACTS.yaml — which is also where this phase's binding is declared. Read them there rather than assuming: a contract assigns the severity of its own rules, so never reinterpret a verdict, and never assume one the linter did not return.

Anti-Patterns

Design Principles

Remember

"Design from patterns, not from scratch. Match specialists to tasks."

Mission: Transform validated requirements into comprehensive technical designs with KB-grounded patterns and agent-matched file manifests.

Core Principle: KB first. Confidence always. Ask when uncertain.