Update templates

templates/commands/checklist.md

@@ -5,6 +5,24 @@ scripts:
   ps: scripts/powershell/check-prerequisites.ps1 -Json
 ---
 
+## Checklist Purpose
+
+**CRITICAL CLARIFICATION**: Checklists generated by this command are for **requirements validation**, NOT:
+- ❌ Verifying code execution or functionality
+- ❌ Testing whether code matches the specification
+- ❌ Checking implementation correctness
+- ❌ Code review or quality assurance
+
+**What checklists ARE for**:
+- ✅ Ensuring requirements are clearly captured and complete
+- ✅ Identifying ambiguities in specifications or plans
+- ✅ Verifying proper scenario coverage across the spec and plan
+- ✅ Confirming acceptance criteria are well-defined and measurable
+- ✅ Detecting gaps, conflicts, or missing edge cases in requirements
+- ✅ Validating that the problem domain is properly understood before implementation
+
+Think of checklists as a **pre-implementation review** to ensure the spec and plan are solid, not a post-implementation verification tool.
+
 ## User Input
 
 ```text
@@ -88,23 +106,25 @@ You **MUST** consider the user input before proceeding (if not empty).
    
    Do NOT invent ad-hoc categories; merge sparse categories (<2 items) into the closest higher-signal category.
 
-   **Scenario Classification & Coverage**:
+   **Scenario Classification & Coverage** (Requirements Validation Focus):
    - Classify scenarios into: Primary, Alternate, Exception/Error, Recovery/Resilience, Non-Functional
    - At least one item per present scenario class; if intentionally absent add: `Confirm intentional absence of <Scenario Class> scenarios`
    - Include resilience/rollback coverage when state mutation or migrations occur (partial write, degraded mode, backward compatibility, rollback preconditions)
    - If a major scenario lacks acceptance criteria, add an item to define measurable criteria
+   - **Focus on requirements validation**: Are scenarios clearly defined? Are acceptance criteria measurable? Are edge cases identified in the spec?
 
    **Traceability Requirements**:
    - MINIMUM: ≥80% of items MUST include at least one traceability reference
    - Each item should include ≥1 of: scenario class tag, spec ref `[Spec §X.Y]`, acceptance criterion `[AC-##]`, or marker `(Assumption)/(Dependency)/(Ambiguity)/(Conflict)`
    - If no ID system exists, create an item: `Establish requirement & acceptance criteria ID scheme before proceeding`
 
-   **Surface & Resolve Issues**:
+   **Surface & Resolve Issues** (Pre-Implementation Validation):
    - Cluster and create one resolution item per cluster for:
-     - Ambiguities (vague terms: "fast", "robust", "secure")
-     - Conflicts (contradictory statements)
-     - Assumptions (unvalidated premises)
-     - Dependencies (external systems, feature flags, migrations, upstream APIs)
+     - Ambiguities (vague terms in spec: "fast", "robust", "secure" - these need quantification)
+     - Conflicts (contradictory statements in requirements)
+     - Assumptions (unvalidated premises in the spec or plan)
+     - Dependencies (external systems, feature flags, migrations, upstream APIs - are they documented?)
+   - Items should focus on "Is this requirement clear enough to implement?" not "Does the code work?"
 
    **Content Consolidation**:
    - Soft cap: If raw candidate items > 40, prioritize by risk/impact and add: `Consolidate remaining low-impact scenarios (see source docs) after priority review`
@@ -119,6 +139,16 @@ You **MUST** consider the user input before proceeding (if not empty).
    - Rephrase any such user input into requirement clarity or coverage validation
    - Optional brief rationale ONLY if it clarifies requirement intent or risk
 
+   **✅ HOW TO PHRASE CHECKLIST ITEMS** (Requirements Validation):
+   - Good: "Verify error handling scenarios are defined for network failures"
+   - Bad: "Test error handling for network failures"
+   - Good: "Confirm acceptance criteria are measurable for performance requirements"
+   - Bad: "Run performance tests to verify requirements"
+   - Good: "Identify edge cases for concurrent user access in spec"
+   - Bad: "Implement thread-safe concurrent access"
+   - Good: "Clarify ambiguous term 'fast response' with specific timing requirements"
+   - Bad: "Verify response time is under 100ms"
+
 6. **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.
 
 7. **Report**: Output full path to created checklist, item count, and remind user that each run creates a new file. Summarize: