spec-design

Overview

This skill is used to execute D2 of the Spec-level "design phase": producing a reviewable Decision Doc / RFC, and can independently decide whether to first perform D0 (diversion: skip or not skip design) and D1 (research: optional) before execution.
Core principle: Gatekeeping first (spec-context) → Diversion first (D0) → Research on demand (D1) → Finalize decisions (D2). Under any pressure, guessing paths and proceeding with made-up details without SSOT are strictly prohibited.

Announce at the start: "I am using the spec-design skill to produce a design decision document (design/design.md / RFC)."

When to Use / Not to Use

Use Cases
- Users request to produce
```
design/design.md
```
  (RFC/Decision Doc), or require "completing design before entering implementation".
- You need to judge "whether the design phase can be skipped" and "whether research is needed first".
- You are asked to include interface fields/table structures/task breakdowns in the design document and are concerned about breaking document layering.
Do Not Use
- Requirements have not completed R1 (no
```
requirements/solution.md
```
  ): First complete requirement clarification and solution decision-making (see
```
spec-product-clarify
```
  ).
- Users explicitly only need implementation plans and tasks: Proceed directly to implementation (but
```
spec-context
```
  is still required).

Quick Reference

Hard Gatekeeping (Top Priority)：Before reading or writing any
```
{FEATURE_DIR}/design/*.md
```
, you must first execute
```
spec-context
```
to obtain
```
FEATURE_DIR=...
```
; stop immediately if it fails.
Shortest Path
- Skip Path: D0 decides to skip → Do not write
```
design/*.md
```
  → Enter implementation (fill in minimal decision information in
```
plan.md
```
  ).
- Regular Path: D0 (do not skip) → (Optional) D1 → D2 (write
```
design/design.md
```
  ) → Implementation.

Output Locations

D1 (Optional):
```
{FEATURE_DIR}/design/research.md
```
D2 (Mandatory if not skipped):
```
{FEATURE_DIR}/design/design.md
```

Minimal Templates

D1:

skills/spec-design-research/research-template.md

(Copy to

{FEATURE_DIR}/design/research.md

before filling)

D2:

skills/spec-design/design-template.md

(Copy to

{FEATURE_DIR}/design/design.md

before filling)

Decision Cheat Sheet

What You Are Judging	Trigger Signals (Any Hit)	Action
Whether to start writing any `design/*.md`	No `FEATURE_DIR=...` or `solution.md` is missing/untraceable	Stop; Fix context/supplement SSOT first
D0: Whether to skip the design phase	Single scope, no changes to external commitments, no critical uncertainties, acceptance criteria are sufficient	Can skip; Fill in minimal decision information in implementation `plan.md` instead
D0: Whether to must enter D2	Changes to external contracts/authorizations/data calibers; Data migration/rollback; Critical uncertainties; Wide cross-system impact	Do not skip; Proceed to D1 (on demand) → D2
D1: Whether research.md is needed	Solution correctness depends on unknown facts; Multiple solutions lack evidence; High-risk points need prior verification	Execute D1, write `design/research.md` and provide a verification checklist
D2: Whether implementation details/tasks/DDL are allowed to be written	Asked to "write them in for development convenience"	Reject layer mixing; Only write key external commitments + traceable links, sink details to contracts/ADR/implementation

Implementation Steps (Agent Behavior Specifications)

0) Gatekeeping: Locate

{FEATURE_DIR}

(Mandatory)

Red Line: Do not guess
.aisdlc/specs/...
, do not use the current working directory to assemble relative paths.

powershell

$repoRoot = (git rev-parse --show-toplevel)
. (Join-Path $repoRoot "skills\spec-context\spec-common.ps1")
$context = Get-SpecContext
$FEATURE_DIR = $context.FEATURE_DIR
Write-Host "FEATURE_DIR=$FEATURE_DIR"

If an error occurs above → Stop immediately (Do not generate/write any

design/*.md

content).

1) Read Minimal Required Input (Stop if Missing)

Mandatory Read (Demand-side SSOT)：
```
{FEATURE_DIR}/requirements/solution.md
```

On Demand:

{FEATURE_DIR}/requirements/prd.md

{FEATURE_DIR}/requirements/prototype.md

On Demand (Project-level):

project/memory/*

, related

project/contracts/

project/adr/

indexes

If Exists:

{FEATURE_DIR}/design/research.md

{FEATURE_DIR}/design/design.md

Stop Conditions (Do Not Proceed with Made-up Details):

Cannot find or read
```
requirements/solution.md
```
.
The In/Out, acceptance criteria, and key constraints of requirements cannot be traced from the input.

2) D0: Diversion (Whether to Skip the Design Phase)

2.1 When to "Skip the Design Phase Directly" (Consider skipping if any condition is met)

Single scope, clear boundaries: Barely involves cross-module collaboration and systemic risks
No changes to external commitments: No new/changed external contracts (API/events/authorizations/data calibers), and no data migration
No critical technical uncertainties: No prior research verification needed
Acceptance criteria are sufficient: Acceptance criteria are clear, testable, and traceable in
```
solution.md
```
(or
```
prd.md
```
)

2.2 When to "Not Skip" (Do not skip by default if any condition is hit)

New/changed external contracts (API/events/authorizations/data calibers), or need to update
```
project/contracts/
```
Risks of data migration/rollback exist, or need to add/update ADRs
Explicit critical uncertainties (performance/security/consistency/dependencies/compliance/gateway capabilities/storage strategies, etc.)
Involves multiple systems/teams/upstream-downstream parties, or the impact scope cannot be defined in one sentence

2.3 Override Rules (Prevent "Could Skip but Must Review")

Even if the skip criteria are met, do not skip (proceed to D2) if any of the following occurs:

Users/teams explicitly require an RFC for review and alignment
Similar changes have frequently led to rework/incidents recently, requiring decision documents to freeze specifications

2.4 Minimal Output of D0 (Can be unrecorded)

Output a quotable conclusion paragraph (within 3–7 reasons):

Conclusion: Skip / Do not skip
Basis: Corresponding to the above criteria (traceable to
```
solution.md
```
/ contract/ADR entry)
If skipped: List the minimal decision information that must be filled in implementation
```
plan.md
```
:
- Objectives, scope and boundaries, key constraints, acceptance criteria, verification checklist (Owner/Deadline/Signals/Actions)

3) D1: Research (Optional; Only Perform When Needed)

3.1 Signals to Trigger D1 (Perform if any is hit)

Solution correctness depends on unknown facts ("If X is not true, the solution will be completely overturned")
Multiple feasible directions exist, but lack evidence to support trade-offs
High-risk points exist in external contracts/migration/security/performance/consistency, requiring prior verification

3.2 When to Skip D1

Uncertainties have been evidenced in the input (key risks and verification checklists are already covered in
```
solution.md
```
/existing
```
research.md
```
)
This D2 is only a low-risk small-scale change with no critical unknowns

3.3 Minimal Structure of

design/research.md

(Write conclusions, not problem lists)

Red Line: Do not leave behind "To-Confirm Problem Lists / TODO Lists". Unknowns must be handled uniformly with "Assumptions + Verification Checklists".

TL;DR (3–7 lines): Current status + Highest risk + Recommended direction
Current Status and Problem Domain
Scope Boundaries and Invariants
Key Constraints
Risks and Verification Checklist (Mandatory): Risk/Assumption → Verification Method → Success/Failure Signals → Owner → Deadline → Next Actions
Alternatives and Trade-offs (Optional)

4) D2: Design (Decision Doc / RFC; Mandatory if not skipped)

4.1 Positioning of D2 (Write "Decisions", not "Implementations")

Only write: Why it is done this way, how boundaries are defined, solutions and trade-offs, key external commitments, how to verify, impact and migration/rollback key points.
Do not write: Implementation steps, task breakdowns, code-level details, itemized interface fields, DDL specifics.
- If external commitments on fields/compatibility must be included: Write "key points + traceable links" in this document, and sink details to
```
project/contracts/
```
  or ADRs.

4.2 Recommended Minimal Structure of

design/design.md

(Template)

Must use the minimal template to generate design.md (avoid structural drift):

Copy the content of
```
skills/spec-design/design-template.md
```
Paste it to
```
{FEATURE_DIR}/design/design.md
```
Fill in the placeholders according to the template (especially C4 L1–L3, alternative solutions, risks and verification checklist, traceable links)

Writing Constraints: Only retain minimal information that supports decision-making/acceptance/evolution; Do not add "To-Confirm Problems/TODO" sections; Do not write implementation details/task breakdowns/field lists/DDL.

4.3 D2-DoD (All items are mandatory)

In/Out are clear and traceable to
```
solution.md
```
Recommended solution is clearly explained with C4 L1+L2+L3, with traceable layers
Key decisions explain "why this is chosen/why alternatives are rejected"
Uncertainties have been converged: All unknowns are included in "Assumptions + Verification Checklist" (Owner/Deadline/Actions are clear)

Red Flags (Stop and correct immediately if any occurs)

Start writing
```
design/*.md
```
without first obtaining
```
FEATURE_DIR=...
```
Continue writing design when
```
requirements/solution.md
```
cannot be found (= making up details)
Leave unknowns hanging with "To-Confirm Problem Lists / TODO" (Should be changed to "Assumptions + Verification Checklist")
Write D2 as implementation specifications: Task breakdowns, implementation steps, field/DDL details
Missing alternative solutions or verification checklists (resulting in inability to review/implement)

Anti-Rationalization Under Pressure (Common Excuses → Corresponding Actions)

Common Excuses	Corresponding Rules / Actions
"Just write something in `design/design.md` casually, we can move it later"	Path guessing is prohibited: First obtain `FEATURE_DIR` via `spec-context` ; Stop otherwise
"We can produce a draft first even with incomplete information, and fill it in later"	Making up details is prohibited: Stop if `solution.md` is missing or untraceable; Rewrite unknowns as "Assumptions + Verification Checklist"
"Supervisor/PM said no gatekeeping/no need to check documents"	Gatekeeping is a hard rule: Stop if `Get-SpecContext` fails; Do not make exceptions due to authority pressure
"To speed up development, write tasks/DDL/fields into the design"	Layer mixing is rejected: D2 only writes decisions and key external commitments + traceable links; Sink details to contracts/ADR/implementation
"No time to prepare alternatives/verification checklists"	Alternatives and verification are part of D2-DoD: Missing them will lead to inability to review/rework; Shorten the main text rather than delete DoD items

Common Mistakes (and Fixes)

Mistake: Under pressure, "write first and ask questions later", generating documents first then supplementing input.
Fix: Pass the
```
spec-context
```
and
```
solution.md
```
gatekeeping first; Stop if missing, and clearly write down blocking items.
Mistake: Treat research as "looking up information", writing a lot of background but no verification checklist.
Fix: Convert all unknowns into "Risk/Assumption → Verification Method → Signals → Owner/Deadline/Actions".
Mistake: PM requires writing tasks/interfaces/table structures into the design, resulting in layer mixing.
Fix: Only retain "key external commitments + traceable links" in the design document; Move implementation details to implementation or contracts/ADRs.

spec-design

NPX Install

Tags

SKILL.md Content (Chinese)

spec-design

Overview

When to Use / Not to Use

Quick Reference

Implementation Steps (Agent Behavior Specifications)

0) Gatekeeping: Locate
`{FEATURE_DIR}`
(Mandatory)

1) Read Minimal Required Input (Stop if Missing)

2) D0: Diversion (Whether to Skip the Design Phase)

2.1 When to "Skip the Design Phase Directly" (Consider skipping if any condition is met)

2.2 When to "Not Skip" (Do not skip by default if any condition is hit)

2.3 Override Rules (Prevent "Could Skip but Must Review")

2.4 Minimal Output of D0 (Can be unrecorded)

3) D1: Research (Optional; Only Perform When Needed)

3.1 Signals to Trigger D1 (Perform if any is hit)

3.2 When to Skip D1

3.3 Minimal Structure of
`design/research.md`
(Write conclusions, not problem lists)

4) D2: Design (Decision Doc / RFC; Mandatory if not skipped)

4.1 Positioning of D2 (Write "Decisions", not "Implementations")

4.2 Recommended Minimal Structure of
`design/design.md`
(Template)

4.3 D2-DoD (All items are mandatory)

Red Flags (Stop and correct immediately if any occurs)

Anti-Rationalization Under Pressure (Common Excuses → Corresponding Actions)

Common Mistakes (and Fixes)