Agentic Retrospective

Evidence-based sprint retrospectives for human-agent collaboration. No AI slop - every finding links to specific commits, PRs, or decisions.

What Makes This Different

Most retrospective tools produce vague observations like "58 tool invocations across 7 tools". That's useless.

This tool produces objective, evidence-based metrics:

Metric	Example Output
Commit Breakdown	"59.7% fixes (227/380), 10.8% features (41/380), 1.6% tests (6/380)"
Rework Rate	"15/20 PRs superseded (75% rework)"
Testing Discipline	"2% of decisions mention testing"
Decision Quality	"78% have both rationale AND context"
Agent Contribution	"45 commits (11.8%) by agents"

Before vs After

Before (AI Slop):

### Tool Usage
Observation: 58 total tool invocations across 7 different tools
Top Tools: Bash (39), Glob (6), Read (4)

After (Evidence-Based):

### Executive Summary

| Metric | Value |
|--------|-------|
| Total Commits | 380 |
| PRs Superseded (Rework) | 15 (75.0%) |
| Testing Loop Adherence | 2.0% |
| Decision Quality Score | 78.0% |
| Reactive Work Ratio | 87.6% |

### What Didn't Work
| Metric | Value | Issue |
|--------|-------|-------|
| Testing Discipline | 2% | Agent not testing before push |
| Supersession Rate | 75% | Poor initial PR quality |

Installation

Quick run (no install)

npx @daax-dev/retrospective

Global install

npm install -g @daax-dev/retrospective
# Then run:
agentic-retrospective

As Claude Code Plugin

claude mcp install github.com/daax-dev/agentic-retrospective

Usage

Basic

# Analyze last 2 weeks (default)
npx @daax-dev/retrospective

# Analyze from specific ref
npx @daax-dev/retrospective --from HEAD~50
npx @daax-dev/retrospective --from "2 weeks ago"

# Output JSON only
npx @daax-dev/retrospective --json

Session Feedback

npx @daax-dev/retrospective feedback

30-second survey to capture alignment, rework needed, and session quality.

Metrics Calculated

From Git History

• Commit Type Breakdown: feat/fix/docs/test/refactor/chore
• Checkpoint Commits: wip/save/tmp patterns
• Reactive vs Proactive Ratio: fixes vs features
• Agent Commit Detection: Co-authored-by patterns, bot emails
• Rework Chains: fix commits following features
• Code Hotspots: files changed 3+ times

From GitHub (requires gh CLI)

• PR Supersession Rate: PRs that replaced other PRs
• PRs with Test Files: PRs including test/spec files
• Review Metrics: approval times, revision cycles
• Negative Reviews: CHANGES_REQUESTED count

From Decision Logs

• Decision Quality Score: % with both rationale AND context
• Testing Discipline: % mentioning tests
• Decision Thrash: conflicting decisions on same topic
• Risk Profile: one-way-doors missing reversibility plans

From Security Scans

• Vulnerability Counts: critical/high/medium/low
• Scan Sources: Trivy, npm audit, Snyk

Data Sources

Required

• Git History - Automatically extracted

Optional (Enhanced Analysis)

Source	Location	Enables
Decision Logs	.logs/decisions/*.jsonl	Decision quality, testing discipline
Security Scans	.logs/security/*.json	Vulnerability analysis
Feedback	.logs/feedback/*.jsonl	Alignment tracking
Tool Logs	.logs/tools/*.jsonl	Tool usage patterns

Setup Directories

mkdir -p .logs/decisions .logs/security .logs/feedback .logs/tools

Report Output

Reports are generated at docs/retrospectives/retrospective-YYYY-MM-DD/:

File	Contents
retrospective.md	Human-readable report
retrospective.json	Structured data
evidence_map.json	Commit/decision index
alerts.json	Critical findings for automation

Report Sections

1. Executive Summary - 10+ key metrics in table format
2. Code Hotspots - Files with high churn
3. Commit Type Breakdown - Work classification
4. PR Analysis - Rework rate, test coverage
5. What Worked / What Didn't - Threshold-based (>70% good, <50% bad)
6. Testing Discipline - Loop adherence %
7. Mistakes & Corrections - Documented learnings
8. Recommendations - Current | Target | Action format

Graceful Degradation

Always produces useful output with available data:

Missing Source	Impact
Decision logs	Decision score = null, gap recorded
Security scans	Security score = null, gap recorded
GitHub access	No PR metrics, git-only analysis
Feedback logs	No alignment tracking

Principles

1. Evidence-Driven - Every claim links to commits, PRs, or decisions
2. Blameless - Evaluates systems and patterns, not people
3. Objective - Percentages and counts, not vague observations
4. Actionable - Recommendations include current state, target, and action

Development

# Install
pnpm install

# Build
pnpm run build

# Test (243 tests)
pnpm test

# Full validation
pnpm run validate

License

Apache 2.0