💫 Toolkit to help you get started with SDD or any other process!
Update checklist.md
den (work)08b2a0ae5522
diff --git a/templates/commands/checklist.md b/templates/commands/checklist.mdindex 52b154b88..dfd093451 100644--- a/templates/commands/checklist.md+++ b/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.- * Examples: `ux.md`, `test.md`, `security.md`, `deploy.md`, `review-2.md`- - Use format: `[ ] CHK001 Item description here`+ * If file exists, append to existing file (e.g., use the same UX checklist)- Number items sequentially starting from CHK001- - Group items by category/section if applicable- - Include brief explanations or links where helpful+ - Group items by category/section ONLY using this controlled set:+ - 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:- * Validate scenario coverage and edge cases- * Ensure requirements are clear, testable, and measurable- * 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**:- ```markdown- # [Checklist Type] Checklist: [Feature Name]-- **Purpose**: [Brief description of what this checklist covers]- **Created**: [Date]-- ## [Category 1]- - [ ] CHK001 First item- - [ ] CHK002 Second item-- ## [Category 2]- - [ ] CHK003 Third item- ```+ - **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).+ - 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`.+ - 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.++ **Scenario Modeling & Traceability (MANDATORY)**:+ - Classify scenarios into: Primary, Alternate, Exception/Error, Recovery/Resilience, Non-Functional (performance, reliability, security/privacy, accessibility, observability, scalability, data lifecycle) where applicable.+ - 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).+ - Surface & cluster (+ - Ambiguities (vague terms: "fast", "robust", "secure")+ - Conflicts (contradictory statements)+ - Assumptions (unvalidated premises)+ - Dependencies (external systems, feature flags, migrations, upstream APIs)+ ) — create one resolution item per cluster.+ - Include resilience/rollback coverage when state mutation or migrations occur (partial write, degraded mode, backward compatibility, rollback preconditions).+ - 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.+ - 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/` folderTo 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.