RetroPRD reads your git history and agent session transcripts, then generates PRDs, ADRs, and sets up a builder OS, all in one pass.
npx skills add yagneshlp/retroprd
Works with Claude Code · Codex CLI · Cursor · Gemini CLI
Why it exists
That's not a flaw. It's how good builders work. RetroPRD fills the gap retroactively, from evidence that already exists in your repo.
You sit down tomorrow and spend 30 minutes reconstructing what you were thinking today. Multiply that by every session, every project. It compounds into real time lost.
Claude Code, Cursor, and Codex read your code, not your intent. Without structured context files, every new session hands your agent a blank slate. The more you build, the more gets left behind.
Tradeoffs, rejected approaches, architecture decisions: they live in your head during the build. Handoffs start without them. The code survives. The reasoning doesn't.
RetroPRD treats your git history and session transcripts as primary sources. One command reads, classifies, and reconstructs: the PRDs, ADRs, and context files your project should have had from day one. No rewriting history. Just surfacing it.
AI continuity Each new agent session picks up exactly where the last one ended. No re-explaining, no re-reading.
Onboarding in hours New contributors read the PRD trail and understand the project's full arc — decisions, tradeoffs, and all.
Permanent decision trail Every architectural choice is documented with context, alternatives considered, and consequences. The "why" never gets lost.
What you get
Every artifact a well-documented codebase should have — generated from what already exists.
.prd/NNN-*.md
One per feature, bug fix, or infra change. Chronological, with reconstruction confidence markers.
.dev/decisions.md
Every technical decision with context, alternatives considered, and consequences. Reconstructed from code and commits.
.context/session.md
Current product state, open items, and suggested next priorities — ready for the next agent to pick up.
.context/backlog.md
Deferred items, known bugs, and ideas surfaced during the archaeological dig. Nothing gets lost.
AGENTS.md
Populates your builder OS scaffold with real product context: build phases, conventions, and key learnings.
.prd/README.md
A master changelog of everything shipped, typed and dated — built for both agent and human readability.
Builder OS
RetroPRD doesn't just generate docs. It wires up the infrastructure that makes every future agent session context-aware from the first message — automatically, permanently.
Without RetroPRD
Repeated every session, forever.
After one /retroprd run
AGENTS.md — full product context.context/session.md — current state.dev/decisions.md — decision trail.prd/ — complete feature historyEvery session, without any extra work.
Why it's permanent
Claude Code, Cursor, Codex, and Gemini CLI all read AGENTS.md and the context files in your repo at session start — it's a shared convention across all major coding agents. RetroPRD fills those files with real content from your actual build history. That's the entire mechanism. One run, and documentation capability is baked into every agent session going forward.
Harness switching
Context lives in your repo, not in any model's window. When one agent's context window fills, switch to another — it reads the same files and picks up exactly where the last one stopped. Burn through limits freely. Nothing is lost between handoffs.
.context/session.md · .prd/ · .dev/decisions.md · AGENTS.md
How it works
A structured process designed to surface evidence before writing anything.
Reads existing scaffold files — AGENTS.md, README, .prd/ — before touching anything. Understands your conventions first.
Three evidence layers: git log and diffs, agent session transcripts (Claude Code, Codex CLI), and direct code reading for intent.
Groups related commits into PRD-sized units. A feature spread across four commits becomes one PRD, not four.
Produces dated, typed PRDs with problem, change, and files sections. Each carries a confidence marker: High, Medium, or Low.
Fills in session.md, backlog.md, decisions.md, and AGENTS.md TODO sections with real context from the dig.
Summarises what was reconstructed, confidence levels, gaps, and what needs builder verification — then reminds you to commit.
Compatibility
Reads each agent's native transcript format. No manual export required.
| Agent | Transcript location | Notes |
|---|---|---|
| Claude Code | ~/.claude/projects/<hash>/sessions/*.jsonl |
Full support · --synthesize flag |
| Codex CLI | ~/.codex/sessions/**/*.jsonl |
Also reads ~/.codex/memories/ |
| Any agent | --transcript /path/to/file.jsonl |
Generic JSONL parser |
Installation
Then use it in your agent
/retroprd # Full run — git dig + PRDs + all scaffold files
/retroprd --prds-only # Just generate PRDs
/retroprd --scaffold-only # Just populate AGENTS.md and context filesOr just say: "Document what I've built so far"