Conduct a structured retrospective analysis of the completed development cycle — from specification through shipping. Analyze what went well, what didn't, and generate actionable improvement suggestions for future iterations. Track metrics over time to identify trends and continuously improve the spec-driven development process.
-
Run .specify/scripts/powershell/check-prerequisites.ps1 -Json -RequireTasks -IncludeTasks from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. 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").
-
Gather Retrospective Data:
Load all available artifacts from the development cycle:
- REQUIRED: Read
spec.md — original specification and requirements
- REQUIRED: Read
tasks.md — task breakdown and completion status
- REQUIRED: Read
plan.md — technical plan and architecture decisions
- IF EXISTS: Read review reports in FEATURE_DIR/reviews/ — code review findings
- IF EXISTS: Read QA reports in FEATURE_DIR/qa/ — testing results
- IF EXISTS: Read release artifacts in FEATURE_DIR/releases/ — shipping data
- IF EXISTS: Read critique reports in FEATURE_DIR/critiques/ — pre-implementation review
- IF EXISTS: Read previous retros in FEATURE_DIR/retros/ — historical context
- IF EXISTS: Read
.specify/memory/constitution.md — project principles
-
Collect Git Metrics:
Gather quantitative data from the git history:
: "${BASE_REF:?Set BASE_REF to the base branch/ref for this feature (e.g., main, develop, or an upstream ref)}"
git rev-list --count "$BASE_REF"..HEAD
git diff --stat "$BASE_REF"..HEAD
git diff --shortstat "$BASE_REF"..HEAD
git log "$BASE_REF"..HEAD --format='%an' | sort -u | wc -l
git log "$BASE_REF"..HEAD --format='%ai' | tail -1
git log "$BASE_REF"..HEAD --format='%ai' | head -1
If git data is not available (e.g., already merged), use artifact timestamps and content analysis as fallback.
-
Specification Accuracy Analysis:
Compare the original spec against what was actually built:
- Requirements fulfilled: Count of spec requirements that were fully implemented
- Requirements partially fulfilled: Requirements that were implemented with deviations
- Requirements not implemented: Spec items that were deferred or dropped
- Unplanned additions: Features implemented that were NOT in the original spec (scope creep)
- Surprises: Requirements that turned out to be much harder or easier than expected
- Accuracy score: (fulfilled + partial×0.5) / total requirements × 100%
-
Plan Effectiveness Analysis:
Evaluate how well the technical plan guided implementation:
- Architecture decisions validated: Did the chosen patterns/stack work as planned?
- Architecture decisions revised: Were any plan decisions changed during implementation?
- Task scoping accuracy: Were tasks well-sized? Any tasks that were much larger/smaller than expected?
- Missing tasks: Were any tasks added during implementation that weren't in the original breakdown?
- Task ordering issues: Were there dependency problems or tasks that should have been reordered?
- Plan score: Qualitative assessment (EXCELLENT / GOOD / ADEQUATE / NEEDS IMPROVEMENT)
-
Implementation Quality Analysis:
Analyze the quality of the implementation based on review and QA data:
- Review findings summary: Total findings by severity from review reports
- Blocker resolution: Were all blockers resolved before shipping?
- QA results summary: Pass/fail rates from QA testing
- Test coverage: Test suite results and coverage metrics
- Code quality indicators: Lines of code, test-to-code ratio, cyclomatic complexity (if available)
- Quality score: Based on review verdict and QA pass rate
-
Process Metrics Dashboard:
Compile a metrics summary:
📊 Development Cycle Metrics
══════════════════════════
Feature: {feature_name}
Duration: {first_commit} → {last_commit}
📝 Specification
Requirements: {total} total, {fulfilled} fulfilled, {partial} partial
Spec Accuracy: {accuracy}%
📋 Planning
Tasks: {total_tasks} total, {completed} completed
Added during impl: {unplanned_tasks}
Plan Score: {plan_score}
💻 Implementation
Commits: {commit_count}
Files changed: {files_changed}
Lines: +{additions} / -{deletions}
Test/Code ratio: {test_ratio}
🔍 Quality
Review findings: 🔴{blockers} 🟡{warnings} 🟢{suggestions}
QA pass rate: {qa_pass_rate}%
Quality Score: {quality_score}
-
What Went Well (Keep Doing):
Identify and celebrate successes:
- Aspects of the spec that were clear and led to smooth implementation
- Architecture decisions that proved effective
- Tasks that were well-scoped and completed without issues
- Quality practices that caught real issues
- Any particularly efficient or elegant solutions
-
What Could Improve (Start/Stop Doing):
Identify areas for improvement:
- Spec gaps that caused confusion or rework during implementation
- Plan decisions that needed revision
- Tasks that were poorly scoped or had missing dependencies
- Quality issues that slipped through review/QA
- Process friction points (tool issues, unclear workflows)
-
Actionable Improvement Suggestions:
Generate specific, actionable suggestions:
- Rank by impact (HIGH / MEDIUM / LOW)
- Each suggestion should be concrete and implementable
- Group by category: Specification, Planning, Implementation, Quality, Process
Example format:
IMP-001 [HIGH] Add data model validation to spec template
→ The spec lacked entity relationship details, causing 3 unplanned tasks during implementation.
→ Suggestion: Add a "Data Model" section to the spec template with entity, attribute, and relationship requirements.
IMP-002 [MEDIUM] Include browser compatibility in QA checklist
→ QA missed a CSS rendering issue in Safari that was caught post-merge.
→ Suggestion: Add cross-browser testing scenarios to the QA test plan.
-
Historical Trend Analysis (if previous retros exist):
If FEATURE_DIR/retros/ contains previous retrospective reports:
- Compare key metrics across cycles (spec accuracy, QA pass rate, review findings)
- Identify improving trends (celebrate!) and declining trends (flag for attention)
- Check if previous improvement suggestions were adopted and whether they helped
- Output a trend summary table
-
Generate Retrospective Report:
- Load the retrospective report template from
.specify/templates/retro-template.md. If the template file does not exist or cannot be read, continue using a reasonable fallback structure based on the sections above.
- Ensure the
FEATURE_DIR/retros/ directory exists. If it does not exist, create it before writing any files.
- Generate the retro report at
FEATURE_DIR/retros/retro-{timestamp}.md, using the loaded retrospective report template and filling it with the metrics, findings, and improvement suggestions from the previous steps.
-
Offer Constitution Update:
Based on the retrospective findings, offer to update .specify/memory/constitution.md with new learnings:
- "Based on this retrospective, I suggest adding the following principles to your constitution:"
- List specific principle additions or modifications
- Wait for explicit user approval before making any changes
- If approved, append new principles with a "Learned from: {feature_name} retro" annotation
-
Suggest Next Actions:
- If this was a successful cycle: "Great work! Consider starting your next feature with
/speckit.specify"
- If improvements were identified: List the top 3 most impactful improvements to adopt
- If trends are declining: Recommend a process review or team discussion