spec-design-research

spec-design-research

Overview

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

At the start, announce:"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 match)
  • Solution correctness depends on unknown facts (if X does not hold, the solution will need to be redone from scratch)
  • Multiple viable directions exist, but there is insufficient evidence to support the trade-off
  • There are high-risk points in external contracts/migration/security/performance/consistency, etc., that need to be validated first
  • You find yourself about to write a "pending questions list / TODO", but cannot provide a validation method and next actions
• Do not use when
  • The requirements-side SSOT has not been written to disk yet (missing requirements/solution.md): first complete R1 (see spec-product-clarify）
  • There is no key uncertainty, and solution.md has already evidenced the key constraints and acceptance criteria: you can skip D1 and go directly to D2

Quick reference

• The only write-to-disk 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 are provided in research.md (in Decision/Rationale/Alternatives structure)
  • For each dependency , there is a corresponding "best practice" task conclusion (or an explicit "not applicable" reason and evidence entry point)
  • For each integration point , there is a corresponding "pattern/integration approach" task conclusion (including key constraints, failure modes, and alternatives)
  • Unknowns do not remain dangling: they are either closed by research conclusions or enter the "risks and validation checklist" (including signal/Owner/deadline/action)
  • Research conclusions are traceable and can be directly referenced by D2 (concise conclusions, clear evidence, reusable)
• Prohibitions
  • Do not guess FEATURE_DIR / hand-write .aisdlc/specs/... paths
  • Do not write implementation specs in research.md (task breakdowns/field lists/DDL/script steps)
  • Do not output "TODO/pending questions" in place of research tasks and conclusions (unknowns must either become tasks and produce conclusions, or enter an executable validation checklist)
  • Do not arbitrarily create contracts/ADR/implementation spec files or directories during D1: D1 only produces design/research.md; if you need to update project/contracts/ or project/adr/, in research write "entry points that need updating + key points", and leave the actual file changes to D2 (or an operation 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 it back 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 making things up):

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

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-aisdlc to re-route, rather than rewriting the routing conclusion within this skill.

3) Extract unknowns from "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 with 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 dependency) → best practices task
  Goal: find out the best practices/common pitfalls/constraints of this dependency in this domain (and give a conclusion combined with this project's constraints).
• Integration points (connecting to external systems/protocols/messages/authentication/callbacks, etc.) → pattern task
  Goal: clarify the integration pattern (sync/async, 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 mapping table of "unknown item → research task number" 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 entry points.
When distributing, provide sufficient context: feature background, constraints, current-state evidence entry points (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 a clear 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 point (documents, code, standards, historical incidents, stress test/PoC results, etc.)

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

The minimal template must be usedGenerate research.md (to avoid structural drift):

1. Copy the contents of <本SKILL.md目录>/assets/research-template.md the contents of
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 supporting the D2 decision
• All NEEDS CLARIFICATION must appear in "Research Tasks" and be closed in the corresponding subsection (or entered into the verification checklist with an explanation of the reason)
• Each research task subsection must contain Decision / Rationale / Alternatives considered
• Do not add a "Open Questions/TODO" section

6) Put "open items" into the "Risks and Verification Checklist" (necessary fallback)

For unknowns that still cannot be closed in this round (e.g., requiring a PoC, access permissions, external confirmation, stress test window, etc.), they must be moved into the "Risks and Verification Checklist", and clearly specify:

• Verification signal: what is seen counts as confirmed/not confirmed
• 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 confirmed/not confirmed (branch actions)

7) Handoff after D1 output (input directly referenceable by D2)

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 section (the Decision/Rationale/Alternatives structure can be reused)
• The verification checklist can be directly mapped to D2's "Risks and Verification Checklist" (Owner/Deadline/Action are not lost)

After completion:Immediately call using-aisdlc to route the next step (usually enter D2:spec-design）。

Output and automatic routing after completion (must be executed)

research.md After is written to disk,mustcomplete the following actions (in order, none may be omitted):

1. Output ROUTER_SUMMARY(in 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-aisdlc: pass the above ROUTER_SUMMARY as routing input to using-aisdlc, let the Router determine the next step andautomatically proceed(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 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-aisdlc, you may briefly state "The artifacts for this stage have been written to disk; calling using-aisdlc 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 continue writing research (= making things up)
• A "Pending Confirmation Question List / TODO" appears, but there is no research task and no Decision/Rationale/Alternatives (or no verification method/Owner/deadline/action)
• research.md turns into 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 action)

Common excuse	Corresponding rule / action
"Write it to the repository root first, move it into spec later"	Guessing paths is prohibited: first spec-context get FEATURE_DIR, otherwise stop
"We can do research first without solution.md, and fill in what's missing later"	Making things up is prohibited: if solution.md is missing, stop directly and first return to R1 to complete the SSOT
"No time to write the verification checklist, just list TODOs first"	TODO violation: rewrite each TODO as a verification checklist (including Owner/deadline/signal/action)
"The PM asks for details (fields/DDL/scripts) to give to developers"	Refuse to mix layers: research only writes conclusions/evidence/verification; in research write "the project/contracts/ / project/adr/ entry points + key points that need to be updated", 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 trade-off rationale 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 "Pending Confirmation Question List".
  Fix: rewrite using "risk/assumption → verification method → signal → Owner/deadline → action" and number them.
• Mistake: write interface fields/table structures into research, making D2 difficult to maintain.
  Fix: research only writes "key external commitments + traceability links (project/contracts/ / project/adr/ entry points)"; leave fields/DDL/scripts to D2 or implementation.