diff --git a/templates/commands/retrospective.md b/templates/commands/retrospective.md new file mode 100644 index 0000000000..a9a3fbfa0a --- /dev/null +++ b/templates/commands/retrospective.md @@ -0,0 +1,250 @@ +--- +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 + - 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 +--- + +## User Input + +```text +$ARGUMENTS +``` + +Consider user input before proceeding (if not empty). + +## Goal + +Analyze completed implementation against spec.md, plan.md, and tasks.md to measure **spec drift**. Generate actionable insights for future SDD cycles. + +## Constraints + +- **Output**: Generates and saves `retrospective.md` report to FEATURE_DIR +- **Post-Implementation**: Run after implementation complete; warn if <80% tasks done, confirm before proceeding if <50% + +## Execution Steps + +### 1. Initialize Context + +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"). + +### 2. Validate Completeness + +```bash +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)) +``` + +**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 + +- **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. Discover Implementation + +- 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 + +### 5. 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 + +**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 | +|----------|----------|--------| +| **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. Innovation Opportunities + +For positive deviations: What improved, why better, reusability, constitution candidate? + +### 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 + +### 9. Constitution Compliance + +Check each article against implementation. All violations = CRITICAL. + +| Article | Title | Status | Notes | +|---------|-------|--------|-------| + +### 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]% + +### Executive Summary +[2-3 sentences] | **Spec Adherence**: [X]% + +| Metric | Value | +|--------|-------| +| 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 + +**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] + +### 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 | +|------|------------------|--------------| +``` + +### 11. Save Report + +1. Write to `FEATURE_DIR/retrospective.md` with YAML frontmatter (feature, branch, date, rates, counts) +2. Commit: `feat(retrospective): add spec drift report (adherence X%, completion X%)` +3. Confirm: `✅ Retrospective saved | 📊 Adherence: X% | ⚠️ Critical: X` + +### 12. 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 (summarize overflow), compact tables +- Executive summary <500 words, report <2000 lines