Skip to content

💫 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.md
index 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/` 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.