spec-product-clarify

spec-product-clarify (R1: requirement clarification + solution decision)

Overview

This skill is used to converge {FEATURE_DIR}/requirements/raw.md throughmultiple rounds of minimal clarification loopsinto a reviewable {FEATURE_DIR}/requirements/solution.md(including ## Impact Analysis）。
The clarification process must be traceable: after each user decision,immediately write backto raw.md/## 澄清记录。

Core principle: clarify first, then artifact; artifact first, then routing.

At the start, announce:"I am using the spec-product-clarify skill to clarify requirements and produce solution.md."

Hard rules (to prevent "routing before clarification")

When clarification is not complete, it is forbidden to create/update solution.md(including templates/skeletons).
When clarification is not complete, it is forbidden to output any information about "next-step routing/candidate next steps/letting the user choose a phase (R2/R3/I1/I2...)".
Clarification questions must be "requirement decisions"; it is forbidden to pass off "process branching/phase selection" as clarification.(For example: do not ask "do you want a PRD, a prototype, or development")
This skill does not output a next-step routing conclusion.(The next step is determined by the Router:using-aidlc )
Only in step 5: this skill must call using-aidlc, handing ROUTER_SUMMARY as routing input to the Router to advance automatically.

Process

Step 0: gate check (stop if it does not pass)

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

At the same time, the following must also be satisfied:

{FEATURE_DIR}/requirements/raw.md exists and is non-empty

If any condition is not satisfied:stop immediately, output only:

Blocking reason
The minimum input needed (for example:spec-context output fragment, or raw.md content/path)

Note: when stopping, alsodo notoutput "which path/which skill to take next".

Step 1: read input (establish clarification context)

Required reading:

{FEATURE_DIR}/requirements/raw.md

Mandatory attempts to read (if unreadable, first record as CONTEXT GAP, later write into solution.md/## Context Gaps, and add a verification item):

.aidlc/project/memory/product.md
.aidlc/project/memory/glossary.md
.aidlc/project/products/index.md
.aidlc/project/components/index.md

Then maintain two lists in the conversation (visible in the conversation is sufficient; writing back process state is not required):

Confirmed conclusions: points already decided by the user that can go directly into solution.md key points of
Remaining unclarified points: key unknowns that would cause solution divergence/uncertain impact scope (3-8 items recommended)

Step 1.5: automatic mode determination (only when `AUTO_MODE=true` )

If raw.md in the YAML Frontmatter of mode is not auto(or there is no Frontmatter), skip this step and go directly to step 2.

If mode: auto, execute the following 6-dimensional completeness quick scan：

Dimension	Pass criteria
Goal	`raw.md` clearly state what problem to solve or what effect to achieve
Input	The data sources/trigger conditions/prerequisite dependencies involved have been stated
Output	The expected deliverables/outputs/behavior changes have been stated
Constraints	Technical/business/time/resource and other limiting conditions have been stated (may be empty—explicitly declaring "no special constraints" also counts as passing)
Acceptance criteria	There is at least a testable success/failure determination condition
Boundaries	The In/Out scope can be inferred (precision is not required, but it cannot be completely missing)

Determination result：

All 6 dimensions are explicitly covered (pass): Skip step 2 and step 3, and go directly to step 4 to produce solution.md. Treat the existing information in raw.md as "confirmed conclusions"; no need to wait for user confirmation.
Any dimension is missing or there is major ambiguity (fail)：one-timeOutput the full list of questions to be clarified (rather than interacting item by item), set ROUTER_SUMMARY to blocked: true，block_reason state the missing dimensions and corresponding questions. This skill ends, and the caller decides how to collect answers before re-entering R1.

Note: In automatic mode, when "fail" occurs, this skill does not enter the interaction loop of step 2, but directly ends and blocks.

Step 2: Minimal clarification loop (ask only 1 question at a time)

Repeat the following closed loop until entering step 3:

From the "remaining unclarified points", select 1 highest-leverage unknown(the one that can most reduce divergence in the solution)
Ask 1 decidable multiple-choice question(2–4 options + your recommended option + an "other/unsure" fallback)
- The question must be of therequirements-decision type: goal/scope/user/entry point/data definition/permissions/performance/consistency/failure strategy/acceptance criteria
- The question must not be of theprocess-branching type: do not ask the user to choose "which stage/skill to go to next/whether to do a PRD/prototype/development"
After receiving the answer, immediately write it back raw.md/## 澄清记录
Update both lists (remove/split/replace that unknown; if new unknowns are introduced, add them to the "remaining unclarified points")

When the user pressures with "you can only reply once/ask everything at once/stop asking":

Still ask only 1 highest-leverage multiple-choice question
Move all other unknowns into the solution.md verification checklist (V-xxx), and do not output any routing information because of this
Pay special attention: this question must also be a "requirements decision", and must not degrade into "which stage do you want to go to"

Step 3: Clarification completion confirmation (must be explicitly confirmed)

Only when the following conditions are all met may you proceed to step 4:

You confirm in the conversation:remaining unclarified points = empty
The user explicitly confirms:"no omissions/can proceed to solution decision-making"(confirming with a yes/no multiple-choice question also counts)

If any condition is not met: return to step 2 and continue clarification.

AUTO_MODE exception: If the Step 1.5 scoring passes (all 6 dimensions covered), Steps 2 and 3 have been skipped, and you may proceed directly to Step 4 without user confirmation.

Step 4: Produce/Update `solution.md`(only after clarification is complete)

Template source:assets/solution-template.md(borrow only the structure; do not treat the unknown as known).

solution.md must satisfy the following invariants:

must have 1 recommended option: key trade-offs are clear; each key point can point to evidence (raw.md point) or verification item
must have 2–3 clearly different alternatives: each clearly states "when it would be chosen / reason not to choose it" (capture 1–2 key differences)
must have "Decision Basis (Evidence Entry)": explicitly cite raw.md; anything lacking evidence must be moved to the verification checklist
must have an executable "Verification Checklist": each item includes Hypothesis/Risk → Method → Success/Failure Signal → Owner → Deadline → Trigger Action (number V-xxx); prohibit TBD/待定/待指定
body text from containing must not contain lists such as "Pending Questions/Pending Confirmation List/To confirm" (uncertainty may only go into the verification checklist)
must explicitly write ## Context Gaps: mark read failures/missing items one by one as CONTEXT GAP, and add a corresponding verification item for each gap (V-xxx）
must include ## Impact Analysis: at least include "affected modules / invariants to comply with / cross-module impact / Context Gaps"
iteration records must be appended: each round append 3–5 items of "what was changed + why it was changed"

Step 5: End output (deliver only the results of this stage; do not route)

After completing the write-to-disk, output in order:

Artifact list(path list)
ROUTER_SUMMARY(used only for consumption by the Router)
immediately call using-aidlc: pass the above ROUTER_SUMMARY as input to the Router; the Router determines the next step and automatically advances within this round of dialogue (unless a hard interruption is triggered)

and explicitly declare:

this skill has ended;
using-aidlc will output "next step (only one)" and execute the corresponding worker skill (if a hard interruption is triggered, stop and explain the reason/required input)

ROUTER_SUMMARY Reference format:

ROUTER_SUMMARY:
  stage: R1
  artifacts:
    - "{FEATURE_DIR}/requirements/raw.md"
    - "{FEATURE_DIR}/requirements/solution.md"
  needs_human_review: false
  blocked: false
  block_reason: ""
  notes: "软检查点：solution.md（尤其 #impact-analysis）建议评审"

When AUTO_MODE is blocked(Step 1.5 scoring does not pass) ROUTER_SUMMARY:

ROUTER_SUMMARY:
  stage: R1
  artifacts:
    - "{FEATURE_DIR}/requirements/raw.md"
  needs_human_review: true
  blocked: true
  block_reason: "raw.md 完整度不足，缺失维度：[输入、验收口径]。待澄清问题：1) xxx？2) xxx？"
  notes: "AUTO_MODE：需调用方收集答案后重新进入 R1"

When to stop and seek clarification (do not guess)

Stop immediately:

did not receive FEATURE_DIR
{FEATURE_DIR}/requirements/raw.md does not exist or is empty
instructions conflict with each other, or you do not understand an instruction
the user states that they have updated/rewritten raw.md, but you cannot read/confirm the latest version

When stopping, output only: blocking reason + minimum required input.

When to return to an earlier step

Return to Step 0：spec-context context changes (branch/FEATURE_DIR change) or the raw file path is no longer trustworthy
Return to Step 1: the user rewrote raw.md or added key constraints (requires re-reading)
Return to Step 2: before writing solution.md , you find that "remaining unclarified points" is still not empty

Red flags (any one appearing = stop immediately and correct)

Not echoed back FEATURE_DIR=...(including variants of "I inferred from the directory/branch")
raw.md missing/empty, or unable to confirm that the latest version has been read
Asking multiple questions at once (including "ask all the questions in one go")
Using "process branching/stage multiple-choice questions" instead of requirement clarification
Creating/updating before clarification is complete solution.md(including "write the template/skeleton first")
Outputting "next-step routing/candidate next steps/letting the user choose a stage" before clarification is complete

Common excuses and countermeasures (most common in stress testing)

Excuse (source of pressure)	Common violations	Required countermeasures
"I can only reply once, ask everything in one go"	Throwing out a long list of questions or process branches for the user to choose from	Ask only 1 highest-leverage "requirement decision" multiple-choice question; all other unknowns go into the verification checklist (`V-xxx`）
"Just tell me directly which path to take next"	Outputting next steps/candidate routes before clarification is complete	Explicit refusal: clarify to zero first + user confirmation; at this stage,routing output is prohibited
"Give me the solution template first, I'll fill it in later"	Generating when raw is missing/unclarified `solution.md`(even if empty)	Directly block: clarification incomplete → creating/updating prohibited `solution.md`

Clarification write-back format (write into `raw.md/## 澄清记录`, append one entry per round)

Conclusion of this round (can be quoted directly into the solution):
Newly added/updated constraints in this round (if any, list 1–5 key points):
Key decisions (if any: decision point → chosen result; 1–3 entries may be written):
Remaining ambiguities (if any: assumptions/risks → corresponding verification ID V-xxx):

Write-back must happen after "obtaining the user's answer"; do not write placeholders in raw.md . Write-back is based onconclusions/constraints/verification itemsas the main content.

Integration

Required sub-skills:

spec-context(obtain context: echo back FEATURE_DIR=...）

Optional (only when Impact Analysis cannot proceed due to gaps in the project knowledge base):

project-discover-preflight-scope
project-discover-memory-index
project-discover-modules-contracts
project-discover-products-ops-dod