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 identify "pending clarification/pending confirmation"high-value questions, and throughasking only one question at a timeloop, write conclusions back into 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 verbal conclusions; immediately persist to disk after each decision.

When to use

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

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 in the conversation FEATURE_DIR=...(allowed (reuse)）。
• stop if spec-context fails: if you cannot obtain a valid FEATURE_DIR=..., 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 with 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 writing back: after each completion of "user answer → write back to document/coordinated updates", you must make a git commit before the end of the round, ensuring that each clarification round has a traceable commit point (the commit message must be in Chinese).
• 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 upstream documents cascade to downstream documents, you must start adjusting from the source:

1. First handle unresolved points in the earliest documents (for example first requirements/raw.md, then solution.md, then prd.md …）
2. Only after "the unresolved points in upstream documents are cleared / or have been converted into explicit verification items" may you proceed to clarification and write-back for downstream documents

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

• Blocks implementation/acceptance: scope boundaries, entry flow, 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 targets, canary/release/rollback strategy, dependencies and SLA
• Can be deferred: copy, visual details, non-critical configuration (unless it affects acceptance)

Process (fixed according to the steps you provided)

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 userhas given 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: currently executing spec-context to get context, and echo FEATURE_DIR=..., then go to Step 1。

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

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

• 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/release rollback/contract details

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

• Candidate clarification points: group and arrange bydocument process order; 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 unresolved points; then within that document choose the highest value)
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 sections
5. Immediately git commit: commit only 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.
6. Remove resolved items from the candidate list; if the write-back introduces new uncertain points, add them to the candidate list

When the user pressures you with "stop asking/ask everything at once/just give defaults": still ask only 1 highest-leverage question; the remaining unresolved items must stay in the document and be converted into executable verification items (rather than verbal bookkeeping).

Step 3: Jump-back rules

• If no file is given: after solving every 1–3 problems, return to Step 1 to continue scanning (because write-backs may expose new gaps).
• If a file is given: loop only within that file and its directly related documents; end when the uncertainty points are cleared to zero.

Minimal write-back format (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: clearly write out the rule/caliber/authority/scope/AC (avoid "tentative/to be discussed later")
• Verification item (when still uncertain): turn it into an executable verification item (including: assumption/risk → method → success/failure signal → trigger action), and make clear that it "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 synchronized and updated because of this adjudication (for example, implementation/plan.md 's tasks and verification steps,verification/usecase.md 's use cases and data caliber).

Minimal Git commit steps (execute once after each round of clarification)

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

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 question	Directly fill in a default value and write it back as a conclusion
The user asks you to "ask everything at once"	Ask only the single highest-leverage question; convert the rest into verification items	Throw out a checklist of 20 questions and make the user exhaustedly answer
The user gave a file path	Directly focus on that document and enter Step 2	Skip gated read/write because "there is a path"

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

• Start reading and writing spec pack documents without echoing back FEATURE_DIR=... start reading and writing the spec pack documents
• Write "reasonable default values" into documents as "confirmed conclusions"
• 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 already answered but you did not immediately write back to the document (only summarized in the conversation)

Common excuses and countermeasures (typical failures from stress testing)

Excuse (source of pressure)	Common violation	Required countermeasure
"Don't ask me questions, just give the result"	Directly fill in the TBD with a default value and write it back	Make clear: adjudication is needed; ask only 1 highest-leverage question and write back the conclusion
"List all the questions at once"	Output a long checklist, losing priority and closure	Ask only 1 question; leave the rest in the document and convert them into verification items/to-dos (traceable)