Repo Retrospective

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:

Quick Start

# Full retrospective
@repo_retrospective full \
  --onboard path/to/ONBOARD.md \
  --xray path/to/xray.md \
  --codebase /path/to/code

# Quick verification audit only
@repo_retrospective quick --onboard path/to/ONBOARD.md --codebase /path/to/code

# Coverage analysis only
@repo_retrospective coverage --onboard path/to/ONBOARD.md --xray path/to/xray.md

# Actionability test only
@repo_retrospective actionability --onboard path/to/ONBOARD.md

When to Use

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:

Verification Outcomes

When auditing [VERIFIED] claims:

Actionability Questions

Standard questions to test document usability:

1. "What is this codebase?" (Orientation)
2. "Where does core logic live?" (Architecture)
3. "How do I add a new [entity]?" (Entry points)
4. "What happens when [X] fails?" (Error handling)
5. "What files should I never read?" (Hazards)
6. "What are common pitfalls?" (Gotchas)
7. "What env vars do I need?" (Configuration)
8. "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:

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.