speckit-checklist-zh

Checklist Purpose: "Unit Tests for Requirements"

• ❌ Not "verify that buttons are clicked correctly"
• ❌ Not "test if error handling works effectively"
• ❌ Not "confirm API returns 200"
• ❌ Not checking if code/implementation conforms to specifications

• ✅ "Are visual hierarchy requirements defined for all card types?" (Completeness)
• ✅ "Is 'prominently displayed' quantified with specific dimensions/positioning?" (Clarity)
• ✅ "Are hover state requirements consistent across all interactive elements?" (Consistency)
• ✅ "Are accessibility requirements defined for keyboard navigation?" (Coverage)
• ✅ "Does the specification define the scenario when logo image fails to load?" (Edge Case)

User Input

$ARGUMENTS

Execution Steps

1. Setup: Run

   {SCRIPT}

   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").
2. 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

     $ARGUMENTS

   • Prioritize precision over breadth
   Generation Algorithm:
   1. 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").
   2. Cluster signals into candidate focus areas (up to 4) sorted by relevance.
   3. Identify potential audience and timing (author, reviewer, QA, release) if unclear.
   4. Detect missing dimensions: scope breadth, depth/rigor, risk focus, exclusion boundaries, measurable acceptance criteria.
   5. 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.
3. Understand User Request: Combine

   $ARGUMENTS

   + 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)
4. 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
5. Generate Checklist - Create "Unit Tests for Requirements":
   • Create the

     FEATURE_DIR/checklists/

     directory if it doesn't exist
   • Generate a unique checklist filename:
     • Use a short, descriptive name based on the domain (e.g.,

       ux.md

       ,

       api.md

       ,

       security.md

       )
     • Format:

       [domain].md

     • Append to the existing file if it already exists
   • Number items sequentially starting from CHK001
   • Each

     speckit-checklist

     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

     [Spec §X.Y]

   • Use

     [Gap]

     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

     [Spec §X.Y]

     , or use tags:

     [Gap]

     ,

     [Ambiguity]

     ,

     [Conflict]

     ,

     [Assumption]

   • 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]?"
6. 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.
7. 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

speckit-checklist

• Multiple checklists of different types (e.g.,

  ux.md

  ,

  test.md

  ,

  security.md

  )
• Simple, memorable filenames indicating the checklist purpose
• Easy identification and navigation in the

  checklists/

  folder

Example Checklist Types and Sample Items

ux.md

• "Is visual hierarchy requirement defined with measurable standards? [Clarity, Spec §FR-1]"
• "Is the quantity and positioning of UI elements clearly defined? [Completeness, Spec §FR-1]"
• "Are interaction state requirements (hover, focus, active) consistently defined? [Consistency]"
• "Are accessibility requirements specified for all interactive elements? [Coverage, Gap]"
• "Is fallback behavior defined when images fail to load? [Edge Case, Gap]"
• "Can 'prominently displayed' be objectively measured? [Measurability, Spec §FR-4]"

api.md

• "Are error response formats specified for all failure scenarios? [Completeness]"
• "Are rate limit requirements quantified with specific thresholds? [Clarity]"
• "Are authentication requirements consistent across all endpoints? [Consistency]"
• "Are retry/timeout requirements defined for external dependencies? [Coverage, Gap]"
• "Is a versioning strategy documented in requirements? [Gap]"

performance.md

• "Are performance requirements quantified with specific metrics? [Clarity]"
• "Are performance targets defined for all critical user journeys? [Coverage]"
• "Are performance requirements specified for different load conditions? [Completeness]"
• "Can performance requirements be objectively measured? [Measurability]"
• "Are degradation requirements defined for high-load scenarios? [Edge Case, Gap]"

security.md

• "Are authentication requirements specified for all protected resources? [Coverage]"
• "Are data protection requirements defined for sensitive information? [Completeness]"
• "Is the threat model documented and aligned with requirements? [Traceability]"
• "Are security requirements consistent with compliance obligations? [Consistency]"
• "Are security failure/breach response requirements defined? [Gap, Exception Flow]"

Counterexamples: What NOT to Do

- [ ] CHK001 - 验证着陆页显示 3 个剧集卡片 [Spec §FR-001]
- [ ] CHK002 - 测试桌面端悬停状态是否正确工作 [Spec §FR-003]
- [ ] CHK003 - 确认徽标点击导航到主页 [Spec §FR-010]
- [ ] CHK004 - 检查相关剧集部分显示 3-5 个项目 [Spec §FR-005]

- [ ] CHK001 - 是否明确定义了特色剧集的数量和布局？ [完整性, Spec §FR-001]
- [ ] CHK002 - 是否为所有交互元素一致定义了悬停状态要求？ [一致性, Spec §FR-003]
- [ ] CHK003 - 是否为所有可点击品牌元素明确了导航要求？ [清晰度, Spec §FR-010]
- [ ] CHK004 - 是否记录了相关剧集的选择标准？ [Gap, Spec §FR-005]
- [ ] CHK005 - 是否为异步剧集数据定义了加载状态要求？ [Gap]
- [ ] CHK006 - 是否可以客观测量"视觉层次"要求？ [可测量性, Spec §FR-001]

• Incorrect: Tests if the system works
• Correct: Tests if requirements are written correctly
• Incorrect: Behavior verification
• Correct: Requirement quality validation
• Incorrect: "Does it do X?"
• Correct: "Is X clearly defined?"