spec-product-clarify

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

Overview

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

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

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

Hard rules (used to prevent "routing before clarification")

• While clarification is incomplete, it is forbidden to create/update solution.md(including templates/skeletons).
• While clarification is incomplete, 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 rulings"; it is forbidden to use "process forks/phase choices" to masquerade 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-aisdlc decision)
• Only in step 5: this skill must call using-aisdlc, pass ROUTER_SUMMARY as routing input to the Router for automatic progression.

Process

Step 0: Gate check (stop if not passed)

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

At the same time, the following must be satisfied:

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

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

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

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

Step 1: Read input (establish clarification context)

Required reading:

• {FEATURE_DIR}/requirements/raw.md

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

• .aisdlc/project/memory/product.md
• .aisdlc/project/memory/glossary.md
• .aisdlc/project/products/index.md
• .aisdlc/project/components/index.md

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

• Confirmed conclusions: points that have been ruled by the user and can directly enter solution.md Remaining unclarified points
• : key unknowns that would cause solution divergence/uncertain impact scope (3–8 items recommended)Step 2: Minimal clarification loop (ask only 1 question at a time)

Repeat the following closed loop until entering step 3:

From "remaining unclarified points", choose

1. 1 highest-leverage unknown (one that best reduces solution divergence)Ask
2. 1 decidable multiple-choice question (2–4 options + your recommendation + "other/uncertain" fallback)The question must be
   • The question must berequirements adjudication type: goal/scope/user/entry point/data definition/permissions/performance/consistency/failure strategy/acceptance criteria
   • The question must not beprocess branching type: do not make the user choose "which stage/skill to go to next/should a PRD/prototype/development be done"
3. After receiving the answer, immediately write back raw.md/## 澄清记录
4. and update the two lists (remove/split/replace this unknown; if a new unknown is introduced, add it to "remaining unclear points")

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

• still ask only 1 highest-leverage multiple-choice question
• and 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 adjudication" question, and must not degenerate into "which stage do you want to go to"

Step 3: Clarification completion confirmation (explicit confirmation required)

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

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

If any condition is not met: return to Step 2 and continue clarifying.

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

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

solution.md The following invariants must be satisfied:

• Must have 1 recommended solution: key trade-offs are clear; each key point can point to evidence (raw.md point) or a verification item
• Must have 2–3 clearly different alternative solutions: for each, write clearly "when it would be chosen / reasons 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 a "verification checklist" and it must be executable: each item includes assumption/risk → method → success/failure signal → Owner → deadline → trigger action (numbering V-xxx); prohibited TBD/待定/待指定
• main text must not contain lists such as "questions to be confirmed/list to be confirmed/To confirm" (uncertainty may only go into the verification checklist)
• Must explicitly write ## Context Gaps: mark each read failure/missing item 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 be followed / cross-module impact / Context Gaps"
• Iteration records must be appended: append 3–5 items per round of "what was changed + why it was changed"

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

After completing the write to disk, output in order:

1. artifact list(path list)
2. ROUTER_SUMMARY(only for consumption by Router)
3. Immediately call using-aisdlc: put the above ROUTER_SUMMARY Hand it to the Router as input; the Router determines the next step and automatically advances within the current conversation round (unless a hard interrupt is triggered)

And explicitly declare:

• This skill has ended;
• using-aisdlc Output the "Next Step (only one)" and execute the corresponding worker skill (if a hard interrupt 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 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 a certain instruction
• The user declares that raw.mdhas been updated/rewritten, but you cannot read/confirm the latest version

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

When to return to an earlier step

• Return to step 0：spec-context Context changes (branch/FEATURE_DIR changes) 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 , it is found that "remaining unclarified points" is still not empty

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

• Did not echo FEATURE_DIR=...(including variants of "I inferred it from the directory/branch")
• raw.md is missing/empty, or it cannot be confirmed that the latest version has been read
• Asking multiple questions at once (including "ask all the questions at once")
• Using "process branching/stage multiple-choice questions" instead of requirements 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 violation behavior	Required countermeasure action
"I can only reply once, ask everything at once"	Throw out a long list of questions or process branches for the user to choose from	Ask only 1 highest-leverage "requirements decision" multiple-choice question; put the remaining unknowns into the verification checklist (V-xxx）
"Just tell me directly which path to take next"	Output the next step/candidate routing before clarification is complete	Clearly refuse: first clarify to zero + user confirmation; at this stagerouting output is prohibited
"First give me the solution template, I'll fill it in later"	Generate when raw is missing/unclarified solution.md(even if empty)	Block directly: clarification is not complete → creating/updating is prohibited solution.md

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

• Conclusion of this round (can be directly quoted into the solution):
• Constraints added/updated 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 number V-xxx):

Write-back must occur after "receiving the user's answer"; do not write placeholders in raw.md . The write-back is mainlyconclusions/constraints/verification items.

Integration

Required sub-skills:

• spec-context(Get context: echo 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