spec-design-research

spec-design-research

Overview

This skill is used to execute the D1 research (optional)of the Spec-level design phase: from the technical background of requirements/solution.md in the technical background ofsystematically extract unknowns, turn "NEEDS CLARIFICATION / dependencies / integrations" intodistributable research tasksand complete the investigation, depositing conclusions in design/research.md using the structure of Decision / Rationale / Alternatives considered , so that D2 can reference them directly without repeated explanation.
This skill can be used independently (D1 only), or be invoked when the routing of using-aidlc determines that "D1 is needed" (this skill does not perform D0/D1/D2 triage decisions).

Announce at the start:"I am using the spec-design-research skill to conduct design research and write research.md to disk."

When to use / not use

• When to use (any one applies)
  • The correctness of the solution depends on unknown facts (if X does not hold, the solution will be torn down and redone)
  • Multiple viable directions exist, but there is insufficient evidence to support the trade-off
  • There are high-risk points such as external contracts/migration/security/performance/consistency that need to be validated first
  • You find yourself about to write an "open questions list / TODO", but cannot provide a validation method and next-step actions
• Do not use when
  • The requirements-side SSOT has not been written to disk yet (missing requirements/solution.md): complete R1 first (see spec-product-clarify）
  • No critical uncertainties exist, and solution.md has already turned the key constraints and acceptance criteria into evidence: you may skip D1 and proceed directly to D2

Quick reference

• Sole output location：{FEATURE_DIR}/design/research.md
• Minimal template：<本SKILL.md目录>/assets/research-template.md
• D1-DoD (all are required)
  • In the technical background, all NEEDS CLARIFICATION have corresponding research tasks and conclusions given in research.md (in Decision/Rationale/Alternatives structure)
  • For each dependency there is a corresponding "best practice" task conclusion (or an explicit reason and evidence entry for "not applicable")
  • For each integration point there is a corresponding "pattern/integration approach" task conclusion (including key constraints, failure modes, and alternatives)
  • No unknown is left dangling: it is either closed by a research conclusion or moved into the "Risks and Validation Checklist" (including signal/Owner/deadline/action)
  • Research conclusions are traceable and can be referenced directly by D2 (short conclusions, clear evidence, reusable)
• Prohibitions
  • Do not guess FEATURE_DIR / hand-write the .aidlc/specs/... path
  • Do not write implementation specs in research.md (task breakdown/field lists/DDL/script steps)
  • Do not output "TODO/open questions" in place of research tasks and conclusions (unknowns must either be turned into tasks and produce conclusions, or go into an executable validation checklist)
  • Do not arbitrarily create contract/ADR/implementation spec files or directories during D1: D1 only produces design/research.md; if you need to update project/contracts/ or project/adr/, write in research "entries that need updating + key points", and leave the actual persistence to D2 (or operations explicitly requested by the user)

Implementation Steps (Agent Behavior Specification)

0) Gate: locate {FEATURE_DIR}(required)

REQUIRED SUB-SKILL: currently executing spec-context to obtain context, and echo in the conversation FEATURE_DIR=...(allowed (reuse)）。

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

• Required reading：{FEATURE_DIR}/requirements/solution.md
• As needed：{FEATURE_DIR}/requirements/prd.md、{FEATURE_DIR}/requirements/prototype.md
• As needed (project-level)：project/memory/*, related project/contracts/、project/adr/ index

Stop conditions (must not continue by guessing):

• Cannot find or cannot read requirements/solution.md
• solution.md the In/Out, acceptance criteria, and key constraints in are not traceable/testable (need to go back to R1 to fill in first)

2) Whether D1 needs to be executed (self-check; avoid "researching for the sake of research")

This skill serves as D1 worker skill: entering this skill means "routing has already determined that D1 is needed", so this skill no longer makes the judgment of "whether to do D1".
If during execution you find that: the key uncertainties have already been evidenced and there is no need to continue research, then you should stop and return to using-aidlc to re-route, rather than rewriting the routing conclusion within this skill.

3) Extract unknowns from the "technical background" → generate research tasks (core mechanism)

Hard rule: research.md must not contain a "list of questions to be confirmed / TODO". All unknowns must be converted into research tasks and given conclusions; those that cannot be closed in this round then go into the "verification checklist".

From requirements/solution.md (especially paragraphs related to "technical background/current state/architecture/dependencies/integration/constraints/risks"), extract three types of items and generate a research task for each:

• NEEDS CLARIFICATION → research task
  Goal: research "unknown facts/uncertainties" into conclusions that can be referenced by D2 (including trade-offs and alternatives).
• Dependencies (component/service/library/platform/organizational dependencies) → best practices task
  Goal: find out the best practices/common pitfalls/constraints of this dependency in this domain (and give conclusions combined with this project's constraints).
• Integration points (connecting to external systems/protocols/messages/authentication/callbacks, etc.) → pattern task
  Goal: clarify the integration pattern (synchronous/asynchronous, idempotency/retry, authentication/signature, data contract/version, error handling and degradation) and provide alternatives.

Research task generation rules (write into the "task list" in research.md and number them):

对于技术背景中的每个未知项：
  任务："针对 {feature context} 研究 {unknown}"
对于每个技术选择/依赖项：
  任务："查找 {domain} 中 {tech} 的最佳实践"
对于每个集成点：
  任务："梳理 {systemA} ↔ {systemB} 的集成模式与失败处理"

It is recommended to keep a "unknown item → research task number" mapping table in research.md to avoid omissions and duplication.

4) Distribute research to Agents for parallel investigation (strongly recommended)

Distribute the tasks generated in step 3 to multiple research Agents according to the principle of "parallelizable, low coupling" (each Agent corresponds to 1 task or 1 group of strongly related tasks), producing referenceable conclusion points and evidence entries.
When distributing, provide sufficient context: feature background, constraints, current-state evidence entries (paragraphs/links in solution.md), and a clear list of questions to be answered.

Minimum output requirements for each research task:

• Decision: what was ultimately chosen (or an explicit conclusion of "no decision for now / not applicable")
• Rationale: why it was chosen this way (combined with project constraints/evidence/trade-offs)
• Alternatives considered: what else was evaluated, and why it was not chosen
• Evidence / References: evidence entry points (documents, code, standards, historical incidents, stress test/PoC results, etc.)

5) Write {FEATURE_DIR}/design/research.md(minimal structure)

The minimized template must be usedto generate research.md (to avoid structural drift):

1. Copy <本SKILL.md目录>/assets/research-template.md content
2. Paste into {FEATURE_DIR}/design/research.md
3. Fill in the placeholders according to the template (especially "Research Task → Conclusion (Decision/Rationale/Alternatives)" must be complete)

Writing constraints:

• Keep only the minimal information that supports the D2 decision
• All NEEDS CLARIFICATION must appear in "Research Task" and be closed in the corresponding subsection (or enter the verification checklist with an explanation of why)
• Each research task subsection must include Decision / Rationale / Alternatives considered
• Do not add a "Open Questions/TODO" section

6) Put "unclosed items" into the "Risk and Verification Checklist" (necessary fallback)

For unknowns that still cannot be closed in this round (for example, those requiring a PoC, access permissions, external confirmation, a stress test window, etc.), they must be moved into the "Risk and Verification Checklist", and the following must be made explicit:

• Verification signal: what is seen determines whether it holds/does not hold
• Method: how to verify (research/interviews/experiments/stress testing/PoC/drills/data replay)
• Owner / Deadline: who is responsible, and by when the signal must be obtained
• Trigger action: what to do if it holds/does not hold (branch actions)

7) Handoff after D1 output (input that D2 can directly reference)

In research.md, ensure the following content can be directly referenced by D2:

• The recommended direction in the TL;DR is a "mechanism-level one-liner", not implementation steps
• Every key conclusion can be traced back to:solution.md, contracts/ADR index, research task number, or verification checklist item number
• Research task conclusions can be directly mapped to D2's decision sections (the Decision/Rationale/Alternatives structure can be reused)
• The verification checklist can be directly mapped to D2's "Risk and Verification Checklist" (Owner/Deadline/Action are not lost)

After completion:Immediately call using-aidlc route the next step (usually entering D2:spec-design）。

Post-completion output and automatic routing (must be executed)

research.md After being written to disk,mustcomplete the following actions (in order, cannot be omitted):

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

ROUTER_SUMMARY:
  stage: D1
  artifacts:
    - "{FEATURE_DIR}/design/research.md"
  needs_human_review: true
  blocked: false
  block_reason: ""
  notes: "research 结论建议评审；通常下一步进入 D2（spec-design）"

1. Immediately execute using-aidlc: pass the above ROUTER_SUMMARY as routing input to using-aidlc, have 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 D2, etc.) within the same conversation turn
   • If the Router triggers a hard interrupt: stop and output the blocking reason, required input, and candidate next steps

2. Conversation output: before calling using-aidlc, you may briefly state "This stage's artifacts have been written to disk; calling using-aidlc to route the next step."

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

• Without FEATURE_DIR=... , start writing/modifying design/research.md
• Missing requirements/solution.md Still continuing to write research (= making things up)
• A “list of questions to be confirmed / TODO” appears, but there are no research tasks and no Decision/Rationale/Alternatives (or no verification method/Owner/deadline/action)
• research.md becomes an implementation document: fields/DDL/migration scripts/task breakdown
• TL;DR exceeds 7 lines or is all background, with no “biggest risk + recommended direction”

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

Common excuses	Corresponding rules / actions
“Write it to the repository root first, and move it into spec later”	Do not guess paths: first spec-context get FEATURE_DIR, otherwise stop
“You can do research first without solution.md, and fill in what’s missing later”	No making things up: if solution.md is missing, stop immediately and first go back to R1 to complete the SSOT
“There’s no time to write a verification checklist, just list TODOs first”	TODO violation: rewrite each TODO as a verification checklist (including Owner/deadline/signal/action)
“The PM asks for detailed writing (fields/DDL/scripts) for developers”	Refuse to mix layers: research only writes conclusions/evidence/verification; in research write “the project/contracts/ / project/adr/ entry + key points that need updating,” and do not write fields/DDL/scripts in D1
“I’ve already written a lot of implementation drafts and don’t want to waste them”	Sunk cost is invalid: move the drafts out of research; keep only citable conclusions and the basis for trade-offs in the research body

Common mistakes (and fixes)

• Mistake: research is written as encyclopedic background and lacks executable verification.
  Fix: compress the background to the “minimum information needed for the decision,” and convert all unknowns into a verification checklist.
• Mistake: leave unknowns as a “list of questions to be confirmed.”
  Fix: rewrite as “risk/assumption → verification method → signal → Owner/deadline → action,” and number them.
• Mistake: write interface fields/table structures into research, making D2 hard to maintain.
  Fix: research only writes “key external commitments + traceability links (project/contracts/ / project/adr/ entry)”; leave fields/DDL/scripts to D2 or implementation.