spec-product-clarify (R1: Clarification + Solution Decision)

Overview

Take the original input from

{FEATURE_DIR}/requirements/raw.md

, first converge to "no unconfirmed key points" through multiple rounds of continuous clarification, then produce a reviewable decision document

{FEATURE_DIR}/requirements/solution.md

; the clarification process must be traceable (written back to

raw.md/## Clarification Records

Announce at the start: "I am using the spec-product-clarify skill to clarify requirements and produce solution.md."

Hard Rule: Prohibit creating/updating

solution.md

until clarification is completed.

Gates / Stop (Strictly Enforced)

REQUIRED SUB-SKILL: First execute
spec-context
and echo
FEATURE_DIR=...
in the conversation.

Stop immediately (if any of the following is met):

```
FEATURE_DIR
```
not obtained
```
{FEATURE_DIR}/requirements/raw.md
```
does not exist or is empty
Path/branch is uncertain, instructions conflict with each other, or an instruction is not understood (prohibit guessing/making up content)
User explicitly requests to stop this task (no further clarification/no more documents to produce)
User states that
```
raw.md
```
has been updated/revised or key constraints have changed, but the latest
```
raw.md
```
cannot be read/confirmed (proceeding based solely on verbal statements is prohibited)

Reading/Writing Conventions:

Read:
```
{FEATURE_DIR}/requirements/raw.md
```
(mandatory);
```
project/memory/glossary.md
```
(if exists and terminology alignment is needed)
Write: Only append/update
```
## Clarification Records
```
in
```
{FEATURE_DIR}/requirements/raw.md
```
;
```
{FEATURE_DIR}/requirements/solution.md
```
is the only decision entry (create/update only after clarification is completed)

Violating the gates = violating the core principle: Even if "time is tight/boss is urging/user doesn't want to run the script", prohibit reading/writing files in unknown contexts.

Common Excuses (Execute Gates Immediately If Present)

"Time is tight/review is imminent/boss is urging": Still must first obtain
```
FEATURE_DIR
```
and read
```
raw.md
```
; stop otherwise
"You decide the path yourself": Prohibit guessing the path;
```
FEATURE_DIR
```
must be provided by
```
spec-context
```
"I can only reply once/ask all questions at once": Still only ask 1 highest-leverage question; other unknowns are added to the verification list
"Don't look back at raw": If input changes/new constraints are added, must rely on
```
raw.md
```
and re-read it; stop if this cannot be done
"Stop asking, directly produce solution/prd": Prohibit producing output until clarification is completed; instead, continue to ask 1 highest-leverage multiple-choice question and explain "this answer is missing and cannot form a reviewable decision"
"Choose for me: Continue clarification / Enter R2 / Fast track": Prohibit providing branching options; if there are still unclarified points, default to continuing clarification until all are resolved

Minimum Loop (Narrow Down Questions, Document Conclusions)

Repeat the following loop until stopped:

Select 1 highest-leverage unknown from
```
raw.md
```
(the one that can most reduce solution disagreements)
Ask 1 adjudicatable multiple-choice question: 2–4 options + your recommended option + "Other/Uncertain" as fallback
Immediately write back to
```
raw.md/## Clarification Records
```
after receiving the answer
Re-evaluate whether there are still unclarified points based on the user's answer (including "newly emerged constraints/scope/goals/risks"), and write "current unclarified points (<=3 items)/whether clarification is completed" into this round's write-back

When the user can only reply once: Keep only the first highest-leverage question; add other unknowns directly to the verification list.

Exit/Transition of Clarification Loop:

If Is clarification completed this round? = Yes in this round's write-back: End the clarification loop and start creating/updating
```
solution.md
```
Otherwise: Proceed directly to the next round (continue to ask 1 multiple-choice question; prohibit providing branching options)

When Is "Clarification Completed" (Must Meet All Conditions)

Clarification is considered completed only when all of the following are met:

Current unclarified points = None (clearly write "None" in this round's write-back)
User explicitly confirms "no omissions/proceed to solution decision" (this can also be confirmed via a multiple-choice question)

Only after clarification is completed is creating/updating

solution.md

allowed, and then proceed to R1's "Solution Decision and Verification List".

Product Invariants (Must Meet)

solution.md

Must include 1 recommended solution: Clearly state key trade-offs; each key point must point to evidence (location in
```
raw.md
```
) or a verification item
Must include 2–3 distinct alternative solutions: For each, clearly state "when to choose / reasons not to choose" (1–2 key differences)
Must have "Decision Basis (Evidence Entry)": Explicitly reference
```
raw.md
```
; any content lacking evidence must be transferred to the verification list
Must have an executable "Verification List": Each entry includes Assumption/Risk → Method → Success/Failure Signal → Owner → Deadline → Trigger Action (numbered V-xxx); placeholders like "TBD/to be determined/to be assigned" are prohibited, Owner/Deadline must at least specify "role/responsible person + relative time frame"
The main body must not contain lists such as "pending confirmation questions/pending confirmation list/To confirm" (uncertainties can only be included in the verification list)
Iteration records must be appended: Each round appends 3–5 entries of "what was changed + why it was changed"

raw.md

After each answer, a traceable record must be left in
```
## Clarification Records
```
(prohibit placeholders)

Clarification Write-Back Format (Write to

raw.md/## Clarification Records

)

Append one entry per round:

Question:
Recommended Option (with reasoning):
User's Answer:
One-sentence Conclusion:
Remaining Ambiguities (if any, written as "Assumption/Risk" with verification number V-xxx):
Current Unclarified Points (<=3 items; write "None" if none):
Is Clarification Completed This Round: Yes / No

Write-back must occur after receiving the user's answer; do not write "to be filled by user/placeholder" in
raw.md
. The write-back content only includes the above fields (keep concise and traceable), do not add additional explanatory paragraphs/templates/empty headings.

solution.md

Structure

Follow the template:

skills/spec-product-clarify/solution-template.md

(borrow only the structure, do not treat unknowns as knowns).

Diversion After Clarification Completion (Optional)

Discussing the following diversions is only allowed after clarification is completed; proposing options like "enter R2/fast track" is prohibited until clarification is completed.

If the user explicitly skips R2 (separate PRD), append a Mini-PRD to

solution.md

MVP scope (precise to behavior/rules)
AC (3–10 items, testable, verifiable)
Interaction change conclusion (None / Yes but simple; otherwise, skipping is not recommended)
Impact scope (locatable entries for pages/entries/interfaces/permission points)

Minimal Example (Single Round of Clarification + Write-Back)

A single multiple-choice question to the user:

Question: Which execution method should be used for export tasks?
- A. Synchronous (small data volume)
- B. Asynchronous + Export Center (large data volume)
- C. First synchronous then asynchronous (phased iteration)
- D. Uncertain → Please provide the maximum number of rows to export/expected completion time
- My Recommendation: B (traceable, recoverable)

Write-back to

raw.md/## Clarification Records

Question: Which execution method should be used for export tasks? (same as above)
Recommended Option (with reasoning): B (more stable for large data volumes; easy to trace and recover from failures)
User's Answer: C
One-sentence Conclusion: MVP uses synchronous execution with an upper limit first; then iterate to asynchronous export and Export Center
Remaining Ambiguities: V-001 Export upper limit and performance target not determined (Method = pressure test; Signal = time consumption/failure rate; Owner = DEV; Deadline = 3 days after review; Action = switch to asynchronous scheme if threshold is exceeded)
Current Unclarified Points (<=3 items): Export upper limit (number of rows) and performance target (time consumption/resources) specifications
Is Clarification Completed This Round: No

spec-product-clarify

NPX Install

Tags

SKILL.md Content (Chinese)

spec-product-clarify (R1: Clarification + Solution Decision)

Overview

Gates / Stop (Strictly Enforced)

Common Excuses (Execute Gates Immediately If Present)

Minimum Loop (Narrow Down Questions, Document Conclusions)

When Is "Clarification Completed" (Must Meet All Conditions)

Product Invariants (Must Meet)

Clarification Write-Back Format (Write to
`raw.md/## Clarification Records`
)

`solution.md`
Structure

Diversion After Clarification Completion (Optional)

Minimal Example (Single Round of Clarification + Write-Back)

spec-product-clarify

NPX Install

Tags

SKILL.md Content (Chinese)

spec-product-clarify (R1: Clarification + Solution Decision)

Overview

Gates / Stop (Strictly Enforced)

Common Excuses (Execute Gates Immediately If Present)

Minimum Loop (Narrow Down Questions, Document Conclusions)

When Is "Clarification Completed" (Must Meet All Conditions)

Product Invariants (Must Meet)

Clarification Write-Back Format (Write to raw.md/## Clarification Records)

solution.md Structure

Diversion After Clarification Completion (Optional)

Minimal Example (Single Round of Clarification + Write-Back)

Clarification Write-Back Format (Write to
`raw.md/## Clarification Records`
)

`solution.md`
Structure