💫 Toolkit to help you get started with SDD or any other process!
Consistency updates to commands
den (work)8374777206c9
diff --git a/templates/commands/analyze.md b/templates/commands/analyze.mdindex ef418dc0a..ab11284c2 100644--- a/templates/commands/analyze.md+++ b/templates/commands/analyze.md@@ -5,100 +5,182 @@ scripts:ps: scripts/powershell/check-prerequisites.ps1 -Json -RequireTasks -IncludeTasks----The user input to you can be provided directly by the agent or as a command argument - you **MUST** consider it before proceeding with the prompt (if not empty).--User input:--`$ARGUMENTS-`-Goal: Identify inconsistencies, duplications, ambiguities, and underspecified items across the three core artifacts (`spec.md`, `plan.md`, `tasks.md`) before implementation. This command MUST run only after `/tasks` has successfully produced a complete `tasks.md`.--STRICTLY READ-ONLY: Do **not** modify any files. Output a structured analysis report. Offer an optional remediation plan (user must explicitly approve before any follow-up editing commands would be invoked manually).--Constitution Authority: The project constitution (`/memory/constitution.md`) is **non-negotiable** within this analysis scope. Constitution conflicts are automatically CRITICAL and require adjustment of the spec, plan, or tasks—not dilution, reinterpretation, or silent ignoring of the principle. If a principle itself needs to change, that must occur in a separate, explicit constitution update outside `/analyze`.--Execution steps:--1. Run `{SCRIPT}` once from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS. Derive absolute paths:- - SPEC = FEATURE_DIR/spec.md- - PLAN = FEATURE_DIR/plan.md- - TASKS = FEATURE_DIR/tasks.md- Abort with an error message if any required file is missing (instruct the user to run missing prerequisite command).--2. Load artifacts:- - Parse spec.md sections: Overview/Context, Functional Requirements, Non-Functional Requirements, User Stories, Edge Cases (if present).- - Parse plan.md: Architecture/stack choices, Data Model references, Phases, Technical constraints.- - Parse tasks.md: Task IDs, descriptions, phase grouping, parallel markers [P], referenced file paths.- - Load constitution `/memory/constitution.md` for principle validation.--3. Build internal semantic models:- - Requirements inventory: Each functional + non-functional requirement with a stable key (derive slug based on imperative phrase; e.g., "User can upload file" -> `user-can-upload-file`).- - User story/action inventory.- - Task coverage mapping: Map each task to one or more requirements or stories (inference by keyword / explicit reference patterns like IDs or key phrases).- - Constitution rule set: Extract principle names and any MUST/SHOULD normative statements.--4. Detection passes:- A. Duplication detection:- - Identify near-duplicate requirements. Mark lower-quality phrasing for consolidation.- B. Ambiguity detection:- - Flag vague adjectives (fast, scalable, secure, intuitive, robust) lacking measurable criteria.- - Flag unresolved placeholders (TODO, TKTK, ???, <placeholder>, etc.).- C. Underspecification:- - Requirements with verbs but missing object or measurable outcome.- - User stories missing acceptance criteria alignment.- - Tasks referencing files or components not defined in spec/plan.- D. Constitution alignment:- - Any requirement or plan element conflicting with a MUST principle.- - Missing mandated sections or quality gates from constitution.- E. Coverage gaps:- - Requirements with zero associated tasks.- - Tasks with no mapped requirement/story.- - Non-functional requirements not reflected in tasks (e.g., performance, security).- F. Inconsistency:- - Terminology drift (same concept named differently across files).- - Data entities referenced in plan but absent in spec (or vice versa).- - Task ordering contradictions (e.g., integration tasks before foundational setup tasks without dependency note).- - Conflicting requirements (e.g., one requires to use Next.js while other says to use Vue as the framework).--5. Severity assignment heuristic:- - CRITICAL: Violates constitution MUST, missing core spec artifact, or requirement with zero coverage that blocks baseline functionality.- - HIGH: Duplicate or conflicting requirement, ambiguous security/performance attribute, untestable acceptance criterion.- - MEDIUM: Terminology drift, missing non-functional task coverage, underspecified edge case.- - LOW: Style/wording improvements, minor redundancy not affecting execution order.--6. Produce a Markdown report (no file writes) with sections:-- ### Specification Analysis Report- | ID | Category | Severity | Location(s) | Summary | Recommendation |- |----|----------|----------|-------------|---------|----------------|- | A1 | Duplication | HIGH | spec.md:L120-134 | Two similar requirements ... | Merge phrasing; keep clearer version |- (Add one row per finding; generate stable IDs prefixed by category initial.)-- Additional subsections:- - Coverage Summary Table:- | Requirement Key | Has Task? | Task IDs | Notes |- - Constitution Alignment Issues (if any)- - Unmapped Tasks (if any)- - Metrics:- * Total Requirements- * Total Tasks- * Coverage % (requirements with >=1 task)- * Ambiguity Count- * Duplication Count- * Critical Issues Count--7. At end of report, output a concise Next Actions block:- - If CRITICAL issues exist: Recommend resolving before `/implement`.- - If only LOW/MEDIUM: User may proceed, but provide improvement suggestions.- - Provide explicit command suggestions: e.g., "Run /specify with refinement", "Run /plan to adjust architecture", "Manually edit tasks.md to add coverage for 'performance-metrics'".--8. Ask the user: "Would you like me to suggest concrete remediation edits for the top N issues?" (Do NOT apply them automatically.)--Behavior rules:-- NEVER modify files.-- NEVER hallucinate missing sections—if absent, report them.-- KEEP findings deterministic: if rerun without changes, produce consistent IDs and counts.-- LIMIT total findings in the main table to 50; aggregate remainder in a summarized overflow note.-- If zero issues found, emit a success report with coverage statistics and proceed recommendation.--Context: {ARGS}+## User Input++```text+$ARGUMENTS+```++You **MUST** consider the user input before proceeding (if not empty).++## Goal++Identify inconsistencies, duplications, ambiguities, and underspecified items across the three core artifacts (`spec.md`, `plan.md`, `tasks.md`) before implementation. This command MUST run only after `/tasks` has successfully produced a complete `tasks.md`.++## Operating Constraints++**STRICTLY READ-ONLY**: Do **not** modify any files. Output a structured analysis report. Offer an optional remediation plan (user must explicitly approve before any follow-up editing commands would be invoked manually).++**Constitution Authority**: The project constitution (`/memory/constitution.md`) is **non-negotiable** within this analysis scope. Constitution conflicts are automatically CRITICAL and require adjustment of the spec, plan, or tasks—not dilution, reinterpretation, or silent ignoring of the principle. If a principle itself needs to change, that must occur in a separate, explicit constitution update outside `/analyze`.++## Execution Steps++### 1. Initialize Analysis Context++Run `{SCRIPT}` once from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS. Derive absolute paths:++- SPEC = FEATURE_DIR/spec.md+- PLAN = FEATURE_DIR/plan.md+- TASKS = FEATURE_DIR/tasks.md++Abort with an error message if any required file is missing (instruct the user to run missing prerequisite command).++### 2. Load Artifacts (Progressive Disclosure)++Load only the minimal necessary context from each artifact:++**From spec.md:**++- Overview/Context+- Functional Requirements+- Non-Functional Requirements+- User Stories+- Edge Cases (if present)++**From plan.md:**++- Architecture/stack choices+- Data Model references+- Phases+- Technical constraints++**From tasks.md:**++- Task IDs+- Descriptions+- Phase grouping+- Parallel markers [P]+- Referenced file paths++**From constitution:**++- Load `/memory/constitution.md` for principle validation++### 3. Build Semantic Models++Create internal representations (do not include raw artifacts in output):++- **Requirements inventory**: Each functional + non-functional requirement with a stable key (derive slug based on imperative phrase; e.g., "User can upload file" → `user-can-upload-file`)+- **User story/action inventory**: Discrete user actions with acceptance criteria+- **Task coverage mapping**: Map each task to one or more requirements or stories (inference by keyword / explicit reference patterns like IDs or key phrases)+- **Constitution rule set**: Extract principle names and MUST/SHOULD normative statements++### 4. Detection Passes (Token-Efficient Analysis)++Focus on high-signal findings. Limit to 50 findings total; aggregate remainder in overflow summary.++#### A. Duplication Detection++- Identify near-duplicate requirements+- Mark lower-quality phrasing for consolidation++#### B. Ambiguity Detection++- Flag vague adjectives (fast, scalable, secure, intuitive, robust) lacking measurable criteria+- Flag unresolved placeholders (TODO, TKTK, ???, `<placeholder>`, etc.)++#### C. Underspecification++- Requirements with verbs but missing object or measurable outcome+- User stories missing acceptance criteria alignment+- Tasks referencing files or components not defined in spec/plan++#### D. Constitution Alignment++- Any requirement or plan element conflicting with a MUST principle+- Missing mandated sections or quality gates from constitution++#### E. Coverage Gaps++- Requirements with zero associated tasks+- Tasks with no mapped requirement/story+- Non-functional requirements not reflected in tasks (e.g., performance, security)++#### F. Inconsistency++- Terminology drift (same concept named differently across files)+- Data entities referenced in plan but absent in spec (or vice versa)+- Task ordering contradictions (e.g., integration tasks before foundational setup tasks without dependency note)+- Conflicting requirements (e.g., one requires Next.js while other specifies Vue)++### 5. Severity Assignment++Use this heuristic to prioritize findings:++- **CRITICAL**: Violates constitution MUST, missing core spec artifact, or requirement with zero coverage that blocks baseline functionality+- **HIGH**: Duplicate or conflicting requirement, ambiguous security/performance attribute, untestable acceptance criterion+- **MEDIUM**: Terminology drift, missing non-functional task coverage, underspecified edge case+- **LOW**: Style/wording improvements, minor redundancy not affecting execution order++### 6. Produce Compact Analysis Report++Output a Markdown report (no file writes) with the following structure:++## Specification Analysis Report++| ID | Category | Severity | Location(s) | Summary | Recommendation |+|----|----------|----------|-------------|---------|----------------|+| A1 | Duplication | HIGH | spec.md:L120-134 | Two similar requirements ... | Merge phrasing; keep clearer version |++(Add one row per finding; generate stable IDs prefixed by category initial.)++**Coverage Summary Table:**++| Requirement Key | Has Task? | Task IDs | Notes |+|-----------------|-----------|----------|-------|++**Constitution Alignment Issues:** (if any)++**Unmapped Tasks:** (if any)++**Metrics:**++- Total Requirements+- Total Tasks+- Coverage % (requirements with >=1 task)+- Ambiguity Count+- Duplication Count+- Critical Issues Count++### 7. Provide Next Actions++At end of report, output a concise Next Actions block:++- If CRITICAL issues exist: Recommend resolving before `/implement`+- If only LOW/MEDIUM: User may proceed, but provide improvement suggestions+- Provide explicit command suggestions: e.g., "Run /specify with refinement", "Run /plan to adjust architecture", "Manually edit tasks.md to add coverage for 'performance-metrics'"++### 8. Offer Remediation++Ask the user: "Would you like me to suggest concrete remediation edits for the top N issues?" (Do NOT apply them automatically.)++## Operating Principles++### Context Efficiency++- **Minimal high-signal tokens**: Focus on actionable findings, not exhaustive documentation+- **Progressive disclosure**: Load artifacts incrementally; don't dump all content into analysis+- **Token-efficient output**: Limit findings table to 50 rows; summarize overflow+- **Deterministic results**: Rerunning without changes should produce consistent IDs and counts++### Analysis Guidelines++- **NEVER modify files** (this is read-only analysis)+- **NEVER hallucinate missing sections** (if absent, report them accurately)+- **Prioritize constitution violations** (these are always CRITICAL)+- **Use examples over exhaustive rules** (cite specific instances, not generic patterns)+- **Report zero issues gracefully** (emit success report with coverage statistics)++## Context++{ARGS}diff --git a/templates/commands/checklist.md b/templates/commands/checklist.mdindex 7465527b3..b21737c07 100644--- a/templates/commands/checklist.md+++ b/templates/commands/checklist.md@@ -5,12 +5,14 @@ scripts:ps: scripts/powershell/check-prerequisites.ps1 -Json----The user input to you can be provided directly by the agent or as a command argument - you **MUST** consider it before proceeding with the prompt (if not empty).+## User Input-User input:+```text+$ARGUMENTS+```++You **MUST** consider the user input before proceeding (if not empty).-`$ARGUMENTS-`## Execution Steps1. **Setup**: Run `{SCRIPT}` from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS list.diff --git a/templates/commands/clarify.md b/templates/commands/clarify.mdindex c5821623e..eed35410b 100644--- a/templates/commands/clarify.md+++ b/templates/commands/clarify.md@@ -5,11 +5,15 @@ scripts:ps: scripts/powershell/check-prerequisites.ps1 -Json -PathsOnly----The user input to you can be provided directly by the agent or as a command argument - you **MUST** consider it before proceeding with the prompt (if not empty).+## User Input-User input:+```text+$ARGUMENTS+```-`$ARGUMENTS`+You **MUST** consider the user input before proceeding (if not empty).++## OutlineGoal: Detect and reduce ambiguity or missing decision points in the active feature specification and record the clarifications directly in the spec file.diff --git a/templates/commands/constitution.md b/templates/commands/constitution.mdindex c8b37912d..f6f8b2431 100644--- a/templates/commands/constitution.md+++ b/templates/commands/constitution.md@@ -2,11 +2,15 @@description: Create or update the project constitution from interactive or provided principle inputs, ensuring all dependent templates stay in sync.----The user input to you can be provided directly by the agent or as a command argument - you **MUST** consider it before proceeding with the prompt (if not empty).+## User Input-User input:+```text+$ARGUMENTS+```-`$ARGUMENTS`+You **MUST** consider the user input before proceeding (if not empty).++## OutlineYou are updating the project constitution at `/memory/constitution.md`. This file is a TEMPLATE containing placeholder tokens in square brackets (e.g. `[PROJECT_NAME]`, `[PRINCIPLE_1_NAME]`). Your job is to (a) collect/derive concrete values, (b) fill the template precisely, and (c) propagate any amendments across dependent artifacts.diff --git a/templates/commands/implement.md b/templates/commands/implement.mdindex bc20db016..6478e9e79 100644--- a/templates/commands/implement.md+++ b/templates/commands/implement.md@@ -5,11 +5,15 @@ scripts:ps: scripts/powershell/check-prerequisites.ps1 -Json -RequireTasks -IncludeTasks----The user input can be provided directly by the agent or as a command argument - you **MUST** consider it before proceeding with the prompt (if not empty).+## User Input-User input:+```text+$ARGUMENTS+```-`$ARGUMENTS`+You **MUST** consider the user input before proceeding (if not empty).++## Outline1. Run `{SCRIPT}` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute.diff --git a/templates/commands/plan.md b/templates/commands/plan.mdindex 37b4851fb..7348ada4f 100644--- a/templates/commands/plan.md+++ b/templates/commands/plan.md@@ -8,13 +8,15 @@ agent_scripts:ps: scripts/powershell/update-agent-context.ps1 -AgentType __AGENT__----The user input to you can be provided directly by the agent or as a command argument - you **MUST** consider it before proceeding with the prompt (if not empty).+## User Input-User input:+```text+$ARGUMENTS+```-`$ARGUMENTS`+You **MUST** consider the user input before proceeding (if not empty).-## Execution Steps+## Outline1. **Setup**: Run `{SCRIPT}` from repo root and parse JSON for FEATURE_SPEC, IMPL_PLAN, SPECS_DIR, BRANCH.- Before proceeding: Check FEATURE_SPEC has `## Clarifications` section. If missing or ambiguous, instruct user to run `/clarify` first.diff --git a/templates/commands/specify.md b/templates/commands/specify.mdindex d9e1e2fef..357c00831 100644--- a/templates/commands/specify.md+++ b/templates/commands/specify.md@@ -5,11 +5,15 @@ scripts:ps: scripts/powershell/create-new-feature.ps1 -Json "{ARGS}"----The user input to you can be provided directly by the agent or as a command argument - you **MUST** consider it before proceeding with the prompt (if not empty).+## User Input-User input:+```text+$ARGUMENTS+```-`$ARGUMENTS`+You **MUST** consider the user input before proceeding (if not empty).++## OutlineThe text the user typed after `/specify` in the triggering message **is** the feature description. Assume you always have it available in this conversation even if `{ARGS}` appears literally below. Do not ask the user to repeat it unless they provided an empty command.diff --git a/templates/commands/tasks.md b/templates/commands/tasks.mdindex ad05d3c9a..d6beea739 100644--- a/templates/commands/tasks.md+++ b/templates/commands/tasks.md@@ -5,13 +5,15 @@ scripts:ps: scripts/powershell/check-prerequisites.ps1 -Json----The user input to you can be provided directly by the agent or as a command argument - you **MUST** consider it before proceeding with the prompt (if not empty).+## User Input-User input:+```text+$ARGUMENTS+```-`$ARGUMENTS`+You **MUST** consider the user input before proceeding (if not empty).-## Execution Steps+## Outline1. **Setup**: Run `{SCRIPT}` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute.