Update checklist.md

templates/commands/checklist.md

@@ -18,7 +18,7 @@ You **MUST** consider the user input before proceeding (if not empty).
 1. **Setup**: Run `{SCRIPT}` from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS list.
    - All file paths must be absolute.
 
-2. **Clarify intent (dynamic)**: Derive THREE contextual clarifying questions (no pre-baked catalog). They MUST:
+2. **Clarify intent (dynamic)**: Derive up to THREE initial contextual clarifying questions (no pre-baked catalog). They MUST:
    - Be generated from the user's phrasing + extracted signals from spec/plan/tasks
    - Only ask about information that materially changes checklist content
    - Be skipped individually if already unambiguous in `$ARGUMENTS`
@@ -29,25 +29,26 @@ You **MUST** consider the user input before proceeding (if not empty).
    2. Cluster signals into candidate focus areas (max 4) ranked by relevance.
    3. Identify probable audience & timing (author, reviewer, QA, release) if not explicit.
    4. Detect missing dimensions: scope breadth, depth/rigor, risk emphasis, exclusion boundaries, measurable acceptance criteria.
-   5. Formulate up to three questions chosen from these archetypes:
+   5. Formulate questions chosen from these archetypes:
       - Scope refinement (e.g., "Should this include integration touchpoints with X and Y or stay 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 by the author only or peers during PR review?")
       - Boundary exclusion (e.g., "Should we explicitly exclude performance tuning items this round?")
+      - Scenario class gap (e.g., "No recovery flows detected—are rollback / partial failure paths in scope?")
 
    Question formatting rules:
    - If presenting options, generate a compact table with columns: Option | Candidate | Why It Matters
    - Limit to A–E options maximum; omit table if a free-form answer is clearer
    - Never ask the user to restate what they already said
-   - Avoid speculative categories (no hallucination). If uncertain, ask explicitly: "Confirm whether X belongs in scope." 
+   - Avoid speculative categories (no hallucination). If uncertain, ask explicitly: "Confirm whether X belongs in scope."
 
    Defaults when interaction impossible:
    - Depth: Standard
    - Audience: Reviewer (PR) if code-related; Author otherwise
    - Focus: Top 2 relevance clusters
 
-   Output the three questions (or fewer if not needed) and wait for answers before continuing. Clearly label each as Q1/Q2/Q3.
+   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.
 
 3. **Understand user request**: Combine `$ARGUMENTS` + clarifying answers:
    - Derive checklist theme (e.g., security, review, deploy, ux)
@@ -66,34 +67,57 @@ You **MUST** consider the user input before proceeding (if not empty).
    - Generate unique checklist filename:
      * Use short, descriptive name based on checklist type
      * Format: `[type].md` (e.g., `ux.md`, `test.md`, `security.md`, `deploy.md`)
-     * If file exists, append counter: `[type]-2.md`, `[type]-3.md`, etc.
+     * If file exists, append to existing file (e.g., use the same UX checklist)
-     * Examples: `ux.md`, `test.md`, `security.md`, `deploy.md`, `review-2.md`
-   - Use format: `[ ] CHK001 Item description here`
    - Number items sequentially starting from CHK001
-   - Group items by category/section if applicable
+   - Group items by category/section ONLY using this controlled set:
-   - Include brief explanations or links where helpful
+       - Primary Flows
+       - Alternate Flows
+       - Exception / Error Flows
+       - Recovery & Resilience
+       - Non-Functional Domains (sub‑grouped or prefixed: Performance, Reliability, Security & Privacy, Accessibility, Observability, Scalability, Data Lifecycle)
+       - Traceability & Coverage
+       - Ambiguities & Conflicts
+       - Assumptions & Dependencies
+   - Do NOT invent ad-hoc categories; merge sparse categories (<2 items) into the closest higher-signal category.
+   - Add traceability refs when possible (order: spec section, acceptance criterion). If no ID system exists, create an item: `Establish requirement & acceptance criteria ID scheme before proceeding`.
+   - Optional brief rationale ONLY if it clarifies requirement intent or risk; never include implementation strategy, code pointers, or test plan details.
    - Each `/checklist` run creates a NEW file (never overwrites existing checklists)
-   - **CRITICAL**: Focus checklist items on **specification and requirements quality** for the domain:
+   - **CRITICAL**: Focus on requirements & scenario coverage quality (NOT implementation). Enforce clarity, completeness, measurability, domain & cross-cutting obligations; surface ambiguities / assumptions / conflicts / dependencies. NEVER include implementation details (tests, code symbols, algorithms, deployment steps).
-     * Validate scenario coverage and edge cases
+   - Soft cap: If raw candidate items > 40, prioritize by risk/impact, consolidate minor edge cases, and add one consolidation item: `Consolidate remaining low-impact scenarios (see source docs) after priority review`.
-     * Ensure requirements are clear, testable, and measurable
+   - Minimum traceability coverage: ≥80% of items MUST include at least one traceability reference (spec section OR acceptance criterion). If impossible (missing structure), add corrective item: `Establish requirement & acceptance criteria ID scheme before proceeding` then proceed.
-     * Check for completeness of acceptance criteria
-     * Verify domain-specific considerations are addressed
-     * DO NOT include implementation details like unit tests, code quality, or deployment steps
 
-6. **Checklist structure**:
+   **Scenario Modeling & Traceability (MANDATORY)**:
-   ```markdown
+   - Classify scenarios into: Primary, Alternate, Exception/Error, Recovery/Resilience, Non-Functional (performance, reliability, security/privacy, accessibility, observability, scalability, data lifecycle) where applicable.
-   # [Checklist Type] Checklist: [Feature Name]
+   - At least one item per present scenario class; if a class is intentionally absent add: `Confirm intentional absence of <Scenario Class> scenarios`.
-   
+   - Each item MUST include ≥1 of: scenario class tag, spec ref `[Spec §X.Y]`, acceptance criterion `[AC-##]`, or marker `(Assumption)/(Dependency)/(Ambiguity)/(Conflict)` (track coverage ratio for ≥80% traceability rule).
-   **Purpose**: [Brief description of what this checklist covers]
+   - Surface & cluster (
-   **Created**: [Date]
+     - Ambiguities (vague terms: "fast", "robust", "secure")
-   
+     - Conflicts (contradictory statements)
-   ## [Category 1]
+     - Assumptions (unvalidated premises)
-   - [ ] CHK001 First item
+     - Dependencies (external systems, feature flags, migrations, upstream APIs)
-   - [ ] CHK002 Second item
+   ) — create one resolution item per cluster.
-   
+   - Include resilience/rollback coverage when state mutation or migrations occur (partial write, degraded mode, backward compatibility, rollback preconditions).
-   ## [Category 2]
+   - BANNED: references to specific tests ("unit test", "integration test"), code symbols, frameworks, algorithmic prescriptions, deployment steps. Rephrase any such user input into requirement clarity or coverage validation.
-   - [ ] CHK003 Third item
+   - If a major scenario lacks acceptance criteria, add an item to define measurable criteria.
-   ```
+
+   **Context Curation (High-Signal Tokens Only)**:
+   - Load only necessary portions of `spec.md`, `plan.md`, `tasks.md` relevant to active focus areas (avoid full-file dumping where sections are irrelevant).
+   - Prefer summarizing long sections into concise scenario/requirement bullets before generating items (compaction principle).
+   - If source docs are large, generate interim summary items (e.g., `Confirm summary of §4 data retention rules is complete`) instead of embedding raw text.
+   - Use progressive disclosure: add follow-on retrieval only if a gap is detected (missing scenario class, unclear constraint).
+   - Treat context budget as finite: do not restate already-tagged requirements verbatim across multiple items.
+   - Merge near-duplicates when: same scenario class + same spec section + overlapping acceptance intent. Keep higher-risk phrasing; add note if consolidation occurred.
+   - Do not repeat identical spec or acceptance refs in >3 items unless covering distinct scenario classes.
+   - If >5 low-impact edge cases (minor parameter permutations), cluster into a single aggregated item.
+   - If user arguments are sparse, prioritize clarifying questions over speculative item generation.
+
+6. **Structure Reference**: Generate the checklist exactly following the canonical template in `templates/checklist-template.md`. Treat that file as the single source of truth for:
+   - Title + meta section placement
+   - Category headings
+   - Checklist line formatting and ID sequencing
+   - Prohibited content (implementation details)
+
+   If (and only if) the canonical file is missing/unreadable, fall back to: H1 title, purpose/created meta lines, then one or more `##` category sections containing `- [ ] CHK### <imperative requirement-quality item>` lines with globally incrementing IDs starting at CHK001. No trailing explanatory footer.
 
 7. **Report**: Output full path to created checklist, item count, and remind user that each run creates a new file. Summarize:
    - Focus areas selected
@@ -101,44 +125,49 @@ You **MUST** consider the user input before proceeding (if not empty).
    - Actor/timing
    - Any explicit user-specified must-have items incorporated
 
-**Important**: Each `/checklist` command invocation creates a NEW checklist file using short, descriptive names. This allows:
+**Important**: Each `/checklist` command invocation creates a checklist file using short, descriptive names unless file already exists. This allows:
+
 - Multiple checklists of different types (e.g., `ux.md`, `test.md`, `security.md`)
 - Simple, memorable filenames that indicate checklist purpose
-- Counter-based uniqueness for duplicate types (e.g., `review-2.md`)
+- Easy identification and navigation in the `checklists/` folder
-- Easy identification and navigation in the checklists/ folder
 
 To avoid clutter, use descriptive types and clean up obsolete checklists when done.
 
 ## Example Checklist Types
 
 **Specification Review:** `spec-review.md`
+
 - Requirement completeness and clarity
 - User scenarios and edge cases coverage
 - Acceptance criteria definition
 - Domain-specific considerations
 
 **Requirements Quality:** `requirements.md`
+
 - Testable and measurable outcomes
 - Stakeholder alignment verification
 - Assumptions and constraints documentation
 - Success metrics definition
 
 **UX/Accessibility Scenarios:** `ux.md` or `a11y.md`
+
 - User journey completeness
 - Accessibility requirement coverage
 - Responsive design considerations
 - Internationalization needs
 
 **Security Requirements:** `security.md`
+
 - Threat model coverage
 - Authentication/authorization requirements
 - Data protection requirements
 - Compliance and regulatory needs
 
 **API/Integration Scenarios:** `api.md`
+
 - Contract completeness
 - Error handling scenarios
 - Backward compatibility considerations
 - Integration touchpoint coverage
 
-Generate checklist items that validate the **quality and completeness of specifications and requirements** for the domain, focusing on scenarios, edge cases, and requirement clarity rather than implementation details.
+Principle reminder: Checklist items validate requirements/scenario coverage quality—not implementation. If in doubt, transform any implementation phrasing into a requirement clarity or coverage validation item.