feat: add /speckit.retro command — sprint retrospective & metrics

[arunt14]

Description

Problem

Spec-Kit has no feedback loop. Once a feature is shipped, there is no structured way to reflect on: Was the spec accurate? Was the plan effective? Were there quality issues that slipped through? What should the team do differently next time? Without retrospectives, teams repeat the same mistakes across development cycles and miss opportunities to improve their spec-driven workflow.

The community retrospective extension exists but is not part of core, and it lacks metrics tracking and trend analysis across multiple cycles.

Industry context: GStack's /retro command demonstrates that embedding retrospective analysis directly in the workflow — with data-driven metrics rather than subjective impressions — creates a continuous improvement engine. Teams using structured retros consistently improve their spec accuracy and reduce rework over time.

Solution

Adds /speckit.retro — a new core command that closes the development feedback loop with structured, data-driven retrospective analysis:

• Specification accuracy scoring — requirements fulfilled vs. partial vs. deferred vs. unplanned additions
• Plan effectiveness analysis — architecture decisions validated/revised, task scoping accuracy, missing tasks
• Implementation quality metrics — review findings summary, QA pass rates, test coverage
• Git-based development metrics — commits, files changed, lines added/removed, duration, contributors
• What went well / what could improve — balanced, constructive assessment with specific examples
• Actionable improvement suggestions — ranked by impact (HIGH/MEDIUM/LOW) with rationale
• Historical trend analysis — compares metrics across multiple cycles to track improvement over time
• Constitution updates — optionally adds learned principles to project constitution (with user approval)

Output: Structured retrospective report with metrics dashboard, improvement suggestions, and trend analysis.

Business Value

• Creates a continuous improvement engine — each cycle's learnings feed into the next, compounding quality improvements
• Makes spec-driven development measurably better over time — spec accuracy scores and plan effectiveness trends reveal whether the process is working
• Reduces rework — by identifying and addressing recurring issues (e.g., "specs consistently miss data model details")
• Provides quantitative project health data — metrics like test/code ratio, QA pass rate, and review blocker count give teams objective quality signals
• Closes the full lifecycle loop: constitution → specify → plan → critique → tasks → implement → review → qa → ship → retro → (next cycle)

Workflow Position

/speckit.ship → /speckit.retro ⭐ → (feeds learnings into next /speckit.constitution or /speckit.specify)

Files Added

File	Purpose
templates/commands/retro.md	Command template with metrics collection, analysis passes, trend tracking, constitution update offer, extension hooks (before_retro, after_retro)
templates/retro-template.md	Retrospective report template with metrics dashboard, findings, improvement suggestions, and trend table

Testing

• Tested locally with uv run specify --help
• Ran existing tests with uv sync && uv run pytest — 878/972 pass (44 failures are pre-existing, unrelated to this change)
• Verified YAML frontmatter is valid and parseable
• Verified command file is auto-discovered by specify init
• Confirmed no changes to Python source code — template-only addition

AI Disclosure

• AI assistance was used in this PR
• How: GitHub Copilot CLI (Claude) was used to draft the command template and output template content, following the existing patterns established by implement.md and analyze.md. All content was reviewed and validated against the project's template conventions.

---

Note: Happy to discuss the scope and approach with maintainers. This is one of five related-but-independent PRs adding lifecycle commands inspired by GStack's role-based workflow.

[Copilot]

Pull request overview

Adds a new core /speckit.retro workflow command and a corresponding retrospective report template, intended to close the loop after shipping by summarizing cycle metrics, learnings, and improvement actions.

Changes:

• Added templates/commands/retro.md to define the retrospective command workflow (including extension hooks).
• Added templates/retro-template.md as the markdown output structure for generated retrospectives.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

File	Description
templates/commands/retro.md	New command template describing how to gather artifacts, compute metrics, and generate the retro report (with before/after hook support).
templates/retro-template.md	New report template defining the retrospective markdown layout and metric sections.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

In the artifact list, plan.md is marked as “IF EXISTS”, but this command’s prerequisite script (check-prerequisites with --require-tasks) fails if plan.md is missing. To avoid the agent treating it as optional, mark plan.md as REQUIRED here (or relax the prerequisite script args if it truly should be optional).

Suggested change

	- **IF EXISTS**: Read `plan.md` — technical plan and architecture decisions
	- **REQUIRED**: Read `plan.md` — technical plan and architecture decisions

[Copilot]

The git metric commands rely on an undefined {target_branch} placeholder and assume a remote named origin exists. Since template preprocessing doesn’t substitute {target_branch}, agents may execute these literally or guess incorrectly. Recommend either (1) add explicit instructions to determine the base ref (e.g., default branch / upstream) and use that value consistently, or (2) avoid the placeholder by using a computed merge-base/upstream ref in the commands.

Suggested change

	# Commit count for the feature
	git rev-list --count origin/{target_branch}..HEAD
	# Files changed
	git diff --stat origin/{target_branch}..HEAD
	# Lines added/removed
	git diff --shortstat origin/{target_branch}..HEAD
	# Number of authors
	git log origin/{target_branch}..HEAD --format='%an' | sort -u | wc -l
	# Date range (first commit to last)
	git log origin/{target_branch}..HEAD --format='%ai' | tail -1
	git log origin/{target_branch}..HEAD --format='%ai' | head -1
	# Determine the base ref for this feature once per repo.
	# Preferred: use the upstream branch (e.g., origin/main, origin/develop):
	# BASE_REF="$(git rev-parse --abbrev-ref --symbolic-full-name @{upstream})"
	#
	# Or set it explicitly if there is no upstream configured:
	# BASE_REF=main
	# BASE_REF=develop
	#
	: "${BASE_REF:?Set BASE_REF to the base branch/ref for this feature (e.g., main, develop, or an upstream ref)}"
	# Commit count for the feature
	git rev-list --count "$BASE_REF"..HEAD
	# Files changed
	git diff --stat "$BASE_REF"..HEAD
	# Lines added/removed
	git diff --shortstat "$BASE_REF"..HEAD
	# Number of authors
	git log "$BASE_REF"..HEAD --format='%an' | sort -u | wc -l
	# Date range (first commit to last)
	git log "$BASE_REF"..HEAD --format='%ai' | tail -1
	git log "$BASE_REF"..HEAD --format='%ai' | head -1

[Copilot]

Step 12 says to generate the report “using the retrospective report template”, but the workflow never instructs the agent to read the template file (e.g., .specify/templates/retro-template.md) nor to create FEATURE_DIR/retros/ if it doesn’t exist. Add an explicit step to load the template and ensure the destination directory exists before writing retro-{timestamp}.md.

Suggested change

	Create the retro report at `FEATURE_DIR/retros/retro-{timestamp}.md` using the retrospective report template.
	- 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.

[Copilot]

Several placeholders in the dashboard are ambiguous/reused for different metrics (e.g., Requirements: [total]... and Tasks: [total]..., plus multiple [count] fields). This makes it easy to fill the template incorrectly or to auto-populate with the wrong values. Consider using distinct placeholder names (e.g., [req_total], [tasks_total], [commit_count], [files_changed]) and keep the same placeholder name for spec accuracy throughout (dashboard [accuracy]% vs later [X]%).

[arunt14]

Thanks for the thorough review! All 4 comments addressed in the latest push:

1. plan.md marked REQUIRED: Changed from IF EXISTS to REQUIRED to match the prerequisite script behavior.
2. Git metric commands: Replaced undefined {target_branch} placeholder with a BASE_REF computation that determines the base ref from upstream or allows explicit configuration. No more hard-coded origin assumptions.
3. Step 12 template reference: Now explicitly loads from templates/retro-template.md, ensures FEATURE_DIR/retros/ directory exists, and includes fallback behavior if template is missing.
4. Template placeholders: Replaced ambiguous reused names ([total], [count]) with distinct prefixed names ([req_total], [tasks_total], [commit_count], [files_changed], etc.) to prevent mismatched auto-population.

[mnriem]

Please review https://github.com/github/spec-kit/blob/main/extensions/EXTENSION-PUBLISHING-GUIDE.md for publishing a community hosted extension

[arunt14]

Thanks @mnriem! I've reviewed the Extension Publishing Guide. Will restructure this as a community extension following the extension.yml manifest pattern and resubmit as an extension contribution to catalog.community.json.

[arunt14]

Closing in favor of PR #2049 — restructured as a community extension per maintainer feedback. Extension repo and v1.0.0 release are available.