SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsspec-design

spec-design

Design & creation

View repository

Updated 10-16 08:46

About this skill

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-aidlc as the sole router; this skill does not make triage decisions.
Core principles:Gate first (spec-context) → mandatorily consume impact analysis and the project knowledge base → persist the decision (D2). Under any pressure, guessing paths is prohibited, and pushing forward by inventing things when the SSOT is missing is 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 use

  • When to use
    • The user asks to produce design/design.md(RFC/Decision Doc), or "do the design before entering implementation."
    • You are asked to stuff interface fields/table structures/task breakdowns into the design document, and you are worried 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-making (see spec-product-clarify）。
    • The user explicitly wants only the implementation plan and tasks: go directly to implementation

Quick reference

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

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

  • 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 a discussion arises about "whether to skip design / whether research is needed," return to using-aidlc for the routing determination; this skill only executes D2.

Implementation steps (Agent behavior specification)

0) Gate (must pass first, otherwise stop)

REQUIRED SUB-SKILL: currently executing spec-context to obtain context, and echo back FEATURE_DIR=...(allowed (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 follow, 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 points)
    • 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)
    • Relevant 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 continue by making things up):

  • 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 the index / read only part"):

  • The component pages of affected modules and the relevant 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 summary/index page of impact-analysis" 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 off 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 the boundaries are cut, options and trade-offs, key points of external commitments, how to verify, and key points of impact and migration/rollback.
  • Do not write: implementation steps, task breakdown, code-level details, item-by-item enumeration of interface fields, DDL details.
    • If fields/compatibility must be externally committed: write "key points + traceability links" in this document, and push the details down to project/contracts/ or an ADR.
    • If the project uses component pages as the contract SSOT: prefer to push the details down to the corresponding project/components/{module}.md#api-contract/#data-contract(aligned with the Discover module page structure of this repository).

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 content of
  2. Paste to {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 "questions to be confirmed/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 clearly explained using C4 L1+L2+L3 , and the levels are traceable
  • Key decisions explain "why choose it / why the alternatives were not chosen"
  • 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 corresponding component page #api-contract / #data-contract specific invariants
    • For each relevant ADR: complete theADR compliance statement(compliant/needs new/needs modification)
    • For the state machines/domain events involved: complete theimpact statement(cite the 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 explicit)

DoD decision rule (to prevent "treating CONTEXT GAP as done"):

  • If any affected module component page or related ADR shows CONTEXT GAP, then the item "Alignment with the existing system is complete"must not be checked as passed; D2 must explicitly state that this is a blocker/risk and provide a path to close it (read the full text/complete the knowledge base/add a new ADR).

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

  • Starting to write without first obtaining FEATURE_DIR=... then starting to write design/*.md
  • Cannot find requirements/solution.md and still continuing to write the design (= making things up)
  • Using a "list of questions to be confirmed / TODO" to leave unknowns dangling (should instead be changed to an "Assumptions + Verification Checklist")
  • Writing D2 as an implementation specification: task breakdown, implementation steps, field/DDL details
  • Lacking alternatives or lacking a verification checklist (leading to inability to review/inability to implement)
  • Reading only project/adr/index.md / project/components/index.md and then claiming "aligned with the existing system"
  • Reading only some affected modules or only some ADRs, then claiming "aligned/compliant"
  • Using an impact-analysis summary instead of the full component pages/ADRs, but without marking CONTEXT GAP
  • Treating CONTEXT GAP as the reason that "alignment is complete" (this is a DoD failure signal, not a pass signal)

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

Common excuse Corresponding rule / action
"Just write it anywhere for now to design/design.md, and move it later" Guessing paths is prohibited: first spec-context obtain FEATURE_DIR; otherwise stop
"Even with incomplete information, we can produce a draft first and fill it in later" Making things up is prohibited: if solution.md is missing or untraceable, stop; rewrite unknowns as an "Assumptions + Verification Checklist"
"The supervisor/PM says no gate/do not check the docs" The gate is a hard rule:Get-SpecContext if it fails, stop; do not make exceptions because of authority pressure
"For faster development, write all tasks/DDL/fields into the design" Refuse to mix layers: 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 leads to inability to review/rework; rather shorten the main text than delete DoD items
"The module pages/ADRs are too long, don't read them first; the impact-analysis summary is enough" Using summaries to impersonate alignment is prohibited: component pages and ADRs must either be read in full or marked 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" Partial alignment is prohibited: the affected modules and ADRs listed in the impact analysis are mandatory inputs; either read them all, or mark the DoD as unmet and explicitly identify the blocker (prioritize converging requirements/impact scope, rather than sneak-reading)
"I'm already halfway through writing the recommended solution; going back to read now will slow down delivery" Sunk cost is invalid: First complete the mandatory inputs before writing "Alignment with Existing Systems"; otherwise the RFC cannot be reviewed, and subsequent 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 run spec-context to obtain context, and satisfy the solution.md gate; if missing, stop and write down the blocker clearly.
  • Mistake: Treating research as "looking up information," 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 requires tasks/interfaces/table structures to be written into the design, resulting in layer mixing.
    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), and then writing "aligned/compliant."
    Fix: For each affected module and ADR: must read in full and cite specific invariants/clauses; if unable to read, write CONTEXT GAP, and DoD must not pass.

Post-completion output and automatic routing (mandatory)

design.md Aftermustcomplete 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-aidlc: Pass the above ROUTER_SUMMARY as routing input to using-aidlc, and the Router determines the next step andautomatically proceeds(no need to wait for the user to say "continue").

    • If the Router determines that automatic continuation is possible: continue executing the next worker skill (such as I1, etc.) in 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-aidlc, you may briefly state, "The artifacts for this stage have been written to disk; using-aidlc is being called to route the next step."