templates/commands/checklist.md
CRITICAL CONCEPT: Checklists are UNIT TESTS FOR REQUIREMENTS WRITING - they validate the quality, clarity, and completeness of requirements in a given domain.
NOT for verification/testing:
FOR requirements quality validation:
Metaphor: If your spec is code written in English, the checklist is its unit test suite. You're testing whether the requirements are well-written, complete, unambiguous, and ready for implementation - NOT whether the implementation works.
$ARGUMENTS
You MUST consider the user input before proceeding (if not empty).
Check for extension hooks (before checklist generation):
.specify/extensions.yml exists in the project root.hooks.before_checklist keyenabled is explicitly false. Treat hooks without an enabled field as enabled by default.condition expressions:
condition field, or it is null/empty, treat the hook as executablecondition, skip the hook and leave condition evaluation to the HookExecutor implementationoptional flag:
optional: true):
## Extension Hooks
**Optional Pre-Hook**: {extension}
Command: `/{command}`
Description: {description}
Prompt: {prompt}
To execute: `/{command}`
optional: false):
## Extension Hooks
**Automatic Pre-Hook**: {extension}
Executing: `/{command}`
EXECUTE_COMMAND: {command}
Wait for the result of the hook command before proceeding to the Execution Steps.
.specify/extensions.yml does not exist, skip silentlySetup: Run {SCRIPT} from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS list.
Clarify intent (dynamic): Derive up to THREE initial contextual clarifying questions (no pre-baked catalog). They MUST:
$ARGUMENTSGeneration algorithm:
Question formatting rules:
Defaults when interaction impossible:
Output the questions (label Q1/Q2/Q3). After answers: if ≥2 scenario classes (Alternate / Exception / Recovery / Non-Functional domain) remain unclear, you MAY ask up to TWO more targeted follow‑ups (Q4/Q5) with a one-line justification each (e.g., "Unresolved recovery path risk"). Do not exceed five total questions. Skip escalation if user explicitly declines more.
Understand user request: Combine $ARGUMENTS + clarifying answers:
Load feature context: Read from FEATURE_DIR:
Context Loading Strategy:
Generate checklist - Create "Unit Tests for Requirements":
FEATURE_DIR/checklists/ directory if it doesn't existux.md, api.md, security.md)[domain].mdCORE PRINCIPLE - Test the Requirements, Not the Implementation: Every checklist item MUST evaluate the REQUIREMENTS THEMSELVES for:
Category Structure - Group items by requirement quality dimensions:
HOW TO WRITE CHECKLIST ITEMS - "Unit Tests for English":
❌ WRONG (Testing implementation):
✅ CORRECT (Testing requirements quality):
ITEM STRUCTURE: Each item should follow this pattern:
[Spec §X.Y] when checking existing requirements[Gap] marker when checking for missing requirementsEXAMPLES BY QUALITY DIMENSION:
Completeness:
Clarity:
Consistency:
Coverage:
Measurability:
Scenario Classification & Coverage (Requirements Quality Focus):
Traceability Requirements:
[Spec §X.Y], or use markers: [Gap], [Ambiguity], [Conflict], [Assumption]Surface & Resolve Issues (Requirements Quality Problems): Ask questions about the requirements themselves:
Content Consolidation:
🚫 ABSOLUTELY PROHIBITED - These make it an implementation test, not a requirements test:
✅ REQUIRED PATTERNS - These test requirements quality:
Structure Reference: Generate the checklist following the canonical template in templates/checklist-template.md for title, meta section, category headings, and ID formatting. If template is unavailable, use: H1 title, purpose/created meta lines, ## category sections containing - [ ] CHK### <requirement item> lines with globally incrementing IDs starting at CHK001.
Report: Output full path to checklist file, item count, and summarize whether the run created a new file or appended to an existing one. Summarize:
Important: Each __SPECKIT_COMMAND_CHECKLIST__ command invocation uses a short, descriptive checklist filename and either creates a new file or appends to an existing one. This allows:
ux.md, test.md, security.md)checklists/ folderTo avoid clutter, use descriptive types and clean up obsolete checklists when done.
UX Requirements Quality: ux.md
Sample items (testing the requirements, NOT the implementation):
API Requirements Quality: api.md
Sample items:
Performance Requirements Quality: performance.md
Sample items:
Security Requirements Quality: security.md
Sample items:
❌ WRONG - These test implementation, not requirements:
- [ ] CHK001 - Verify landing page displays 3 episode cards [Spec §FR-001]
- [ ] CHK002 - Test hover states work correctly on desktop [Spec §FR-003]
- [ ] CHK003 - Confirm logo click navigates to home page [Spec §FR-010]
- [ ] CHK004 - Check that related episodes section shows 3-5 items [Spec §FR-005]
✅ CORRECT - These test requirements quality:
- [ ] CHK001 - Are the number and layout of featured episodes explicitly specified? [Completeness, Spec §FR-001]
- [ ] CHK002 - Are hover state requirements consistently defined for all interactive elements? [Consistency, Spec §FR-003]
- [ ] CHK003 - Are navigation requirements clear for all clickable brand elements? [Clarity, Spec §FR-010]
- [ ] CHK004 - Is the selection criteria for related episodes documented? [Gap, Spec §FR-005]
- [ ] CHK005 - Are loading state requirements defined for asynchronous episode data? [Gap]
- [ ] CHK006 - Can "visual hierarchy" requirements be objectively measured? [Measurability, Spec §FR-001]
Key Differences:
Check for extension hooks (after checklist generation):
Check if .specify/extensions.yml exists in the project root.
hooks.after_checklist keyenabled is explicitly false. Treat hooks without an enabled field as enabled by default.condition expressions:
condition field, or it is null/empty, treat the hook as executablecondition, skip the hook and leave condition evaluation to the HookExecutor implementationoptional flag:
optional: true):
## Extension Hooks
**Optional Hook**: {extension}
Command: `/{command}`
Description: {description}
Prompt: {prompt}
To execute: `/{command}`
optional: false):
## Extension Hooks
**Automatic Hook**: {extension}
Executing: `/{command}`
EXECUTE_COMMAND: {command}
.specify/extensions.yml does not exist, skip silently