Use when SRS doc exists but no design doc and no feature-list.json - take the approved SRS as input and produce an architecture/design document focused on HOW to build it
LANGUAGE RULE: You MUST respond to the user in Chinese (Simplified). All generated documents, reports, and user-facing output must be written in Chinese. Skill names, code identifiers, and JSON field names remain in English.
Take the approved SRS as input. Propose implementation approaches, get section-by-section design approval, and produce a design document that answers HOW — while the SRS answers WHAT.
<HARD-GATE> Do NOT invoke any implementation skill, write any code, scaffold any project, run init_project.py, or take any implementation action until you have presented a design and the user has approved it. This applies to EVERY project regardless of perceived simplicity. </HARD-GATE>The SRS describes WHAT the system must do. The design document describes HOW. Even when requirements are crystal clear, the implementation approach (architecture, data model, tech stack choices) needs explicit decisions and user approval. Skipping design causes mid-session corrections and rework.
You MUST create a TodoWrite task for each of these items and complete them in order:
docs/plans/*-srs.mddocs/plans/YYYY-MM-DD-<topic>-design.md and commitlong-task:long-task-atsThe terminal state is invoking long-task-ats. Do NOT invoke any other implementation skill.
docs/plans/*-srs.mddocs/plans/*-ucd.md (if it exists — only present for UI projects)AskUserQuestion before Step 2docs/templates/design-template.md (the default template shipped with this skill).md file containing at least one ## headingPresent 2-3 implementation approaches with explicit trade-offs:
## Approach A: [Name]
**How it works**: [1-2 sentences]
**Pros**: [bullet list]
**Cons**: [bullet list]
**Best when**: [conditions]
**NFR impact**: [how this approach affects the SRS NFR thresholds]
**Third-party dependencies**: [key libraries/frameworks this approach requires, with versions]
## Approach B: [Name]
...
## Recommendation: Approach [X]
**Reason**: [why this fits best given the SRS constraints and NFRs]
Key: Each approach must be evaluated against the SRS constraints and NFR thresholds. An approach that cannot meet a "Must" NFR is disqualified.
For non-trivial projects, break the design into sections and get approval per section:
graph) showing layers/packages/modules and dependency directionsgraph) showing runtime components and interactionsclassDiagram) — classes/modules, attributes, methods, relationshipssequenceDiagram) or flow diagram (Mermaid flowchart)erDiagram) where applicablefeature-list.json; group related right-sized FRs (already validated by SRS G+S heuristics) into vertical slices; include Mapped FRs column for traceabilitygraph) identifying the critical pathFeature sizing is upstream: FRs are right-sized at the Requirements phase via bidirectional granularity analysis (G1-G6 split + S1-S4 group). §10.2 groups these right-sized FRs into implementation features. Each row should map 1+ related FRs into a vertical slice that productively fills one Worker session (~50% of context window). Feature counts in the scaling table below refer to the final §10.2 row count.
Present each section. Wait for user feedback. Incorporate changes before moving to the next.
For simple projects (< 5 features): Combine all sections into a single approval step, but still include the required diagrams and dependency versions.
Skip this step if docs/rules/ does not exist or contains only a greenfield stub.
If docs/rules/ is populated with convention scan results (from Phase 0-pre codebase scanner):
docs/rules/*.md files — coding-style.md, coding-constraints.md, build-and-compilation.md, commit-conventions.mdcoding-constraints.mdcoding-constraints.mdcoding-constraints.mdcoding-constraints.md (tool name + config path + run command only — do not read config contents)coding-style.md (summary table)coding-constraints.mdbuild-and-compilation.mdcommit-conventions.mdSave the approved design to docs/plans/YYYY-MM-DD-<topic>-design.md.
Read the template found in Step 2 (user-specified or default docs/templates/design-template.md):
Date, Status, SRS Reference, Template path)Before transitioning to ATS, mechanically verify cross-feature integration coherence:
Present any flagged issues to the user. Resolve before proceeding to ATS.
Once the design document is saved and committed:
long-task:long-task-ats to generate the Acceptance Test Strategy| Project Size | Features | Design Depth |
|---|---|---|
| Tiny | 1-5 | Single paragraph approach + 1 approval step; logical view + 1 feature diagram + dependency table + simplified dev plan |
| Small | 5-20 | 2-3 approach options + combined section approval; logical view + key feature diagrams + dependency table + milestone plan |
| Medium | 20-50 | Full multi-section approval; all architecture views + per-feature diagrams + full dependency analysis + detailed dev plan |
| Large | 50-200+ | Full multi-section approval; comprehensive diagrams for every feature group + dependency compatibility matrix + phased dev plan with risk register |
For projects with many features, §4.N sections are written at different depths to manage context window constraints:
| Project Size | §4.N Content per Feature |
|---|---|
| Small (< 20) | Full: overview + class diagram + behavioral diagram + design notes + integration surface |
| Medium (20-50) | Full for P0/P1 features; Thin for P2/P3 features |
| Large (50+) | Thin for ALL features: overview + key types + integration surface only |
Thin §4.N format:
### 4.N Feature: <Name> (FR-xxx)
#### 4.N.1 Overview
[1-2 sentences]
#### 4.N.2 Key Types
[List the main classes/types this feature introduces, with one-line purpose each]
#### 4.N.6 Integration Surface
[Provides/Requires tables referencing §6.2]
This is safe because the feature-design SubAgent (Worker Step 4) produces the full class/sequence/flow/algorithm design with access to §6.2 contracts. The thin §4.N serves as an integration specification, not a complete design.
| Rationalization | Correct Response |
|---|---|
| "The SRS already implies the architecture" | SRS describes WHAT, not HOW. Present options. |
| "There's only one way to build this" | Present at least 2 approaches. Even obvious choices benefit from stated trade-offs. |
| "I already know the best approach" | Present options, let the user choose |
| "The user seems impatient, I'll skip design" | Explain the value briefly, then run efficiently |
| "I'll design as I go" | Upfront design is cheaper than mid-session corrections |
| "Let me re-clarify requirements here" | Requirements belong in the SRS. If missing, note as Open Question and resolve with user before design. |
All architectural and design views MUST use Mermaid syntax. This ensures:
| Section | Diagram Type | Mermaid Syntax | Required? |
|---|---|---|---|
| Architecture Logical View | Layered package diagram | graph TB | Always |
| Architecture Components | Component interaction | graph LR | Always |
| Key Feature — Structure | Class diagram | classDiagram | Per feature |
| Key Feature — Behavior | Sequence diagram | sequenceDiagram | Per feature (at least one behavioral) |
| Key Feature — Logic | Flow/decision diagram | flowchart TD | Per feature (at least one behavioral) |
| Data Model | ER diagram | erDiagram | If persistent storage |
| Dependency Graph | Dependency tree | graph LR | If > 3 third-party deps |
| Development Plan | Critical path | graph LR | Always |
+/-/#) and key methods1.2.3 or a constrained range ^1.2.0 / >=1.2,<2.0; never use latest or omit versionThe development plan section bridges the design document to the Init phase. It MUST include:
feature-list.json.The Init phase uses this plan to populate feature-list.json with correct priority ordering, paired grouping, and dependency chains.
Called by: using-long-task (when SRS + UCD exist, no design doc, no feature-list.json) or long-task-ucd (Step 8)
Requires: Approved SRS at docs/plans/*-srs.md; optionally approved UCD at docs/plans/*-ucd.md (for UI projects); optionally docs/rules/*.md (codebase conventions from Phase 0-pre scan)
Chains to: long-task-ats (after design approval)
Produces: docs/plans/YYYY-MM-DD-<topic>-design.md (includes §13 Codebase Conventions if docs/rules/ exists)