Skip to content

feat: add retrospective command for spec drift analysis #1533

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
emi-dm wants to merge 3 commits into
base: main
Choose a base branch
from
+220 −0
Open

feat: add retrospective command for spec drift analysis #1533

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
3dee20d
feat: add retrospective command for spec drift analysis
emi-dm Jan 28, 2026
b2f802b
fix: update retrospective command to include non-functional requireme…
emi-dm Jan 28, 2026
932ee3a
feat: enhance retrospective command with new handoffs for constitutio…
emi-dm Feb 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
220 changes: 220 additions & 0 deletions templates/commands/retrospective.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,220 @@
---
description: Perform a post-implementation retrospective analysis measuring spec drift, implementation deviations, and generating lessons learned for future features.
Copy link

Copilot AI Feb 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The new /speckit.retrospective command is not documented in README.md's "Available Slash Commands" section (around lines 247-270). Since this is a new command being added to the Spec-Driven Development workflow, it should be documented there. Based on its purpose (post-implementation analysis), it would fit best in the "Optional Commands" section alongside analyze and checklist, with a description like "Post-implementation retrospective analysis measuring spec drift and generating lessons learned".

Copilot uses AI. Check for mistakes.
Copy link

Copilot AI Feb 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The CHANGELOG.md should be updated to document the addition of the new /speckit.retrospective command. According to the AGENTS.md guidelines (line 15): "Any changes to init.py for the Specify CLI require a version rev in pyproject.toml and addition of entries to CHANGELOG.md." While this change doesn't modify init.py, it does add a significant new command to the toolkit that should be documented for users. The changelog should include a description of the new retrospective command and its purpose (spec drift analysis, lessons learned, etc.).

Copilot uses AI. Check for mistakes.
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
---

## User Input

```text
$ARGUMENTS
```

Consider user input before proceeding (if not empty).
Copy link

Copilot AI Feb 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The user input consideration statement should use the stronger "You MUST consider" wording to be consistent with all other commands in the codebase. Every other command file (analyze.md, checklist.md, clarify.md, constitution.md, implement.md, plan.md, specify.md, tasks.md, taskstoissues.md) uses "You MUST consider the user input before proceeding (if not empty)." instead of just "Consider user input before proceeding (if not empty)."

Copilot uses AI. Check for mistakes.

## Goal

Analyze completed implementation against spec.md, plan.md, and tasks.md to measure **spec drift**. Generate actionable insights for future SDD cycles.

## Constraints

- **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 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.

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").

### 2. Validate Completeness

```bash
total_tasks=$(grep -c '^\- \[[ Xx]\]' "$TASKS")
Copy link

Copilot AI Feb 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The bash regex pattern '^\- \[[ Xx]\]' will match tasks in any state (unchecked [ ], checked [X], or [x]), which is correct for counting total tasks. However, the pattern should be '^- \[[ Xx]\]' (without backslash before the hyphen) as the hyphen doesn't need to be escaped at the beginning of the pattern. This is more consistent with standard grep patterns and avoids potential confusion.

Suggested change
total_tasks=$(grep -c '^\- \[[ Xx]\]' "$TASKS")
total_tasks=$(grep -c '^- \[[ Xx]\]' "$TASKS")

Copilot uses AI. Check for mistakes.
completed_tasks=$(grep -c '^\- \[[Xx]\]' "$TASKS")
Comment on lines +45 to +46
Copy link

Copilot AI Feb 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Similarly, the pattern '^\- \[[Xx]\]' for completed tasks should be '^- \[[Xx]\]' without escaping the hyphen.

Suggested change
total_tasks=$(grep -c '^\- \[[ Xx]\]' "$TASKS")
completed_tasks=$(grep -c '^\- \[[Xx]\]' "$TASKS")
total_tasks=$(grep -c '^- \[[ Xx]\]' "$TASKS")
completed_tasks=$(grep -c '^- \[[Xx]\]' "$TASKS")

Copilot uses AI. Check for mistakes.
completion_rate=$((completed_tasks * 100 / total_tasks))
Copy link

Copilot AI Feb 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The division operation $((completed_tasks * 100 / total_tasks)) will fail with a "division by zero" error if there are no tasks in the file. While this is unlikely in normal usage (since tasks.md should have tasks), it's a potential edge case that should be handled. Consider adding a check or using a safer calculation approach.

Suggested change
completion_rate=$((completed_tasks * 100 / total_tasks))
if [ "$total_tasks" -eq 0 ]; then
completion_rate=0
else
completion_rate=$((completed_tasks * 100 / total_tasks))
fi

Copilot uses AI. Check for mistakes.
```

- **≥80%**: Full retrospective | **50-79%**: Warn, partial analysis | **<50%**: Confirm before proceeding
Comment on lines +32 to +50
Copy link

Copilot AI Feb 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The command states "abort if <50%" in line 32, but the detailed instruction in line 50 says "Confirm before proceeding" for <50% completion. These instructions are inconsistent. Based on the context and safer design (allowing users to proceed if they explicitly confirm), the "Confirm before proceeding" approach is more appropriate than an absolute abort, but the instructions should be consistent.

Copilot uses AI. Check for mistakes.

### 3. Load Artifacts

- **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)

### 4. Load Pre-Implementation Analysis

Check FEATURE_DIR for analysis-report.md. Track: predicted vs actual issues.

### 5. Discover Implementation

- Extract file paths from completed tasks + `git log --name-only HEAD~50..HEAD`
Copy link

Copilot AI Feb 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The git log command git log --name-only HEAD~50..HEAD assumes there are at least 50 commits in the repository history. In a new or small repository, this will fail with an error like "fatal: ambiguous argument 'HEAD~50': unknown revision or path not in the working tree." Consider using a safer approach like git log --name-only --since="1 month ago" or wrapping the command with error handling.

Suggested change
- 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"` (or another safe range that works even in small repositories)

Copilot uses AI. Check for mistakes.
- Inventory: Models, APIs, Services, Tests, Config changes
- Audit: Libraries, frameworks, integrations actually used

### 6. Spec Drift Analysis

#### A. Requirement Coverage

| 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 |

#### 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

### 7. Severity Classification

| Severity | Criteria | Example |
|----------|----------|--------|
| **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 |

### 8. Innovation Opportunities

For positive deviations: What improved, why better, reusability, constitution candidate?

### 9. 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

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

```markdown
## 📊 Feature Retrospective Report
**Feature**: [Name] | **Branch**: [branch] | **Date**: [date] | **Completion**: [X]%

### Executive Summary
[2-3 sentences] | **Spec Adherence**: [X]%

| Metric | Value |
|--------|-------|
| Total/Implemented/Modified/Not Implemented/Unspecified | X |
Comment on lines +125 to +127
Copy link

Copilot AI Feb 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The table format appears incorrect. Line 127 shows "Total/Implemented/Modified/Not Implemented/Unspecified | X" which suggests multiple metrics crammed into a single row. This should likely be a multi-row table where each metric (Total, Implemented, Modified, Not Implemented, Unspecified) has its own row with a corresponding value, or it should be a multi-column table with separate columns for each metric type. The current format is unclear and won't render properly as a meaningful table.

Suggested change
| Metric | Value |
|--------|-------|
| Total/Implemented/Modified/Not Implemented/Unspecified | X |
| Metric | Total | Implemented | Modified | Not Implemented | Unspecified |
|--------|-------|-------------|----------|------------------|-------------|
| Count | X | X | X | X | X |

Copilot uses AI. Check for mistakes.

### 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

**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

### 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]

### Analysis Effectiveness (if applicable)
| Category | Predicted & Found | Predicted & Not Found | Found & Not Predicted |

### Unspecified Implementations
| Addition | Description | Justification | Should Have Been Specified? |

### Task Execution Analysis
| Phase | Planned | Completed | Added | Dropped |

### Lessons Learned
- Specification/Planning/Process/Technical improvements

### Recommendations
- For this feature / For future features / Constitution updates

### Appendix: File Traceability
| File | Created/Modified | Requirements |
Comment on lines +130 to +175
Copy link

Copilot AI Feb 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Multiple tables in the report template are missing the required separator row between the header and content rows. According to Markdown table syntax, each table must have a separator row with dashes. The following tables are incomplete:

  • Line 130: "Requirement Coverage Matrix" (missing separator like |--------|-------------|--------|-------|)
  • Line 133: "Success Criteria Assessment" (missing separator)
  • Line 136: "Architecture Drift" (missing separator)
  • Line 150: "Innovations & Best Practices" (missing separator)
  • Line 156: "Constitution Compliance" (missing separator)
  • Line 160: "Analysis Effectiveness" (missing separator)
  • Line 163: "Unspecified Implementations" (missing separator)
  • Line 166: "Task Execution Analysis" (missing separator)
  • Line 175: "Appendix: File Traceability" (missing separator)

Without these separator rows, the tables won't render correctly in most Markdown parsers.

Copilot uses AI. Check for mistakes.
```

### 13. 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%`
Copy link

Copilot AI Feb 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The commit message format uses a dash separator "Spec adherence: X% | Completion: X%" but most of the codebase and conventional commit messages would use a colon after "Add retrospective analysis". Consider using "Add retrospective analysis: Spec adherence X%, Completion X%" or following conventional commit format like "feat(retrospective): add analysis report (adherence X%, completion X%)" for better git log readability and consistency.

Suggested change
2. Commit: `Add retrospective analysis - Spec adherence: X% | Completion: X%`
2. Commit: `Add retrospective analysis: Spec adherence X%, Completion X%`

Copilot uses AI. Check for mistakes.
3. Confirm: `✅ Retrospective saved | 📊 Adherence: X% | ⚠️ Critical: X`

### 14. Follow-up Actions

**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

**Commands:**
- `/speckit.constitution` for violations
- `/speckit.specify` for spec updates
- `/speckit.checklist` for new checklists

**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
```

## Guidelines

### Count as Drift
Features differing from spec, dropped requirements, scope creep, tech approach changes

### NOT Drift
Implementation details, optimizations within boundaries, bug fixes, refactoring, test improvements

### 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
Loading