From 3dee20d2c1599436c3803ba88e60c6c203c072ac Mon Sep 17 00:00:00 2001 From: Emi Date: Wed, 28 Jan 2026 18:08:09 +0100 Subject: [PATCH 1/6] feat: add retrospective command for spec drift analysis Add /speckit.retrospective command template that performs post-implementation analysis measuring spec drift - the deviation between specification and actual implementation. Features: - Calculates Spec Drift Score (% of requirements implemented as specified) - Classifies deviations: CRITICAL, SIGNIFICANT, MINOR, POSITIVE - Requirement coverage matrix (FR/NFR tracking) - Success criteria assessment against actual values - Architecture drift analysis (data model, tech stack, APIs) - Root cause analysis (when/why deviations occurred) - Structured lessons learned by category - Actionable recommendations for future features - Read-only analysis mode (non-destructive) --- templates/commands/retrospective.md | 404 ++++++++++++++++++++++++++++ 1 file changed, 404 insertions(+) create mode 100644 templates/commands/retrospective.md diff --git a/templates/commands/retrospective.md b/templates/commands/retrospective.md new file mode 100644 index 0000000000..d0b51dc3d7 --- /dev/null +++ b/templates/commands/retrospective.md @@ -0,0 +1,404 @@ +```markdown +--- +description: Perform a post-implementation retrospective analysis measuring spec drift, implementation deviations, and generating lessons learned for future features. +scripts: + sh: scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks + ps: scripts/powershell/check-prerequisites.ps1 -Json -RequireTasks -IncludeTasks +--- + +## User Input + +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). + +## Goal + +Analyze the **completed implementation** against the original specification (`spec.md`), plan (`plan.md`), and tasks (`tasks.md`) to measure **spec drift** - the deviation between what was specified and what was actually built. Generate actionable insights and lessons learned to improve future Spec-Driven Development cycles. + +## Operating Constraints + +**STRICTLY READ-ONLY**: Do **not** modify any files. Output a structured retrospective report. All findings are for team learning and process improvement, not for immediate remediation. + +**Post-Implementation Only**: This command should run AFTER implementation is complete (or at a significant milestone). If tasks.md shows many incomplete tasks, warn the user and offer to proceed with partial analysis or abort. + +## Execution Steps + +### 1. Initialize Retrospective 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 + +For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot"). + +If any required file is missing, abort with instructions to ensure the feature was developed using the full Spec-Driven Development workflow. + +### 2. Validate Implementation Completeness + +**Before proceeding, verify implementation readiness:** + +1. Parse tasks.md and calculate completion percentage: + - Count total tasks: Lines matching `- [ ]` or `- [X]` or `- [x]` + - Count completed tasks: Lines matching `- [X]` or `- [x]` + - Calculate: `completion_rate = completed / total * 100` + +2. **Completeness Gate:** + - **≥80% complete**: Proceed with full retrospective + - **50-79% complete**: Warn user, proceed with partial analysis, note incomplete areas + - **<50% complete**: Ask user to confirm proceeding (analysis may be premature) + +### 3. Load Artifacts (Progressive Disclosure) + +Load relevant sections from each artifact: + +**From spec.md:** + +- Feature Overview/Context +- Functional Requirements (FR-XXX) +- Non-Functional Requirements (NFR-XXX) +- User Stories with priorities +- Success Criteria (SC-XXX) +- Assumptions +- Edge Cases + +**From plan.md:** + +- Architecture/stack choices +- Data Model specifications +- Phase breakdown +- Technical constraints +- Dependencies + +**From tasks.md:** + +- All tasks with completion status +- Phase grouping +- Referenced file paths +- Any notes or blockers + +**From constitution (if exists):** + +- Load `/memory/constitution.md` for principle validation + +### 4. Discover Implementation Reality + +**Scan the actual codebase** to understand what was built: + +1. **File Discovery**: Identify all files created/modified as part of this feature: + - Extract file paths from completed tasks in tasks.md + - Cross-reference with git history if available: `git log --name-only --oneline HEAD~50..HEAD` + - List actual project structure in relevant directories + +2. **Implementation Inventory**: + - Entities/Models actually created (vs data-model.md) + - Endpoints/APIs actually implemented (vs contracts/) + - Services/Components actually built + - Tests actually written + - Configuration changes made + +3. **Technology Audit**: + - Libraries/dependencies actually installed + - Frameworks actually used + - Third-party integrations actually connected + +### 5. Spec Drift Analysis + +Compare specification artifacts against implementation reality across these dimensions: + +#### A. Requirement Coverage Analysis + +For each Functional Requirement (FR-XXX): + +| Status | Meaning | +|--------|---------| +| ✅ IMPLEMENTED | Requirement fully satisfied in code | +| ⚠️ PARTIAL | Requirement partially implemented, missing aspects | +| ❌ NOT IMPLEMENTED | Requirement not addressed in code | +| 🔄 MODIFIED | Implementation differs from specification | +| ➕ UNSPECIFIED | Implemented but not in original spec (scope creep or evolution) | + +Track: + +- Which requirements were implemented as specified +- Which requirements were modified during implementation +- Which requirements were dropped or deferred +- Which capabilities were added without specification + +#### B. Success Criteria Validation + +For each Success Criterion (SC-XXX): + +- Is the criterion measurable in the current implementation? +- What is the actual measured value (if available)? +- Does it meet the specified target? + +#### C. Architecture Drift + +Compare plan.md architecture against actual implementation: + +- Data model changes (entities added/removed/modified) +- API contract changes (endpoints, request/response shapes) +- Technology stack changes (libraries, frameworks) +- Structural changes (file organization, module boundaries) + +#### D. Task Execution Fidelity + +Analyze how closely implementation followed the task plan: + +- Tasks completed as specified +- Tasks modified during execution +- Tasks added during implementation +- Tasks that proved unnecessary +- Parallel execution opportunities used/missed + +#### E. Timeline & Scope Analysis (if data available) + +- Phases that took longer than expected +- Scope changes during implementation +- Blockers encountered +- Dependencies that caused delays + +### 6. Drift Severity Classification + +Classify each deviation by impact: + +| Severity | Criteria | Action | +|----------|----------|--------| +| **CRITICAL** | Changes core functionality, breaks user stories, violates constitution | Must document for stakeholders | +| **SIGNIFICANT** | Notable deviation from spec, may affect user experience or performance | Document and analyze cause | +| **MINOR** | Small implementation variations, cosmetic differences | Note for completeness | +| **POSITIVE** | Improvements over specification (better UX, performance, security) | Capture as best practice | + +### 7. Root Cause Analysis + +For each significant deviation, analyze: + +1. **Discovery Point**: When was the deviation identified? + - During planning (spec was unclear) + - During implementation (technical constraint) + - During testing (requirement was wrong) + - During review (stakeholder feedback) + +2. **Cause Category**: + - **Spec Gap**: Original specification was incomplete or ambiguous + - **Tech Constraint**: Technical limitation prevented specified approach + - **Scope Evolution**: Requirements changed during development + - **Misunderstanding**: Requirement was misinterpreted + - **Improvement**: Deviation represents a better solution + - **Process Skip**: Spec/plan step was bypassed + +3. **Prevention Strategy**: How could this be avoided in future features? + +### 8. Generate Retrospective Report + +Output a comprehensive Markdown report with the following structure: + +--- + +## 📊 Feature Retrospective Report + +**Feature**: [Feature Name from spec.md] +**Branch**: [Branch name] +**Analysis Date**: [Current date] +**Implementation Completion**: [X]% + +--- + +### Executive Summary + +[2-3 sentence summary of overall spec adherence and key findings] + +**Spec Drift Score**: [Calculate as percentage: implemented_as_specified / total_requirements * 100] + +| Metric | Value | +|--------|-------| +| Total Requirements | X | +| Implemented as Specified | X | +| Modified During Implementation | X | +| Not Implemented | X | +| Unspecified Additions | X | +| Spec Drift Score | X% | + +--- + +### Requirement Coverage Matrix + +| Req ID | Description | Status | Deviation Notes | +|--------|-------------|--------|-----------------| +| FR-001 | [Brief desc] | ✅/⚠️/❌/🔄 | [If applicable] | +| ... | ... | ... | ... | + +--- + +### Success Criteria Assessment + +| Criterion | Target | Actual | Met? | Notes | +|-----------|--------|--------|------|-------| +| SC-001 | [Target value] | [Measured/Estimated] | ✅/❌/⚠️ | [Notes] | +| ... | ... | ... | ... | ... | + +--- + +### Architecture Drift Summary + +#### Data Model Changes + +| Entity | Specified | Actual | Change Type | +|--------|-----------|--------|-------------| +| [Entity] | [Spec version] | [Impl version] | Added/Modified/Removed | + +#### Technology Stack Changes + +| Component | Planned | Actual | Reason | +|-----------|---------|--------|--------| +| [Database/Framework/Library] | [Planned] | [Used] | [Why changed] | + +--- + +### Significant Deviations + +#### Deviation 1: [Title] + +- **Severity**: [CRITICAL/SIGNIFICANT/MINOR/POSITIVE] +- **Requirement(s) Affected**: [FR-XXX, SC-XXX] +- **What was specified**: [Original spec] +- **What was implemented**: [Actual implementation] +- **Discovery Point**: [When identified] +- **Root Cause**: [Cause category] +- **Impact**: [Effect on feature/user] +- **Lesson Learned**: [Preventive insight] + +[Repeat for each significant deviation] + +--- + +### Unspecified Implementations + +| Addition | Description | Justification | Should Have Been Specified? | +|----------|-------------|---------------|---------------------------| +| [What was added] | [Brief desc] | [Why added] | Yes/No - [Reason] | + +--- + +### Task Execution Analysis + +| Phase | Planned Tasks | Completed | Added | Dropped | Notes | +|-------|---------------|-----------|-------|---------|-------| +| Setup | X | X | X | X | [Notes] | +| [Phase N] | X | X | X | X | [Notes] | +| ... | ... | ... | ... | ... | ... | + +--- + +### Lessons Learned + +#### Specification Improvements + +- [ ] [Lesson 1: What to improve in future specs] +- [ ] [Lesson 2: ...] + +#### Planning Improvements + +- [ ] [Lesson 1: What to improve in future plans] +- [ ] [Lesson 2: ...] + +#### Process Improvements + +- [ ] [Lesson 1: What to improve in the SDD workflow] +- [ ] [Lesson 2: ...] + +#### Technical Insights + +- [ ] [Lesson 1: Technical knowledge gained] +- [ ] [Lesson 2: ...] + +--- + +### Recommendations + +#### For This Feature + +1. [Recommendation for addressing any gaps] +2. [Recommendation for documentation updates] + +#### For Future Features + +1. [Process improvement recommendation] +2. [Template/checklist improvement recommendation] + +#### Constitution Updates (if applicable) + +- [ ] [Principle to add/modify based on learnings] + +--- + +### Appendix: File-Level Traceability + +| File | Created/Modified | Related Requirements | Notes | +|------|------------------|---------------------|-------| +| [path/to/file.ext] | Created | FR-001, FR-002 | [Notes] | +| ... | ... | ... | ... | + +--- + +### 9. Save Retrospective (Optional) + +Ask user: "Would you like me to save this retrospective report to `FEATURE_DIR/retrospective.md`?" + +If yes, write the report file. + +### 10. Offer Follow-up Actions + +Based on findings, suggest next steps: + +- If significant gaps exist: "Consider running `/speckit.specify` to update the spec with actual implementation" +- If constitution violations found: "Review constitution principles that may need updating" +- If process issues identified: "Consider updating team's SDD workflow documentation" +- If positive deviations found: "Document these improvements as best practices" + +## Analysis Guidelines + +### What to Count as Spec Drift + +**Count as drift:** + +- Features implemented differently than specified +- Requirements dropped without documentation +- Unplanned features added (scope creep) +- Technical approach changed from plan +- Data model evolved from specification +- API contracts modified + +**Do NOT count as drift:** + +- Implementation details not specified in functional requirements +- Technology-specific optimizations within spec boundaries +- Bug fixes discovered during development +- Refactoring that maintains functionality +- Test coverage improvements + +### Objectivity Principles + +- Report facts, not judgments about team performance +- Focus on process improvement, not blame +- Treat positive deviations as valuable learning +- Acknowledge that some drift is normal and expected +- Prioritize actionable insights over exhaustive documentation + +### Token Efficiency + +- Limit deviation details to top 10 most significant +- Aggregate minor deviations in summary counts +- Use tables for structured data +- Keep recommendations actionable and specific +- Cap total report at ~2000 lines + +## Context + +{ARGS} +``` From b2f802b09cfdd42ea50576efb099577291b5cd7b Mon Sep 17 00:00:00 2001 From: Emi Date: Wed, 28 Jan 2026 20:06:13 +0100 Subject: [PATCH 2/6] fix: update retrospective command to include non-functional requirements and rename spec drift score to spec adherence score --- templates/commands/retrospective.md | 19 +++++++------------ 1 file changed, 7 insertions(+), 12 deletions(-) diff --git a/templates/commands/retrospective.md b/templates/commands/retrospective.md index d0b51dc3d7..1215be1629 100644 --- a/templates/commands/retrospective.md +++ b/templates/commands/retrospective.md @@ -1,4 +1,3 @@ -```markdown --- description: Perform a post-implementation retrospective analysis measuring spec drift, implementation deviations, and generating lessons learned for future features. scripts: @@ -112,7 +111,7 @@ Compare specification artifacts against implementation reality across these dime #### A. Requirement Coverage Analysis -For each Functional Requirement (FR-XXX): +For each Functional Requirement (FR-XXX) and Non-Functional Requirement (NFR-XXX): | Status | Meaning | |--------|---------| @@ -124,7 +123,7 @@ For each Functional Requirement (FR-XXX): Track: -- Which requirements were implemented as specified +- Which requirements (FR and NFR) were implemented as specified - Which requirements were modified during implementation - Which requirements were dropped or deferred - Which capabilities were added without specification @@ -213,7 +212,7 @@ Output a comprehensive Markdown report with the following structure: [2-3 sentence summary of overall spec adherence and key findings] -**Spec Drift Score**: [Calculate as percentage: implemented_as_specified / total_requirements * 100] +**Spec Adherence Score**: [Calculate as percentage: implemented_as_specified / total_requirements * 100] | Metric | Value | |--------|-------| @@ -222,7 +221,7 @@ Output a comprehensive Markdown report with the following structure: | Modified During Implementation | X | | Not Implemented | X | | Unspecified Additions | X | -| Spec Drift Score | X% | +| Spec Adherence Score | X% | --- @@ -231,6 +230,7 @@ Output a comprehensive Markdown report with the following structure: | Req ID | Description | Status | Deviation Notes | |--------|-------------|--------|-----------------| | FR-001 | [Brief desc] | ✅/⚠️/❌/🔄 | [If applicable] | +| NFR-001 | [Brief desc] | ✅/⚠️/❌/🔄 | [If applicable] | | ... | ... | ... | ... | --- @@ -346,13 +346,13 @@ Output a comprehensive Markdown report with the following structure: --- -### 9. Save Retrospective (Optional) +## 9. Save Retrospective (Optional) Ask user: "Would you like me to save this retrospective report to `FEATURE_DIR/retrospective.md`?" If yes, write the report file. -### 10. Offer Follow-up Actions +## 10. Offer Follow-up Actions Based on findings, suggest next steps: @@ -397,8 +397,3 @@ Based on findings, suggest next steps: - Use tables for structured data - Keep recommendations actionable and specific - Cap total report at ~2000 lines - -## Context - -{ARGS} -``` From 932ee3acedc8d3ee8f96531af3718b776aa62376 Mon Sep 17 00:00:00 2001 From: Emi Date: Mon, 2 Feb 2026 14:47:03 +0100 Subject: [PATCH 3/6] feat: enhance retrospective command with new handoffs for constitution updates and feature creation --- templates/commands/retrospective.md | 445 +++++++++------------------- 1 file changed, 133 insertions(+), 312 deletions(-) diff --git a/templates/commands/retrospective.md b/templates/commands/retrospective.md index 1215be1629..4e7ed656a3 100644 --- a/templates/commands/retrospective.md +++ b/templates/commands/retrospective.md @@ -1,5 +1,14 @@ --- description: Perform a post-implementation retrospective analysis measuring spec drift, implementation deviations, and generating lessons learned for future features. +handoffs: + - label: Update Constitution + agent: speckit.constitution + prompt: Update constitution based on retrospective learnings + send: true + - label: Create New Feature + agent: speckit.specify + prompt: Create a new feature incorporating learnings from retrospective + send: true scripts: sh: scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks ps: scripts/powershell/check-prerequisites.ps1 -Json -RequireTasks -IncludeTasks @@ -11,389 +20,201 @@ scripts: $ARGUMENTS ``` -You **MUST** consider the user input before proceeding (if not empty). +Consider user input before proceeding (if not empty). ## Goal -Analyze the **completed implementation** against the original specification (`spec.md`), plan (`plan.md`), and tasks (`tasks.md`) to measure **spec drift** - the deviation between what was specified and what was actually built. Generate actionable insights and lessons learned to improve future Spec-Driven Development cycles. +Analyze completed implementation against spec.md, plan.md, and tasks.md to measure **spec drift**. Generate actionable insights for future SDD cycles. -## Operating Constraints +## Constraints -**STRICTLY READ-ONLY**: Do **not** modify any files. Output a structured retrospective report. All findings are for team learning and process improvement, not for immediate remediation. - -**Post-Implementation Only**: This command should run AFTER implementation is complete (or at a significant milestone). If tasks.md shows many incomplete tasks, warn the user and offer to proceed with partial analysis or abort. +- **READ-ONLY**: Output report only, no file modifications +- **Post-Implementation**: Run after implementation complete; warn if <80% tasks done, abort if <50% ## Execution Steps -### 1. Initialize Retrospective Context - -Run `{SCRIPT}` once from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS. Derive absolute paths: +### 1. Initialize Context -- SPEC = FEATURE_DIR/spec.md -- PLAN = FEATURE_DIR/plan.md -- TASKS = FEATURE_DIR/tasks.md +Run `{SCRIPT}` from repo root. Parse JSON for FEATURE_DIR. Derive paths: SPEC, PLAN, TASKS = FEATURE_DIR/{spec,plan,tasks}.md. Abort if missing. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot"). -If any required file is missing, abort with instructions to ensure the feature was developed using the full Spec-Driven Development workflow. - -### 2. Validate Implementation Completeness - -**Before proceeding, verify implementation readiness:** - -1. Parse tasks.md and calculate completion percentage: - - Count total tasks: Lines matching `- [ ]` or `- [X]` or `- [x]` - - Count completed tasks: Lines matching `- [X]` or `- [x]` - - Calculate: `completion_rate = completed / total * 100` - -2. **Completeness Gate:** - - **≥80% complete**: Proceed with full retrospective - - **50-79% complete**: Warn user, proceed with partial analysis, note incomplete areas - - **<50% complete**: Ask user to confirm proceeding (analysis may be premature) - -### 3. Load Artifacts (Progressive Disclosure) - -Load relevant sections from each artifact: - -**From spec.md:** - -- Feature Overview/Context -- Functional Requirements (FR-XXX) -- Non-Functional Requirements (NFR-XXX) -- User Stories with priorities -- Success Criteria (SC-XXX) -- Assumptions -- Edge Cases - -**From plan.md:** - -- Architecture/stack choices -- Data Model specifications -- Phase breakdown -- Technical constraints -- Dependencies - -**From tasks.md:** - -- All tasks with completion status -- Phase grouping -- Referenced file paths -- Any notes or blockers - -**From constitution (if exists):** - -- Load `/memory/constitution.md` for principle validation - -### 4. Discover Implementation Reality - -**Scan the actual codebase** to understand what was built: - -1. **File Discovery**: Identify all files created/modified as part of this feature: - - Extract file paths from completed tasks in tasks.md - - Cross-reference with git history if available: `git log --name-only --oneline HEAD~50..HEAD` - - List actual project structure in relevant directories - -2. **Implementation Inventory**: - - Entities/Models actually created (vs data-model.md) - - Endpoints/APIs actually implemented (vs contracts/) - - Services/Components actually built - - Tests actually written - - Configuration changes made - -3. **Technology Audit**: - - Libraries/dependencies actually installed - - Frameworks actually used - - Third-party integrations actually connected - -### 5. Spec Drift Analysis +### 2. Validate Completeness -Compare specification artifacts against implementation reality across these dimensions: - -#### A. Requirement Coverage Analysis - -For each Functional Requirement (FR-XXX) and Non-Functional Requirement (NFR-XXX): - -| Status | Meaning | -|--------|---------| -| ✅ IMPLEMENTED | Requirement fully satisfied in code | -| ⚠️ PARTIAL | Requirement partially implemented, missing aspects | -| ❌ NOT IMPLEMENTED | Requirement not addressed in code | -| 🔄 MODIFIED | Implementation differs from specification | -| ➕ UNSPECIFIED | Implemented but not in original spec (scope creep or evolution) | - -Track: - -- Which requirements (FR and NFR) were implemented as specified -- Which requirements were modified during implementation -- Which requirements were dropped or deferred -- Which capabilities were added without specification - -#### B. Success Criteria Validation +```bash +total_tasks=$(grep -c '^\- \[[ Xx]\]' "$TASKS") +completed_tasks=$(grep -c '^\- \[[Xx]\]' "$TASKS") +completion_rate=$((completed_tasks * 100 / total_tasks)) +``` -For each Success Criterion (SC-XXX): +- **≥80%**: Full retrospective | **50-79%**: Warn, partial analysis | **<50%**: Confirm before proceeding -- Is the criterion measurable in the current implementation? -- What is the actual measured value (if available)? -- Does it meet the specified target? +### 3. Load Artifacts -#### C. Architecture Drift +- **spec.md**: FR-XXX, NFR-XXX, SC-XXX, User Stories, Assumptions, Edge Cases +- **plan.md**: Architecture, data model, phases, constraints, dependencies +- **tasks.md**: All tasks with status, file paths, blockers +- **constitution**: `/memory/constitution.md` (if exists) -Compare plan.md architecture against actual implementation: +### 4. Load Pre-Implementation Analysis -- Data model changes (entities added/removed/modified) -- API contract changes (endpoints, request/response shapes) -- Technology stack changes (libraries, frameworks) -- Structural changes (file organization, module boundaries) +Check FEATURE_DIR for analysis-report.md. Track: predicted vs actual issues. -#### D. Task Execution Fidelity +### 5. Discover Implementation -Analyze how closely implementation followed the task plan: +- Extract file paths from completed tasks + `git log --name-only HEAD~50..HEAD` +- Inventory: Models, APIs, Services, Tests, Config changes +- Audit: Libraries, frameworks, integrations actually used -- Tasks completed as specified -- Tasks modified during execution -- Tasks added during implementation -- Tasks that proved unnecessary -- Parallel execution opportunities used/missed +### 6. Spec Drift Analysis -#### E. Timeline & Scope Analysis (if data available) +#### A. Requirement Coverage -- Phases that took longer than expected -- Scope changes during implementation -- Blockers encountered -- Dependencies that caused delays +| Status | Meaning | Example | +|--------|---------|--------| +| ✅ IMPLEMENTED | Fully satisfied | FR-001: User login works as specified | +| ⚠️ PARTIAL | Partially done | FR-002: Search works but no filters | +| ❌ NOT IMPLEMENTED | Not addressed | NFR-003: No rate limiting added | +| 🔄 MODIFIED | Differs from spec | FR-004: REST instead of GraphQL | +| ➕ UNSPECIFIED | Added without spec | Admin dashboard not in requirements | -### 6. Drift Severity Classification +#### B. Success Criteria - Validate each SC-XXX against measured values +#### C. Architecture Drift - Data model, API, stack, structure changes vs plan.md +#### D. Task Fidelity - Tasks completed/modified/added/dropped +#### E. Timeline (if available) - Phase delays, scope changes, blockers -Classify each deviation by impact: +### 7. Severity Classification -| Severity | Criteria | Action | +| Severity | Criteria | Example | |----------|----------|--------| -| **CRITICAL** | Changes core functionality, breaks user stories, violates constitution | Must document for stakeholders | -| **SIGNIFICANT** | Notable deviation from spec, may affect user experience or performance | Document and analyze cause | -| **MINOR** | Small implementation variations, cosmetic differences | Note for completeness | -| **POSITIVE** | Improvements over specification (better UX, performance, security) | Capture as best practice | +| **CRITICAL** | Core functionality, constitution violations | Missing payment validation | +| **SIGNIFICANT** | Notable deviation affecting UX/performance | Changed auth method | +| **MINOR** | Small variations, cosmetic | Button color differs | +| **POSITIVE** | Improvements over spec | Added response caching | -### 7. Root Cause Analysis +### 8. Innovation Opportunities -For each significant deviation, analyze: +For positive deviations: What improved, why better, reusability, constitution candidate? -1. **Discovery Point**: When was the deviation identified? - - During planning (spec was unclear) - - During implementation (technical constraint) - - During testing (requirement was wrong) - - During review (stakeholder feedback) +### 9. Root Cause Analysis -2. **Cause Category**: - - **Spec Gap**: Original specification was incomplete or ambiguous - - **Tech Constraint**: Technical limitation prevented specified approach - - **Scope Evolution**: Requirements changed during development - - **Misunderstanding**: Requirement was misinterpreted - - **Improvement**: Deviation represents a better solution - - **Process Skip**: Spec/plan step was bypassed +- **Discovery Point**: Planning/Implementation/Testing/Review +- **Cause**: Spec Gap, Tech Constraint, Scope Evolution, Misunderstanding, Improvement, Process Skip +- **Prevention**: How to avoid in future -3. **Prevention Strategy**: How could this be avoided in future features? +### 10. Constitution Compliance -### 8. Generate Retrospective Report +Check each article against implementation. All violations = CRITICAL. -Output a comprehensive Markdown report with the following structure: +| Article | Title | Status | Notes | +|---------|-------|--------|-------| ---- +### 11. Analysis Effectiveness (if applicable) -## 📊 Feature Retrospective Report +Compare predicted vs actual issues. Calculate accuracy: `(correctly_predicted / total_actual) * 100` -**Feature**: [Feature Name from spec.md] -**Branch**: [Branch name] -**Analysis Date**: [Current date] -**Implementation Completion**: [X]% +### 12. Generate Report ---- +```markdown +## 📊 Feature Retrospective Report +**Feature**: [Name] | **Branch**: [branch] | **Date**: [date] | **Completion**: [X]% ### Executive Summary - -[2-3 sentence summary of overall spec adherence and key findings] - -**Spec Adherence Score**: [Calculate as percentage: implemented_as_specified / total_requirements * 100] +[2-3 sentences] | **Spec Adherence**: [X]% | Metric | Value | |--------|-------| -| Total Requirements | X | -| Implemented as Specified | X | -| Modified During Implementation | X | -| Not Implemented | X | -| Unspecified Additions | X | -| Spec Adherence Score | X% | - ---- +| Total/Implemented/Modified/Not Implemented/Unspecified | X | ### Requirement Coverage Matrix - -| Req ID | Description | Status | Deviation Notes | -|--------|-------------|--------|-----------------| -| FR-001 | [Brief desc] | ✅/⚠️/❌/🔄 | [If applicable] | -| NFR-001 | [Brief desc] | ✅/⚠️/❌/🔄 | [If applicable] | -| ... | ... | ... | ... | - ---- +| Req ID | Description | Status | Notes | ### Success Criteria Assessment +| Criterion | Target | Actual | Met? | -| Criterion | Target | Actual | Met? | Notes | -|-----------|--------|--------|------|-------| -| SC-001 | [Target value] | [Measured/Estimated] | ✅/❌/⚠️ | [Notes] | -| ... | ... | ... | ... | ... | - ---- - -### Architecture Drift Summary - -#### Data Model Changes - -| Entity | Specified | Actual | Change Type | -|--------|-----------|--------|-------------| -| [Entity] | [Spec version] | [Impl version] | Added/Modified/Removed | - -#### Technology Stack Changes - -| Component | Planned | Actual | Reason | -|-----------|---------|--------|--------| -| [Database/Framework/Library] | [Planned] | [Used] | [Why changed] | - ---- +### Architecture Drift +| Entity/Component | Specified | Actual | Change Type/Reason | ### Significant Deviations +For each: Severity, Requirements Affected, Specified vs Implemented, Discovery, Root Cause, Impact, Lesson -#### Deviation 1: [Title] +**Example:** +> #### Auth Method Changed +> - **Severity**: SIGNIFICANT | **Affected**: FR-003, SC-002 +> - **Specified**: Email/password with bcrypt | **Implemented**: OAuth2 SSO +> - **Discovery**: Phase 1 | **Cause**: Tech Constraint (email service unavailable) +> - **Impact**: Better UX, added third-party dependency +> - **Lesson**: Specify auth dependencies in planning phase -- **Severity**: [CRITICAL/SIGNIFICANT/MINOR/POSITIVE] -- **Requirement(s) Affected**: [FR-XXX, SC-XXX] -- **What was specified**: [Original spec] -- **What was implemented**: [Actual implementation] -- **Discovery Point**: [When identified] -- **Root Cause**: [Cause category] -- **Impact**: [Effect on feature/user] -- **Lesson Learned**: [Preventive insight] +### Innovations & Best Practices +| Innovation | Description | Benefit | Reusability | Constitution Candidate? | -[Repeat for each significant deviation] +**Example:** +| Response caching | Redis cache for frequent queries | 85% less DB load, 60% faster | All read-heavy endpoints | Yes - "Cache-First" principle | ---- +### Constitution Compliance +| Article | Title | Status | Notes | +**Violations**: [None / List with justifications] -### Unspecified Implementations +### Analysis Effectiveness (if applicable) +| Category | Predicted & Found | Predicted & Not Found | Found & Not Predicted | +### Unspecified Implementations | Addition | Description | Justification | Should Have Been Specified? | -|----------|-------------|---------------|---------------------------| -| [What was added] | [Brief desc] | [Why added] | Yes/No - [Reason] | - ---- ### Task Execution Analysis - -| Phase | Planned Tasks | Completed | Added | Dropped | Notes | -|-------|---------------|-----------|-------|---------|-------| -| Setup | X | X | X | X | [Notes] | -| [Phase N] | X | X | X | X | [Notes] | -| ... | ... | ... | ... | ... | ... | - ---- +| Phase | Planned | Completed | Added | Dropped | ### Lessons Learned - -#### Specification Improvements - -- [ ] [Lesson 1: What to improve in future specs] -- [ ] [Lesson 2: ...] - -#### Planning Improvements - -- [ ] [Lesson 1: What to improve in future plans] -- [ ] [Lesson 2: ...] - -#### Process Improvements - -- [ ] [Lesson 1: What to improve in the SDD workflow] -- [ ] [Lesson 2: ...] - -#### Technical Insights - -- [ ] [Lesson 1: Technical knowledge gained] -- [ ] [Lesson 2: ...] - ---- +- Specification/Planning/Process/Technical improvements ### Recommendations +- For this feature / For future features / Constitution updates -#### For This Feature - -1. [Recommendation for addressing any gaps] -2. [Recommendation for documentation updates] - -#### For Future Features - -1. [Process improvement recommendation] -2. [Template/checklist improvement recommendation] - -#### Constitution Updates (if applicable) - -- [ ] [Principle to add/modify based on learnings] - ---- - -### Appendix: File-Level Traceability - -| File | Created/Modified | Related Requirements | Notes | -|------|------------------|---------------------|-------| -| [path/to/file.ext] | Created | FR-001, FR-002 | [Notes] | -| ... | ... | ... | ... | - ---- - -## 9. Save Retrospective (Optional) - -Ask user: "Would you like me to save this retrospective report to `FEATURE_DIR/retrospective.md`?" - -If yes, write the report file. - -## 10. Offer Follow-up Actions - -Based on findings, suggest next steps: - -- If significant gaps exist: "Consider running `/speckit.specify` to update the spec with actual implementation" -- If constitution violations found: "Review constitution principles that may need updating" -- If process issues identified: "Consider updating team's SDD workflow documentation" -- If positive deviations found: "Document these improvements as best practices" +### Appendix: File Traceability +| File | Created/Modified | Requirements | +``` -## Analysis Guidelines +### 13. Save Report -### What to Count as Spec Drift +1. Write to `FEATURE_DIR/retrospective.md` with YAML frontmatter (feature, branch, date, rates, counts) +2. Commit: `Add retrospective analysis - Spec adherence: X% | Completion: X%` +3. Confirm: `✅ Retrospective saved | 📊 Adherence: X% | ⚠️ Critical: X` -**Count as drift:** +### 14. Follow-up Actions -- Features implemented differently than specified -- Requirements dropped without documentation -- Unplanned features added (scope creep) -- Technical approach changed from plan -- Data model evolved from specification -- API contracts modified +**By Priority:** +1. **CRITICAL**: Constitution violations, breaking changes, security issues +2. **HIGH**: Significant drift, process improvements, template updates +3. **MEDIUM**: Best practices, constitution candidates +4. **LOW**: Minor optimizations -**Do NOT count as drift:** +**Commands:** +- `/speckit.constitution` for violations +- `/speckit.specify` for spec updates +- `/speckit.checklist` for new checklists -- Implementation details not specified in functional requirements -- Technology-specific optimizations within spec boundaries -- Bug fixes discovered during development -- Refactoring that maintains functionality -- Test coverage improvements +**Example output:** +``` +🚨 CRITICAL: 2 actions required + 1. /speckit.constitution Review Article II violation in auth module + 2. Update spec.md to document OAuth2 implementation +⚠️ HIGH: 2 improvements + 1. /speckit.checklist Create security checklist with OAuth2 validation + 2. Document caching pattern in /memory/patterns/ +✅ MEDIUM: 1 best practice + 1. /speckit.constitution Consider "Cache-First" principle +``` -### Objectivity Principles +## Guidelines -- Report facts, not judgments about team performance -- Focus on process improvement, not blame -- Treat positive deviations as valuable learning -- Acknowledge that some drift is normal and expected -- Prioritize actionable insights over exhaustive documentation +### Count as Drift +Features differing from spec, dropped requirements, scope creep, tech approach changes -### Token Efficiency +### NOT Drift +Implementation details, optimizations within boundaries, bug fixes, refactoring, test improvements -- Limit deviation details to top 10 most significant -- Aggregate minor deviations in summary counts -- Use tables for structured data -- Keep recommendations actionable and specific -- Cap total report at ~2000 lines +### Principles +- Facts over judgments, process over blame, positive deviations = learning +- Progressive disclosure, max 50 detailed deviations, compact tables +- Executive summary <500 words, report <2000 lines From bb4a21f0347b8b0ac0331dbecc93f499b71a8c33 Mon Sep 17 00:00:00 2001 From: Emi Date: Tue, 3 Feb 2026 08:08:51 +0100 Subject: [PATCH 4/6] fix: Fix bugs related to file creation and numeration --- templates/commands/retrospective.md | 35 ++++++++++++----------------- 1 file changed, 14 insertions(+), 21 deletions(-) diff --git a/templates/commands/retrospective.md b/templates/commands/retrospective.md index 4e7ed656a3..4ebb537f0a 100644 --- a/templates/commands/retrospective.md +++ b/templates/commands/retrospective.md @@ -9,6 +9,10 @@ handoffs: agent: speckit.specify prompt: Create a new feature incorporating learnings from retrospective send: true + - label: Create Checklist + agent: speckit.checklist + prompt: Create checklist based on retrospective findings + send: true scripts: sh: scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks ps: scripts/powershell/check-prerequisites.ps1 -Json -RequireTasks -IncludeTasks @@ -28,7 +32,7 @@ Analyze completed implementation against spec.md, plan.md, and tasks.md to measu ## Constraints -- **READ-ONLY**: Output report only, no file modifications +- **Output**: Generates and saves `retrospective.md` report to FEATURE_DIR - **Post-Implementation**: Run after implementation complete; warn if <80% tasks done, abort if <50% ## Execution Steps @@ -56,17 +60,13 @@ completion_rate=$((completed_tasks * 100 / total_tasks)) - **tasks.md**: All tasks with status, file paths, blockers - **constitution**: `/memory/constitution.md` (if exists) -### 4. Load Pre-Implementation Analysis - -Check FEATURE_DIR for analysis-report.md. Track: predicted vs actual issues. - -### 5. Discover Implementation +### 4. Discover Implementation - Extract file paths from completed tasks + `git log --name-only HEAD~50..HEAD` - Inventory: Models, APIs, Services, Tests, Config changes - Audit: Libraries, frameworks, integrations actually used -### 6. Spec Drift Analysis +### 5. Spec Drift Analysis #### A. Requirement Coverage @@ -83,7 +83,7 @@ Check FEATURE_DIR for analysis-report.md. Track: predicted vs actual issues. #### D. Task Fidelity - Tasks completed/modified/added/dropped #### E. Timeline (if available) - Phase delays, scope changes, blockers -### 7. Severity Classification +### 6. Severity Classification | Severity | Criteria | Example | |----------|----------|--------| @@ -92,28 +92,24 @@ Check FEATURE_DIR for analysis-report.md. Track: predicted vs actual issues. | **MINOR** | Small variations, cosmetic | Button color differs | | **POSITIVE** | Improvements over spec | Added response caching | -### 8. Innovation Opportunities +### 7. Innovation Opportunities For positive deviations: What improved, why better, reusability, constitution candidate? -### 9. Root Cause Analysis +### 8. Root Cause Analysis - **Discovery Point**: Planning/Implementation/Testing/Review - **Cause**: Spec Gap, Tech Constraint, Scope Evolution, Misunderstanding, Improvement, Process Skip - **Prevention**: How to avoid in future -### 10. Constitution Compliance +### 9. Constitution Compliance Check each article against implementation. All violations = CRITICAL. | Article | Title | Status | Notes | |---------|-------|--------|-------| -### 11. Analysis Effectiveness (if applicable) - -Compare predicted vs actual issues. Calculate accuracy: `(correctly_predicted / total_actual) * 100` - -### 12. Generate Report +### 10. Generate Report ```markdown ## 📊 Feature Retrospective Report @@ -156,9 +152,6 @@ For each: Severity, Requirements Affected, Specified vs Implemented, Discovery, | Article | Title | Status | Notes | **Violations**: [None / List with justifications] -### Analysis Effectiveness (if applicable) -| Category | Predicted & Found | Predicted & Not Found | Found & Not Predicted | - ### Unspecified Implementations | Addition | Description | Justification | Should Have Been Specified? | @@ -175,13 +168,13 @@ For each: Severity, Requirements Affected, Specified vs Implemented, Discovery, | File | Created/Modified | Requirements | ``` -### 13. Save Report +### 11. Save Report 1. Write to `FEATURE_DIR/retrospective.md` with YAML frontmatter (feature, branch, date, rates, counts) 2. Commit: `Add retrospective analysis - Spec adherence: X% | Completion: X%` 3. Confirm: `✅ Retrospective saved | 📊 Adherence: X% | ⚠️ Critical: X` -### 14. Follow-up Actions +### 12. Follow-up Actions **By Priority:** 1. **CRITICAL**: Constitution violations, breaking changes, security issues From 722aedb6bb0cf4f6fc6e10ac089b370e1c3a2c3b Mon Sep 17 00:00:00 2001 From: Emi Date: Tue, 3 Feb 2026 08:43:24 +0100 Subject: [PATCH 5/6] fix: update retrospective command to clarify post-implementation warnings and enhance task validation --- templates/commands/retrospective.md | 27 +++++++++++++++++++++------ 1 file changed, 21 insertions(+), 6 deletions(-) diff --git a/templates/commands/retrospective.md b/templates/commands/retrospective.md index 4ebb537f0a..9fdff50a8f 100644 --- a/templates/commands/retrospective.md +++ b/templates/commands/retrospective.md @@ -33,7 +33,7 @@ Analyze completed implementation against spec.md, plan.md, and tasks.md to measu ## Constraints - **Output**: Generates and saves `retrospective.md` report to FEATURE_DIR -- **Post-Implementation**: Run after implementation complete; warn if <80% tasks done, abort if <50% +- **Post-Implementation**: Run after implementation complete; warn if <80% tasks done, confirm before proceeding if <50% ## Execution Steps @@ -46,8 +46,11 @@ For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot ### 2. Validate Completeness ```bash -total_tasks=$(grep -c '^\- \[[ Xx]\]' "$TASKS") -completed_tasks=$(grep -c '^\- \[[Xx]\]' "$TASKS") +total_tasks=$(grep -c '^- \[[ Xx]\]' "$TASKS" || echo 0) +completed_tasks=$(grep -c '^- \[[Xx]\]' "$TASKS" || echo 0) +if [ "$total_tasks" -eq 0 ]; then + echo "No tasks found in $TASKS" && exit 1 +fi completion_rate=$((completed_tasks * 100 / total_tasks)) ``` @@ -62,7 +65,7 @@ completion_rate=$((completed_tasks * 100 / total_tasks)) ### 4. Discover Implementation -- Extract file paths from completed tasks + `git log --name-only HEAD~50..HEAD` +- Extract file paths from completed tasks + `git log --name-only --since="1 month ago" 2>/dev/null || git log --name-only` - Inventory: Models, APIs, Services, Tests, Config changes - Audit: Libraries, frameworks, integrations actually used @@ -120,16 +123,23 @@ Check each article against implementation. All violations = CRITICAL. | Metric | Value | |--------|-------| -| Total/Implemented/Modified/Not Implemented/Unspecified | X | +| Total Requirements | X | +| Implemented | X | +| Modified | X | +| Not Implemented | X | +| Unspecified | X | ### Requirement Coverage Matrix | Req ID | Description | Status | Notes | +|--------|-------------|--------|-------| ### Success Criteria Assessment | Criterion | Target | Actual | Met? | +|-----------|--------|--------|------| ### Architecture Drift | Entity/Component | Specified | Actual | Change Type/Reason | +|------------------|-----------|--------|--------------------| ### Significant Deviations For each: Severity, Requirements Affected, Specified vs Implemented, Discovery, Root Cause, Impact, Lesson @@ -144,19 +154,23 @@ For each: Severity, Requirements Affected, Specified vs Implemented, Discovery, ### Innovations & Best Practices | Innovation | Description | Benefit | Reusability | Constitution Candidate? | +|------------|-------------|---------|-------------|-------------------------| **Example:** | Response caching | Redis cache for frequent queries | 85% less DB load, 60% faster | All read-heavy endpoints | Yes - "Cache-First" principle | ### Constitution Compliance | Article | Title | Status | Notes | +|---------|-------|--------|-------| **Violations**: [None / List with justifications] ### Unspecified Implementations | Addition | Description | Justification | Should Have Been Specified? | +|----------|-------------|---------------|-----------------------------| ### Task Execution Analysis | Phase | Planned | Completed | Added | Dropped | +|-------|---------|-----------|-------|---------| ### Lessons Learned - Specification/Planning/Process/Technical improvements @@ -166,12 +180,13 @@ For each: Severity, Requirements Affected, Specified vs Implemented, Discovery, ### Appendix: File Traceability | File | Created/Modified | Requirements | +|------|------------------|--------------| ``` ### 11. Save Report 1. Write to `FEATURE_DIR/retrospective.md` with YAML frontmatter (feature, branch, date, rates, counts) -2. Commit: `Add retrospective analysis - Spec adherence: X% | Completion: X%` +2. Commit: `feat(retrospective): add spec drift report (adherence X%, completion X%)` 3. Confirm: `✅ Retrospective saved | 📊 Adherence: X% | ⚠️ Critical: X` ### 12. Follow-up Actions From e41edab4f2dd13edc3d74ac812a38d24fb53ac8b Mon Sep 17 00:00:00 2001 From: Emi Date: Tue, 3 Feb 2026 11:31:27 +0100 Subject: [PATCH 6/6] feat: enhance retrospective command with additional context validation and spec adherence calculation --- templates/commands/retrospective.md | 30 +++++++++++++++++++++++++---- 1 file changed, 26 insertions(+), 4 deletions(-) diff --git a/templates/commands/retrospective.md b/templates/commands/retrospective.md index 9fdff50a8f..a9a3fbfa0a 100644 --- a/templates/commands/retrospective.md +++ b/templates/commands/retrospective.md @@ -39,7 +39,7 @@ Analyze completed implementation against spec.md, plan.md, and tasks.md to measu ### 1. Initialize Context -Run `{SCRIPT}` from repo root. Parse JSON for FEATURE_DIR. Derive paths: SPEC, PLAN, TASKS = FEATURE_DIR/{spec,plan,tasks}.md. Abort if missing. +Run `{SCRIPT}` from repo root. Parse JSON for FEATURE_DIR and AVAILABLE_DOCS. Derive paths: SPEC, PLAN, TASKS = FEATURE_DIR/{spec,plan,tasks}.md. Abort if missing. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot"). @@ -54,7 +54,10 @@ fi completion_rate=$((completed_tasks * 100 / total_tasks)) ``` -- **≥80%**: Full retrospective | **50-79%**: Warn, partial analysis | **<50%**: Confirm before proceeding +**Completion Thresholds:** +- **≥80%**: Proceed with full retrospective +- **50-79%**: Display warning about incomplete implementation, then proceed with partial analysis noting the incompleteness +- **<50%**: STOP and display: `⚠️ Only ${completion_rate}% tasks complete. Retrospective requires ≥50% completion. Continue anyway? (y/N)`. Exit if user declines. ### 3. Load Artifacts @@ -65,7 +68,7 @@ completion_rate=$((completed_tasks * 100 / total_tasks)) ### 4. Discover Implementation -- Extract file paths from completed tasks + `git log --name-only --since="1 month ago" 2>/dev/null || git log --name-only` +- Extract file paths from completed tasks + `git log --name-only --since="1 month ago" --max-count=100 2>/dev/null || git log --name-only --max-count=100` - Inventory: Models, APIs, Services, Tests, Config changes - Audit: Libraries, frameworks, integrations actually used @@ -86,6 +89,12 @@ completion_rate=$((completed_tasks * 100 / total_tasks)) #### D. Task Fidelity - Tasks completed/modified/added/dropped #### E. Timeline (if available) - Phase delays, scope changes, blockers +**Calculate Spec Adherence:** +``` +Spec Adherence % = ((IMPLEMENTED + MODIFIED + (PARTIAL * 0.5)) / (Total Requirements - UNSPECIFIED)) * 100 +``` +Where Total Requirements = Count of all FR-XXX, NFR-XXX, SC-XXX from spec.md + ### 6. Severity Classification | Severity | Criteria | Example | @@ -115,6 +124,19 @@ Check each article against implementation. All violations = CRITICAL. ### 10. Generate Report ```markdown +--- +feature: [Feature Name] +branch: [branch-name] +date: [YYYY-MM-DD] +completion_rate: [X] +spec_adherence: [X] +total_requirements: [X] +implemented: [X] +modified: [X] +not_implemented: [X] +unspecified: [X] +--- + ## 📊 Feature Retrospective Report **Feature**: [Name] | **Branch**: [branch] | **Date**: [date] | **Completion**: [X]% @@ -224,5 +246,5 @@ Implementation details, optimizations within boundaries, bug fixes, refactoring, ### Principles - Facts over judgments, process over blame, positive deviations = learning -- Progressive disclosure, max 50 detailed deviations, compact tables +- Progressive disclosure, max 50 detailed deviations (summarize overflow), compact tables - Executive summary <500 words, report <2000 lines