spec-design

spec-design

Overview

This skill is D2 worker skill: it is only responsible for producing a reviewable decision document (Decision Doc / RFC) to {FEATURE_DIR}/design/design.md。
routing authority: whether to skip design (D0) and whether research (D1) is needed are both determined by using-aisdlc as the sole router; this skill does not make routing decisions.
Core principles:gate first (spec-context) → mandatorily consume impact analysis and project knowledge base → write decisions to disk (D2). Under any pressure, guessing paths is prohibited, and proceeding by making things up when the SSOT is missing is prohibited.

At the start, announce:"I am using the spec-design skill to produce the design decision document (design/design.md / RFC)."

When to use / not use

• When to use
  • The user requests the production of design/design.md(RFC/Decision Doc), or "do the design then enter implementation".
  • You are asked to stuff interface fields/table structures/task breakdowns into the design document, and you are worried that the document layering will be broken.
• Do not use for
  • Requirements have not yet completed R1 (no requirements/solution.md): first complete requirements clarification and solution decision (see spec-product-clarify）。
  • The user explicitly only wants the implementation plan and tasks: go directly to implementation

Quick reference

• Hard gate (first priority): before any read/write of {FEATURE_DIR}/design/*.md , you must first execute spec-context to obtain context and echo FEATURE_DIR=...(allows (reuse)); stop immediately on failure.

• D2 mandatory input (second priority): D2 must read {FEATURE_DIR}/requirements/solution.md#impact-analysis, and based on that mandatorily read the full text of affected module component pages and the full text of related ADRs; if they cannot be read, this must be explicitly marked CONTEXT GAP, and must not be silently skipped.

• Output location

  • D2 (required when not skipped):{FEATURE_DIR}/design/design.md

• Minimal template

  • D2：<本SKILL.md目录>/assets/design-template.md(copy to {FEATURE_DIR}/design/design.md then fill in)

Reminder: when discussion arises about "whether to skip design / whether research is needed", return to using-aisdlc for the routing decision; this skill only executes D2.

Implementation steps (Agent behavior specification)

0) Gate (must pass first, otherwise stop)

REQUIRED SUB-SKILL: executing spec-context to obtain context and echo FEATURE_DIR=...(allows (reuse)）。

• spec-context failure → stop

If the above reports an error → stop immediately(do not generate/write any design/*.md content).

1) Read the minimal necessary inputs (stop if missing)

• Required reading (requirements-side SSOT)：{FEATURE_DIR}/requirements/solution.md
• Required reading (impact analysis SSOT)：{FEATURE_DIR}/requirements/solution.md#impact-analysis(extract from it: list of affected modules, invariants to comply with, related ADRs, cross-module impact)
• As needed：{FEATURE_DIR}/requirements/prd.md、{FEATURE_DIR}/requirements/prototype.md
• Required reading (project-level, mandatory)：
  • project/memory/*(business/technical/structural/terminology)
  • project/components/index.md(cross-module dependency graph/interaction entry point)
  • project/adr/index.md(ADR index)
  • Affected modules obtained from impact analysis: read project/components/{module}.md in full(including ## API Contract / ## Data Contract / ## State Machines & Domain Events and other stable anchors)
  • Related ADRs obtained from impact analysis: read project/adr/{adr-id}.md in full
• if present：{FEATURE_DIR}/design/research.md、{FEATURE_DIR}/design/design.md

Stop conditions (must not hallucinate and continue):

• Cannot find or cannot read requirements/solution.md。
• The requirement's In/Out, acceptance criteria, and key constraints cannot be traced from the input.

Hard requirements (must not be downgraded to "read-only index/read-only part"):

• The component pages of affected modules and related ADRs must either be read in full successfully, or be explicitly marked in design/design.md as CONTEXT GAP。
• Prohibitedto replace full-text reading with "the impact-analysis summary/index page" and claim "aligned/compliant".
• If pressure prevents completing the full-text reading: the DoD must be marked as unmet in the D2 output, and the blocking items must be clearly stated (rather than "check it as passed first, and fill it in later").

2) D2: design (decision document / RFC)

2.1 Positioning of D2 (write "decisions", not "implementation")

• Only write: why do it this way, how to draw the boundaries, options and trade-offs, key external commitments, how to verify, and key impact and migration/rollback points.
• Do not write: implementation steps, task breakdown, code-level details, item-by-item listing of interface fields, DDL details.
  • If fields/compatibility must be externally committed: write "key points + traceability links" in this document, and push details down to project/contracts/ or the ADR.
  • If the project uses component pages as the contract SSOT: prefer pushing details down to the corresponding project/components/{module}.md#api-contract/#data-contract(aligned with this repository's Discover module page structure).

2.2 design/design.md Recommended minimal structure (template)

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

1. Copy <本SKILL.md目录>/assets/design-template.md the contents of
2. Paste into {FEATURE_DIR}/design/design.md
3. Fill in the placeholders according to the template (especially C4 L1–L3, alternatives, risks and verification checklist, traceability links)

Writing constraints: keep only the minimal information that supports decisions/acceptance/evolution; do not add a "pending questions/TODO" section; do not write implementation details/task breakdown/field lists/DDL.

2.3 D2-DoD (none may be missing)

• In/Out are clear and can be traced to solution.md
• The recommended solution is explained clearly using C4 L1+L2+L3 with traceable layers
• Key decisions explain "why choose it/why not choose the alternatives"
• Alignment with the existing system has been completed(based on solution.md#impact-analysis）：
  • For each affected module: complete thecontract compatibility statement(compatible/extended/breaking change), and cite the specific invariants of the corresponding component page #api-contract / #data-contract specific invariants
  • For each related ADR: complete theADR compliance statement(compliant/needs new/needs modification)
  • For the state machines/domain events involved: complete theimpact statement(cite component page ## State Machines & Domain Events）
  • Based on the dependency graph: complete thecross-module impact confirmation
• Uncertainty has converged: all unknowns have entered the "assumptions + verification checklist" (Owner/deadline/action are explicit)

DoD decision rules (to prevent "treating CONTEXT GAP as completion"):

• If any affected module component page or related ADR contains CONTEXT GAP, then the item "alignment with the existing system is complete"must not be checked as passed; this must be explicitly stated in D2 as a blocker/risk, and a completion path must be given (read the full text / complete the knowledge base / add a new ADR).

Red flags (if any appears, stop and correct course)

• Without first obtaining FEATURE_DIR=... start writing design/*.md
• Cannot find requirements/solution.md and still continue writing the design (= making things up)
• Use "pending confirmation question list / TODO" to leave unknowns dangling (should be changed to "assumptions + verification checklist")
• Write D2 as an implementation spec: task breakdown, implementation steps, field/DDL details
• Lack of alternatives or lack of a verification checklist (making review impossible / implementation impossible)
• Only read project/adr/index.md / project/components/index.md and then claim "already aligned with the existing system"
• Only read some affected modules or only some ADRs and then claim "already aligned/compliant"
• Use the impact-analysis summary instead of the full component pages/ADRs, but do not label CONTEXT GAP
• Treat CONTEXT GAP as a reason that "alignment is complete" (this is a DoD failure signal, not a pass signal)

Anti-rationalization under pressure (common excuses → corresponding actions)

Common excuses	Corresponding rule / action
"Just write it anywhere for now to design/design.md, and move it later"	Do not guess paths: first spec-context obtain FEATURE_DIR; otherwise stop
"Even if the information is incomplete, we can produce a draft first and fill it in later"	Do not make things up: if solution.md is missing or untraceable, stop; rewrite unknowns as "assumptions + verification checklist"
"The manager/PM says no gate/no checking documents"	The gate is a hard rule:Get-SpecContext if it fails, stop; do not make an exception because of authority pressure
"For faster development, write all tasks/DDL/fields into the design"	Refuse layer mixing: D2 should contain only decision and external commitment points + traceability links; details go into contracts/ADR/implementation
"No time to do alternatives/verification checklist"	Alternatives and verification are part of D2-DoD: missing them will make review impossible/rework likely; rather shorten the main text than delete DoD items
"The module pages/ADRs are too long, don't read them for now; the impact-analysis summary is enough"	Do not use summaries to fake alignment: component pages and ADRs must either be read in full or labeled CONTEXT GAP; and the DoD item "alignment with the existing system is complete" must not pass
"There are too many affected modules; read only the first two, and fill in the rest later"	Do not allow partial alignment: the affected modules and ADRs listed in the impact analysis are mandatory inputs; either read them all, or mark the DoD as unmet and clearly identify the blocker (prioritize converging requirements/impact scope rather than sneak-reading)
"I have already written half of the recommended solution; going back to read now will slow delivery"	Sunk cost is invalid: First complete the mandatory inputs before writing "Alignment with Existing Systems"; otherwise the RFC is not reviewable and later rework will be greater

Common Mistakes (and Fixes)

• Mistake: Under pressure, "write first and figure it out later," generating the document before completing the inputs.
  Fix: First execute spec-context to obtain context, and satisfy the solution.md gate; if missing, stop and clearly write the blockers.
• Mistake: Treating research as "looking things up," writing a lot of background but with no verification checklist.
  Fix: Convert all unknowns into "risk/assumption → verification method → signal → Owner/deadline/action."
• Mistake: The PM asks for tasks/interfaces/table structures to be written into the design, so layers get mixed.
  Fix: The design document should retain only "key external commitments + traceability links"; move implementation details into implementation or contracts/ADR.
• Mistake: Reading only the index (components/index.md、adr/index.md or impact-analysis summary), then writing "aligned/compliant."
  Fix: For each affected module and ADR: you must read the full text and cite specific invariants/clauses; if you cannot read it, write CONTEXT GAP, and DoD must not pass.

Output and Automatic Routing After Completion (Mandatory)

design.md After it is written to disk,mustcomplete the following actions (in order, without omission):

1. Output ROUTER_SUMMARY(in YAML form, for Router decision-making):

ROUTER_SUMMARY:
  stage: D2
  artifacts:
    - "{FEATURE_DIR}/design/design.md"
  needs_human_review: true
  blocked: false
  block_reason: ""
  notes: "RFC 建议评审通过后再进入 I1（spec-plan）"

1. Immediately execute using-aisdlc: pass the above ROUTER_SUMMARY as routing input to using-aisdlc, and let the Router determine the next step andautomatically proceed(no need to wait for the user to say "continue").

   • If the Router determines that it can automatically continue: continue executing the next worker skill (such as I1, etc.) within the same conversation turn
   • If the Router triggers a hard interrupt: stop and output the blocking reason, required inputs, and candidate next steps

2. Conversation output: Before calling using-aisdlc, you may briefly state, "The artifacts for this stage have been written to disk; using-aisdlc is now being called to route the next step."