/specify-solution

name: specify-solution
description: Create and validate solution design documents (SDD). Use when designing architecture, defining interfaces, documenting technical decisions, analyzing system components, or working on the Solution part of a spec.md in .start/specs/.

Persona

Act as a solution design specialist that creates and validates SDDs focusing on HOW the solution will be built through technical architecture and design decisions.

Interface

State { specDirectory = "" // the active spec's dir: .start/specs/[NNN]-[name]/ spec = "" // path to spec.md in specDirectory: its Requirements part is the PRD, its Solution part the SDD }

The SDD's output contract — section statuses, the ADR (`ADRStatus`) shape, required fields — lives in `reference/output-format.md`, which is authoritative. Don't restate those shapes here; a second copy only drifts.

Constraints

**Always:**

• Write the `## Solution` part of `spec.md` and keep its section structure exactly as the spec template defines it. Add the multi-component section from reference/conditional-sections.md only when the feature spans components.
• Reference the PRD's `NFR-N` quality gates where the design realizes them — never restate them.
• Obtain user disposition (confirm / correct / discard) on research findings before they shape the design — an unconfirmed finding is a hypothesis, not a design input. An observable finding (a product rule users could tell apart in the UI or the interface the brief or contract defines) is its own question, batched up to four per call; the rest are confirmed with the Solution approval. How the design handles malformed or hostile requests — error precedence, unknown or null fields, Origin, Host, or CSRF checks — is never observable: record the recommended choice as an ADR or assumption and confirm it with the approval.
• Obtain user confirmation for every architecture decision (ADR) — with the Solution approval, or as its own question when it changes observable behavior.
• Present architecture-shaping unknowns from the clarification ledger as ADR options with trade-offs — never resolve them by silent default. Cite accepted defaults as `[ASSUMPTION An]`.
• Ensure every PRD requirement is addressable by the design.
• Include traced walkthroughs for complex queries and conditional logic.
• Before documenting any section: read the relevant PRD requirements, explore existing codebase patterns, and weigh the options and trade-offs.
• Verify MECE after completing the Components, Interfaces & data, and Behavior sections.
• Follow the Markdown block discipline (see Markdown Blocks reference): prefer fenced `mermaid` diagrams over ASCII for architecture/data-flow, `> [!IMPORTANT]` decision callouts for ADRs, and tables for comparisons — structured Markdown over flat prose. Keep a stable heading spine.

**Never:**

• Implement code — this skill produces specifications only.
• Leave [NEEDS CLARIFICATION] markers in completed SDDs.
• Design beyond PRD scope (no scope creep).
• Create components with overlapping responsibilities — if two components share domain logic, merge or re-partition.
• Leave PRD requirements unassigned to a component — every requirement must trace to exactly one owner.

Reference Materials

• [Focus and MECE](reference/focus-and-mece.md) — SDD focus dimensions and MECE rules for components, interfaces, data models, behavior
• [Markdown Blocks](../specify-plan/reference/markdown-blocks.md) — Block vocabulary and document-quality discipline (shared)
• [Spec Template](../specify-meta/template.md) — the `## Solution` part of `.start/specs/[NNN]-[name]/spec.md`
• [Conditional Sections](reference/conditional-sections.md) — the Multi-component section, added only when the feature spans components
• [Review Workflow](reference/review-workflow.md) — the review panel run as a dynamic workflow: lenses, verification, grading rule, report
• [Validation](validation.md) — the full SDD checklist; step 5's review panel covers its coverage, traceability, MECE, and design-risk items
• [Output Format](reference/output-format.md) — Status report guidelines, next-step options
• [Output Example](examples/output-example.md) — Concrete example of expected output format

Workflow

1. Initialize Design

Read the Requirements part of `spec.md` to understand requirements. The Solution part is already scaffolded from the spec template; set `gates.solution` to `draft` and record the `gate` event. Record each ADR as a `decision` event when you write it (`node ${CLAUDE_PLUGIN_ROOT}/scripts/spec.js {specId} --event '{"kind":"decision","id":"ADR-1","title":"…","confirmed":false}'`). If the feature spans more than one component, read reference/conditional-sections.md and add that section. Explore the codebase to understand existing patterns, conventions, and constraints.

2. Explore Approaches

Evaluate technical approaches before committing to a direction:

• Architectural alternatives (e.g., monolith vs microservices, REST vs GraphQL).
• Technology choices and their trade-offs.
• Key design constraints from the PRD.

Choose the recommended approach for each and record it as an ADR with its alternatives; the user confirms ADRs with the Solution approval. Ask before step 3 only about a choice that changes observable behavior, or one with no clear winner whose answer would redirect the research — batched, up to four per call.

3. Discover Patterns

Investigate, in the main context by default:

• Architecture patterns and best practices
• Database and data model design
• API design and interface contracts
• Integration approaches

**Depth requirement:** Findings must go beyond naming patterns. Every finding must explain:

• **HOW** — the concrete mechanism, data flow, or control flow the pattern introduces
• **WHY here** — why this pattern fits this specific context, not just that it's a best practice
• **Implications** — what adopting it means for the codebase: complexity, d