• 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).

• 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

design/*.md

FEATURE_DIR=...

solution.md

plan.md

design/research.md

Red Line: Do not guess

.aisdlc/specs/...

, do not use the current working directory to assemble relative paths.

$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"

design/*.md

• 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

• Cannot find or read

  requirements/solution.md

  .
• The In/Out, acceptance criteria, and key constraints of requirements cannot be traced from the input.

• 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

  )

• 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

• 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

• 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)

• 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

• 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

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)

• 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.

1. Copy the content of

   skills/spec-design/design-template.md

2. Paste it to

   {FEATURE_DIR}/design/design.md

3. 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.

• 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)

• 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)

• 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.