scripts:
sh: .specify/scripts/bash/check-prerequisites.sh --json
ps: .specify/scripts/powershell/check-prerequisites.ps1 -Json
-
Setup: Run
from the repository root and parse the JSON to get the FEATURE_DIR and AVAILABLE_DOCS list.
- All file paths must be absolute.
- For single quotes in arguments, such as "I'm Groot", use escape syntax: e.g., 'I'''m Groot' (or use double quotes if possible: "I'm Groot").
-
Clarify Intent (Dynamic): Derive up to three initial context-clarifying questions (no preset categories). They must:
- Be generated from the user's wording + signals extracted from specifications/plans/tasks
- Only ask for information that would substantially change the checklist content
- Be skipped individually if already explicitly stated in
- Prioritize precision over breadth
Generation Algorithm:
- Extract signals: functional domain keywords (e.g., auth, latency, UX, API), risk indicators ("critical", "must", "compliance"), stakeholder cues ("QA", "review", "security team") and explicit deliverables ("a11y", "rollback", "contracts").
- Cluster signals into candidate focus areas (up to 4) sorted by relevance.
- Identify potential audience and timing (author, reviewer, QA, release) if unclear.
- Detect missing dimensions: scope breadth, depth/rigor, risk focus, exclusion boundaries, measurable acceptance criteria.
- Formulate questions from these prototypes:
- Scope refinement (e.g., "Should this include integration touchpoints with X and Y or be limited to local module correctness?")
- Risk prioritization (e.g., "Which of these potential risk areas should receive mandatory gating checks?")
- Depth calibration (e.g., "Is this a lightweight pre-commit sanity list or a formal release gate?")
- Audience framing (e.g., "Will this be used only by authors or by peers during PR reviews?")
- Boundary exclusion (e.g., "Should we explicitly exclude performance tuning items in this round?")
- Scenario category gaps (e.g., "No recovery processes detected - are rollback/partial failure paths in scope?")
Question Format Rules:
- If providing options, generate a compact table with columns: Option | Candidate | Reason for Importance
- Limit to maximum A-E options; omit the table if free-form answers are clearer
- Never ask users to restate what they've already said
- Avoid speculative categories (no hallucinations). If unsure, explicitly ask: "Confirm if X is in scope."
Default Values When Interaction Is Not Possible:
- Depth: Standard
- Audience: Reviewer (PR) if code-related; otherwise Author
- Focus: Top 2 relevance clusters
Output questions (marked Q1/Q2/Q3). After answers: If ≥2 scenario categories (alternative/exception/recovery/non-functional domains) are still unclear, you may ask up to two more targeted follow-up questions (Q4/Q5), each with a one-line rationale (e.g., "Unresolved recovery path risk"). Do not exceed five total questions. Skip escalation if the user explicitly declines more questions.
-
Understand User Request: Combine
+ clarification answers:
- Derive the checklist topic (e.g., security, review, deployment, user experience)
- Integrate explicit mandatory items mentioned by the user
- Map focus selections to category scaffolding
- Infer any missing context from specifications/plans/tasks (no hallucinations)
-
Load Feature Context: Read from FEATURE_DIR:
- spec.md: Feature requirements and scope
- plan.md (if exists): Technical details, dependencies
- tasks.md (if exists): Implementation tasks
Context Loading Strategy:
- Only load necessary parts relevant to active focus areas (avoid full file dumps)
- Prefer summarizing long paragraphs into concise scenario/requirement bullet points
- Use progressive disclosure: Add follow-up retrieval only when gaps are detected
- If source documents are large, generate intermediate summary items instead of embedding raw text
-
Generate Checklist - Create "Unit Tests for Requirements":
- Create the directory if it doesn't exist
- Generate a unique checklist filename:
- Use a short, descriptive name based on the domain (e.g., , , )
- Format:
- Append to the existing file if it already exists
- Number items sequentially starting from CHK001
- Each run creates a new file (never overwrite existing checklists)
Core Principle - Test Requirements, Not Implementation: Each checklist item must evaluate the requirements themselves:
- Completeness: Are all necessary requirements present?
- Clarity: Are requirements explicit and specific?
- Consistency: Are requirements aligned with each other?
- Measurability: Can requirements be objectively verified?
- Coverage: Are all scenarios/edge cases addressed?
Category Structure - Group items by requirement quality dimensions:
- Requirement Completeness (Are all necessary requirements documented?)
- Requirement Clarity (Are requirements specific and unambiguous?)
- Requirement Consistency (Are requirements aligned without conflicts?)
- Acceptance Criteria Quality (Are success criteria measurable?)
- Scenario Coverage (Are all processes/cases addressed?)
- Edge Case Coverage (Are boundary conditions defined?)
- Non-Functional Requirements (Performance, security, accessibility, etc. - are they specified?)
- Dependencies and Assumptions (Are they documented and verified?)
- Ambiguities and Conflicts (What needs clarification?)
How to Write Checklist Items - "English Unit Tests":
❌ Incorrect (Testing Implementation):
- "Verify that the landing page displays 3 episode cards"
- "Test that desktop hover states work correctly"
- "Confirm that logo click navigates to homepage"
✅ Correct (Testing Requirement Quality):
- "Is the exact number and layout of featured episodes explicitly specified?" [Completeness]
- "Is 'prominently displayed' quantified with specific dimensions/positioning?" [Clarity]
- "Are hover state requirements consistent across all interactive elements?" [Consistency]
- "Are keyboard navigation requirements defined for all interactive UI elements?" [Coverage]
- "Is fallback behavior specified when logo image fails to load?" [Edge Case]
- "Are loading states defined for asynchronous episode data?" [Completeness]
- "Does the specification define the visual hierarchy of competing UI elements?" [Clarity]
Item Structure: Each item should follow this pattern:
- Question format that evaluates requirement quality
- Focus on what is (or is not) written in specifications/plans
- Include the quality dimension in brackets [Completeness/Clarity/Consistency, etc.]
- Reference specification sections when checking existing requirements
- Use to mark missing requirements
Examples by Quality Dimension:
Completeness:
- "Are error handling requirements defined for all API failure modes? [Gap]"
- "Are accessibility requirements specified for all interactive elements? [Completeness]"
- "Are mobile breakpoint requirements defined for responsive layouts? [Gap]"
Clarity:
- "Is 'fast loading' quantified with specific time thresholds? [Clarity, Spec §NFR-2]"
- "Is the selection criteria for 'related episodes' clearly defined? [Clarity, Spec §FR-5]"
- "Is 'prominent' defined with measurable visual attributes? [Ambiguity, Spec §FR-4]"
Consistency:
- "Are navigation requirements aligned across all pages? [Consistency, Spec §FR-10]"
- "Are card component requirements consistent between landing page and detail page? [Consistency]"
Coverage:
- "Are requirements defined for zero-state scenarios (no episodes)? [Coverage, Edge Case]"
- "Are concurrent user interaction scenarios addressed? [Coverage, Gap]"
- "Are requirements specified for partial data loading failures? [Coverage, Exception Flow]"
Measurability:
- "Are visual hierarchy requirements measurable/testable? [Acceptance Criteria, Spec §FR-1]"
- "Can 'balanced visual weight' be objectively verified? [Measurability, Spec §FR-2]"
Scenario Classification and Coverage (Focus on Requirement Quality):
- Check for presence of requirements: primary, alternative, exception/error, recovery, non-functional scenarios
- For each scenario category, ask: "Are [scenario type] requirements complete, clear, and consistent?"
- If a scenario category is missing: "Are [scenario type] requirements intentionally excluded or missing? [Gap]"
- Include resilience/rollback for state changes: "Are rollback requirements defined for migration failures? [Gap]"
Traceability Requirements:
- Minimum requirement: ≥80% of items must include at least one traceability reference
- Each item should reference: specification section , or use tags: , , ,
- If no ID system exists: "Is a requirement and acceptance criteria ID scheme established? [Traceability]"
Surface and Resolve Issues (Requirement Quality Problems): Ask questions about the requirements themselves:
- Ambiguity: "Is the term 'fast' quantified with specific metrics? [Ambiguity, Spec §NFR-1]"
- Conflict: "Do navigation requirements in §FR-10 and §FR-10a conflict? [Conflict]"
- Assumption: "Is the 'always available podcast API' assumption verified? [Assumption]"
- Dependency: "Are external podcast API requirements documented? [Dependency, Gap]"
- Missing Definition: "Is 'visual hierarchy' defined with measurable standards? [Gap]"
Content Integration:
- Soft cap: If original candidate items >40, prioritize by risk/impact
- Merge near-duplicates that check the same aspect of requirements
- If >5 low-impact edge cases, create one item: "Are edge cases X, Y, Z addressed in requirements? [Coverage]"
🚫 Absolute Prohibitions - These make it an implementation test, not a requirement test:
- ❌ Any item starting with "verify", "test", "confirm", "check" + implementation behavior
- ❌ References to code execution, user actions, system behavior
- ❌ "Display correctly", "work properly", "function as expected"
- ❌ "Click", "navigate", "render", "load", "execute"
- ❌ Test cases, test plans, QA procedures
- ❌ Implementation details (frameworks, APIs, algorithms)
✅ Required Patterns - These test requirement quality:
- ✅ "Are [requirement type] defined/specified/documented for [scenario]?"
- ✅ "Is [ambiguous term] quantified/clarified with specific standards?"
- ✅ "Are requirements for [Part A] and [Part B] consistent?"
- ✅ "Can [requirement] be objectively measured/verified?"
- ✅ "Is [edge case/scenario] addressed in requirements?"
- ✅ "Does the specification define [missing aspect]?"
-
Structure Reference: Generate the checklist following the specification template in
.specify/templates/checklist-template.md
, including title, meta section, category headers, and ID format. If the template is unavailable, use: H1 title, meta lines for purpose/creation,
category sections containing
- [ ] CHK### <requirement item>
lines, with globally incrementing IDs starting from CHK001.
-
Report: Output the full path of the created checklist, item count, and remind users that each run creates a new file. Summarize:
- Selected focus areas
- Depth level
- Participants/timing
- Any explicit mandatory items included from the user
Important: Each
command invocation creates a checklist file with a short, descriptive name, unless the file already exists. This allows:
To avoid clutter, use descriptive types and clean up outdated checklists after completion.