spec-checklist

spec-checklist (Spec Pack document pending-clarification point scanning and convergence)

Overview

This skill is used withinthe current Spec Pack to scan documents in process order and find "pending clarification/pending confirmation"high-value questions, and throughask only one question at a timeloop write the conclusions back to the corresponding documents until the uncertainty is eliminated or converted into verifiable items.

Core principle: do not guess, do not ask in batches, do not leave oral conclusions; after each decision, immediately persist it to disk.

When to use

• You see in a spec pack document 待确认/待澄清/TBD/TODO/未定/暂定/Open Questions/???/FIXME etc.
• You are unsure whether a passage of text is a "conclusion" or a "placeholder/assumption/oral agreement"
• You need to converge uncertainty into:confirmed conclusion or executable verification item

Hard rules (must be followed)

• Gate first: whenever you need to read or write {FEATURE_DIR}/requirements|design|implementation|verification, you must first execute REQUIRED SUB-SKILL：spec-context to obtain context, and echo it in the conversation FEATURE_DIR=...(allowed (reuse)）。
• Stop if spec-context fails: if a valid FEATURE_DIR=...cannot be obtained, you must stop immediately; output only "blocking reason + minimum required input" (for example: switch to the correct spec branch, or provide an actually existing requirements/ that contains FEATURE_DIR）。
• Do not pass off guesses/default values as conclusions: when you see TBD/pending confirmation, unless the user has explicitly decided, you must not "fill it in as a reasonable default value" and write it into the document.
• Ask only one question at a time: each round, ask only 1 highest-leverage clarification question(2-4 options + recommended option + fallback "other/unsure").
• Write back immediately after asking: after the user answers, you mustimmediately update the corresponding document(eliminate placeholders), and when necessary update related documents in coordination (for example AC, scope, data definitions, interface contracts, test plans, etc.).
• Must commit after write-back (controlled by AUTO_COMMIT): after each completion of "user answer -> write back to document/coordinated update":
  • AUTO_COMMIT=true(default): you must make one git commit before the end of this round, ensuring each clarification round has a traceable commit point (the commit message must be in Chinese).
  • AUTO_COMMIT=false: skip git add + git commit, and instead output "list of changed files, please commit manually" and list the file paths modified in this round.
• Given file != skip gate: if the user gives a document path, you may skip the "full scan", but as long as that file is under/may be under {FEATURE_DIR} , you must still first spec-context before reading or writing.

Selection order (first follow the spec-pack process, from source to downstream)

**The first priority is always the "document process order".** Because decisions in earlier documents cascade to affect later documents, you must start adjusting from the source:

1. First handle the unresolved points in the earliest document (for example first requirements/raw.md, then solution.md, then prd.md …）
2. Only after "the pending points of the preceding document are cleared / or converted into explicit verification items" is it allowed to proceed to the clarification and write-back of the subsequent document

Withinthe same document, only then use the "high-value" rule to decide which one to ask first:

• Blocks implementation/acceptance: scope boundaries, entry process, business rules, AC, key data definitions, permission model
• Large impact and irreversible: external/cross-module contracts, data migration/rollback, compliance and security, deletion strategy
• Risk and cost: performance/capacity/reliability goals, canary/release/rollback strategy, dependencies and SLA
• Deferrable: copy, visual details, non-critical configuration (unless it affects acceptance)

Process (solidified according to the steps you gave)

Step 0: Is a file given?

• "Given file" only means: the user provideda locatable document path(for example {FEATURE_DIR}/requirements/solution.md). Providing only fragments/screenshots/verbal descriptions does not count as a given file.
• If the usergave a file path: record it as TARGET_DOC, and go directly to Step 2(but the gate rules above still need to be satisfied).
• Ifno file is given: is executing spec-context to obtain context, and echo FEATURE_DIR=..., then proceed to Step 1。

Step 1: Scan in Spec Pack process order (only scan documents that exist)

Scan in order and extract candidate "to be clarified/to be confirmed" points:

• requirements/raw.md
• requirements/solution.md
• requirements/prd.md
• requirements/prototype.md
• design/research.md
• design/design.md
• implementation/plan.md
• verification/test-plan.md
• verification/usecase.md
• verification/suites.md
• verification/report-*.md

Scanning method (merge and deduplicate):

• Keyword signals：待确认|待澄清|TBD|TODO|TBC|未定|暂定|暂不确定|后续再定|后续再议|Open Questions|FIXME|\?\?\?
• Structural gap signals: missing scope boundaries/role permissions/data definitions/exception strategy/acceptance criteria/contract details

Output a list (maintaining it in the conversation is sufficient):

• Candidate clarification points: bydocument process ordergroup and arrange; each item includes "file→section→original text fragment→why it is high-value (blocking/irreversible/risk)"; within the same file group, sort again by high value

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

Repeat the following closed loop:

1. From the "candidate clarification points", select 1 highest-priority item(first takethe earliest document's pending points; then select the highest-value one within that document)
2. Rewrite it as 1 decidable question(2–4 options + recommended option + fallback)
3. Wait for the user's answer
4. Immediately write back to the document: change that point from "placeholder/undecided" to "conclusion/rule/acceptance criteria", and synchronously update other affected document passages
5. Immediately git commit (controlled by AUTO_COMMIT)：
   • AUTO_COMMIT=true(default): only commit the relevant document changes caused by this round of clarification; avoid committing sensitive files (such as .env, credentials). If there are no actual file changes, skip the commit.
   • AUTO_COMMIT=false: skip the commit, output "The following files have changed, please commit manually:" and list the file paths modified in this round.
6. Remove resolved items from the candidate list; if write-back introduces new uncertainties, add them to the candidate list

When the user pressures you with "stop asking/make it one round/fill in defaults": still ask only 1 highest-leverage question; the remaining unresolved items must stay in the document and be converted into executable verification items (not verbal accounting).

Step 3: Backjump Rule

• If no file is given: after resolving 1–3 questions, return to Step 1 and continue scanning (because write-back may expose new gaps).
• If a file is given: cycle only within that file and its directly related documents; end when the number of uncertainties reaches zero.

Minimum write-back format (to avoid "verbal conclusions")

When you eliminate a "To be confirmed/TBD" point in a document, at minimum change that place to one of the following:

• Adjudicated conclusion: explicitly write out the rule/standard/authority/scope/AC (avoid "tentative/to be discussed later")
• Verification item (when still uncertain): turn it into an executable verification entry (including: assumption/risk → method → success/failure signal → trigger action), and explicitly state "must be completed before entering implementation/acceptance"

And when necessary add 1 line of "linked update" note: point out which sections/documents need to be updated in sync because of this adjudication (for example, implementation/plan.md tasks and verification steps,verification/usecase.md use cases and data standards).

Git commit minimum steps (execute once after each clarification round, controlled by AUTO_COMMIT)

When AUTO_COMMIT=true(default):

• Check changes：git status；git diff
• Stage related files：git add <本轮修改的文档路径...>
• Commit (Chinese message): it is recommended that the commit message include "clarification point + affected documents", for example:
  • 澄清：权限模型与数据口径
  • 澄清：验收口径（更新 usecase 与 test-plan）
• Confirm clean：git status

When AUTO_COMMIT=false :

• Skip git add + git commit
• Output "The following files have changed, please commit manually:" and list the file paths modified in this round
• Continue to the next clarification cycle (do not interrupt the process because commits are skipped)

Quick Reference

The signal you see	What you must do	What you must never do
"TBD/To be confirmed/Undecided"	Generate 1 adjudicable question and ask only this one	Directly fill in a default value and write it back as a conclusion
The user wants you to "ask everything in one round"	Ask only the 1 highest-leverage question, convert the rest into verification items	Throw out a list of 20 questions and make the user tire out answering
The user gave a file path	Directly focus on that document and enter Step 2	Skip the gated read/write just because "there is a path"

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

• Without echoing back FEATURE_DIR=... start reading and writing spec pack documents
• Treat "reasonable default" as "confirmed conclusion" and write it into the document
• Skip to modifying/clarifying downstream documents before upstream documents have converged (violating the "source to downstream" order)
• Ask multiple questions at once/give the user multiple adjudication points at once
• The user has answered but you do not immediately write back to the document (only summarize in the conversation)

Common excuses and countermeasures (typical failures from stress testing)

Excuse (source of pressure)	Common violations	Mandatory counter-actions
"Don't ask me questions, just give the result"	Directly fill in TBD with default values and write them back	Clarify: a decision is needed; ask only 1 highest-leverage question and write the conclusion back
"List all the questions at once"	Output a long list, losing prioritization and closure	Ask only 1 question; leave the rest in the document and convert them into verification items/to-dos (traceable)