| name | repo-retrospective |
| description | Quality assurance for AI onboarding documentation. Analyzes ONBOARD documents against X-Ray outputs and actual code to identify gaps, verify claims, and suggest improvements. |
repo-retrospective
Quality assurance skill for AI onboarding documentation. Ensures ONBOARD documents effectively enable fresh Claude instances to work in codebases.
The Problem
ONBOARD documents are curated from X-Ray scans + investigation.
Curation involves judgment:
- What to include (critical for warm start)
- What to omit (noise, duplicates, low-value)
- What to verify (claims need evidence)
- What to flag (gotchas, hazards)
Judgment can be wrong:
- Critical information omitted
- Claims not properly verified
- Gotchas missed
- Gaps not acknowledged
Cost of errors: Hours of developer time wasted.
The Solution
Retrospective analysis with five phases:
| Phase | Purpose | Output |
|---|
| Inventory | Catalog ONBOARD claims | Checklist to verify |
| Coverage | Compare ONBOARD vs X-Ray | Gap analysis |
| Verification | Spot-check [VERIFIED] claims | Accuracy report |
| Actionability | Test usability with questions | Score (X/8) |
| Recommendations | Synthesize findings | Specific fixes |
Quick Start
@repo_retrospective full \
--onboard path/to/ONBOARD.md \
--xray path/to/xray.md \
--codebase /path/to/code
@repo_retrospective quick --onboard path/to/ONBOARD.md --codebase /path/to/code
@repo_retrospective coverage --onboard path/to/ONBOARD.md --xray path/to/xray.md
@repo_retrospective actionability --onboard path/to/ONBOARD.md
When to Use
| Scenario | Mode | Purpose |
|---|
| Project completion | full | Final QA before commit |
| Mid-project checkpoint | quick | Verify claims are accurate |
| After X-Ray refresh | coverage | Ensure new signals captured |
| User suspects issues | actionability | Test document usability |
Operating Modes
full — Complete Retrospective
All five phases. Most thorough analysis.
Inputs:
- ONBOARD document path
- X-Ray output path
- Codebase path
Output: Full retrospective report with recommendations
Token budget: ~30-40K
quick — Verification Audit
Spot-check [VERIFIED] claims only.
Inputs:
- ONBOARD document path
- Codebase path
Output: Verification audit report
Token budget: ~15-20K
coverage — Gap Analysis
Compare ONBOARD against X-Ray output.
Inputs:
- ONBOARD document path
- X-Ray output path
Output: Coverage matrix with gaps identified
Token budget: ~15-20K
actionability — Usability Test
Test if document enables effective coding.
Inputs:
- ONBOARD document path only
Output: Actionability score (X/8) with breakdown
Token budget: ~10-15K
Coverage Categories
When comparing ONBOARD vs X-Ray:
| Category | Examples | Expected in ONBOARD? |
|---|
| Must Have | Architecture diagram, Hazards, Top pillars | Yes |
| Should Have | Key data models, Critical side effects, Required env vars | Yes (curated) |
| Nice to Have | Decorator counts, Orphan files, Freshness stats | No (can omit) |
Verification Outcomes
When auditing [VERIFIED] claims:
| Outcome | Meaning | Action Required |
|---|
| Confirmed | Claim matches code exactly | None |
| Partially True | Correct but missing context | Recommend enhancement |
| Outdated | Code changed since verification | Re-investigate |
| Inaccurate | Claim doesn't match code | Critical fix needed |
| Unverifiable | Can't find cited location | Clarify reference |
Actionability Questions
Standard questions to test document usability:
- "What is this codebase?" (Orientation)
- "Where does core logic live?" (Architecture)
- "How do I add a new [entity]?" (Entry points)
- "What happens when [X] fails?" (Error handling)
- "What files should I never read?" (Hazards)
- "What are common pitfalls?" (Gotchas)
- "What env vars do I need?" (Configuration)
- "How do I run tests?" (Development)
Scoring:
- 8/8 → Excellent
- 6-7/8 → Good
- 4-5/8 → Needs improvement
- <4/8 → Significant rework
Quality Thresholds
Ship It
- No critical gaps
- ≥80% [VERIFIED] claims confirmed
- Actionability ≥6/8
- All hazards included
Needs Minor Fixes
- 1-2 moderate gaps
- 1-2 verification issues
- Actionability 5-7/8
Needs Significant Rework
- Critical gaps found
-
20% claims unverifiable
- Actionability <5/8
Confidence Levels
Findings are marked:
| Level | Meaning |
|---|
[CONFIRMED] | Verified by reading actual code |
[ASSESSED] | Based on document analysis only |
[UNCERTAIN] | Needs human judgment |
Output: Retrospective Report
# Retrospective Report: [Project Name]
## Executive Summary
[1-2 sentences overall assessment]
## Coverage Analysis
### Critical Gaps (Must Fix)
### Moderate Gaps (Should Fix)
### Justified Omissions
## Verification Audit
### Confirmed Claims
### Issues Found
## Actionability Score
[X/8 with breakdown]
## Specific Recommendations
[Numbered, actionable items]
## Conclusion
[Ship It / Needs Minor Fixes / Needs Significant Rework]
Integration with repo-xray
This skill is designed to QA documents produced by the repo_xray agent:
Workflow:
┌─────────────────────────────────────────────────────────────────────────┐
│ │
│ 1. xray.py scans codebase → xray.md + xray.json │
│ │
│ 2. repo_xray agent investigates → ONBOARD.md │
│ │
│ 3. repo_retrospective reviews → RETROSPECTIVE_REPORT.md │
│ ↓ │
│ Identifies gaps, verifies claims, scores actionability │
│ ↓ │
│ Produces specific recommendations │
│ │
│ 4. Developer/Agent fixes issues (if any) │
│ │
│ 5. Final ONBOARD.md ready for use │
│ │
└─────────────────────────────────────────────────────────────────────────┘
Files
repo-retrospective/
├── SKILL.md # This file
├── COMMANDS.md # Quick reference
└── templates/
└── RETROSPECTIVE.md.template # Report template
Requirements
- Read access to ONBOARD document
- Read access to X-Ray output (for coverage mode)
- Read access to codebase (for verification mode)
- No external dependencies
This skill ensures AI onboarding documentation maintains quality
and effectively solves the cold start problem.
