spec-design-research

Overview

This skill is used to perform optional D1 research during the Spec-level design phase: supplement context and evidence for design decisions, and converge unknowns into an executable verification checklist, so that D2 can directly reference conclusions without repeating explanations.
This skill can be used independently (only for D1) or called as a sub-skill of

spec-design

(when D0 determines "not to skip" and triggers the D1 activation signal).

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

When to Use / Not to Use

Use Cases (meet any one)
- Solution correctness depends on unknown facts (if X is not true, the solution will be completely revised)
- Multiple feasible directions exist, but lack evidence to support trade-offs
- High-risk points exist in external contracts/migration/security/performance/consistency, etc., requiring prior verification
- You find yourself needing to write a "to-be-confirmed issue list / TODO" but cannot provide verification methods and next steps
Do Not Use When
- The requirement-side SSOT has not been finalized (missing
```
requirements/solution.md
```
  ): complete R1 first (see
```
spec-product-clarify
```
  )
- No critical uncertainties exist, and
```
solution.md
```
  has already evidenced key constraints and acceptance criteria: D1 can be skipped and proceed directly to D2

Quick Reference

Only Finalization Location:
```
{FEATURE_DIR}/design/research.md
```
Minimal Template:
```
skills/spec-design-research/research-template.md
```
(copy to the above path before filling)
D1-DoD (all required)
- Unknown items are not left hanging as "to-be-confirmed issues": all are included in the "Risk and Verification Checklist"
- Research conclusions are traceable and can be directly referenced by D2 (concise conclusions, clear evidence, reusable)
Prohibited Items
- Forbidden to guess the
```
FEATURE_DIR
```
  / manually write the
```
.aisdlc/specs/...
```
  path
- Forbidden to write implementation specifications (task breakdown/field list/DDL/script steps) in research.md
- Forbidden to output a "TODO list" instead of a verification checklist
- Forbidden to create new contract/ADR/implementation specification files or directories without authorization during D1: D1 only produces
```
design/research.md
```
  ; if updates to
```
project/contracts/
```
  or
```
project/adr/
```
  are needed, write "entry points + key points to update" in the research, and leave the actual finalization to D2 (or operations explicitly requested by the user)

Implementation Steps (Agent Behavior Specifications)

0) Gatekeeping: Locate

{FEATURE_DIR}

(Mandatory)

Before any reading/writing of
{FEATURE_DIR}/design/*.md
,
spec-context
must be executed first; stop immediately if it fails.

powershell

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

1) Read Minimum Necessary Inputs (Stop if Missing)

Required:
```
{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 (Do Not Continue with Assumptions):

```
requirements/solution.md
```
cannot be found or read
The In/Out, acceptance criteria, and key constraints in
```
solution.md
```
are untraceable/untestable (need to return to R1 to supplement first)

2) Whether D1 Needs to Be Executed (Self-check; Avoid "Research for Research's Sake")

If all the following conditions are met, skip D1 (proceed to D2):

Critical uncertainties have been evidenced in
```
solution.md
```
or the existing
```
design/research.md
```
The Risk and Verification Checklist is complete and executable

Otherwise, proceed to Step 3 to write/update

design/research.md

3) Convert "Unknowns" into "Assumptions + Verification Checklist" (Core Mechanism)

Hard Rule: No "to-be-confirmed issue list / TODO" shall appear in research.md. All unknowns must be converted into verification checklist items.

Translation Template (each unknown must be included in the table):

Risk/Assumption: One-sentence description of uncertainty (may include preconditions)
Verification Method: How to verify at the lowest cost (research/interview/experiment/load test/PoC/drill/data replay)
Success/Failure Signal: What observation constitutes passing/failing
Owner / Deadline: Who is responsible and by when the signal must be obtained (avoid indefinite suspension)
Next Steps: What to do if passed/failed (branch actions)

4) Write

{FEATURE_DIR}/design/research.md

(Minimal Structure)

Must use the minimal template to generate research.md (avoid structural drift):

Copy the content of

skills/spec-design-research/research-template.md

Paste it to
```
{FEATURE_DIR}/design/research.md
```
Fill in the placeholders according to the template (especially ensuring the "Verification Checklist" is executable)

Writing Constraint: Only retain the minimal information that supports D2 decisions; all unknowns are uniformly included in the "Verification Checklist"; do not add a "to-be-confirmed issues/TODO" section.

5) Transition After D1 Output (Provide Input Directly Referencable by D2)

Ensure the following content in research.md can be directly referenced by D2:

The recommended direction in the TL;DR is a "one-sentence mechanism-level description", not implementation steps
Each key conclusion can be traced to:
```
solution.md
```
, contracts/ADR index, or verification checklist item number
The Verification Checklist can be directly mapped to D2's "Risk and Verification Checklist" (Owner/deadline/actions are not lost)

Red Flags (Stop and Correct if Any Appear)

Starting to write/modify
```
design/research.md
```
without
```
FEATURE_DIR=...
```
Continuing to write research without
```
requirements/solution.md
```
(= making assumptions)
Appearance of "to-be-confirmed issue list / TODO" without verification methods/Owner/deadline/actions
research.md becomes an implementation document: fields/DDL/migration scripts/task breakdown
TL;DR exceeds 7 lines or is all background, without "top risk + recommended direction"

Anti-Rationalization Under Pressure (Common Excuses → Corresponding Actions)

Common Excuse	Corresponding Rule / Action
"Write to the root directory first, move it to the spec later"	Forbidden to guess paths: obtain `FEATURE_DIR` via `spec-context` first, otherwise stop
"Research can be done first without solution.md, fill in the gaps later"	Forbidden to make assumptions: stop directly if `solution.md` is missing, return to R1 to supplement the SSOT first
"No time to write the verification checklist, list TODOs first"	TODOs are non-compliant: rewrite each TODO into a verification checklist (including Owner/deadline/signal/actions)
"PM requires detailed writing (fields/DDL/scripts) for developers"	Reject mixing layers: research only includes conclusions/evidence/verification; write "entry points + key points to update in `project/contracts/` / `project/adr/` " in the research, do not write fields/DDL/scripts in D1
"I have already written many implementation drafts, don't want to waste them"	Sunk cost is invalid: move the drafts out of research; only retain referenceable conclusions and trade-off basis in the research body

Common Mistakes (and Fixes)

Mistake: Research is written as encyclopedia background, lacking executable verification.
Fix: Compress background to "minimal information required for decision-making", convert all unknowns into verification checklist items.
Mistake: Unknowns are left as a "to-be-confirmed issue list".
Fix: Rewrite using "Risk/Assumption → Verification Method → Signal → Owner/Deadline → Action" and number them.
Mistake: Interface fields/table structures are written into research, making D2 difficult to maintain.
Fix: Research only includes "key external commitments + traceable links (entries in
```
project/contracts/
```
/
```
project/adr/
```
)"; fields/DDL/scripts are left to D2 or implementation.

spec-design-research

NPX Install

Tags

SKILL.md Content (Chinese)

spec-design-research

Overview

When to Use / Not to Use

Quick Reference

Implementation Steps (Agent Behavior Specifications)

0) Gatekeeping: Locate
`{FEATURE_DIR}`
(Mandatory)

1) Read Minimum Necessary Inputs (Stop if Missing)

2) Whether D1 Needs to Be Executed (Self-check; Avoid "Research for Research's Sake")

3) Convert "Unknowns" into "Assumptions + Verification Checklist" (Core Mechanism)

4) Write
`{FEATURE_DIR}/design/research.md`
(Minimal Structure)

5) Transition After D1 Output (Provide Input Directly Referencable by D2)

Red Flags (Stop and Correct if Any Appear)

Anti-Rationalization Under Pressure (Common Excuses → Corresponding Actions)

Common Mistakes (and Fixes)