Codebase Briefing Report

codebase-briefing-report — a shareable snapshot of a codebase's current state

Turns exploration of an unfamiliar or evolving repository into one self-contained Markdown document: what the system is, how it is structured, what its numbers say, and where the risk sits. The output is meant to be read cold by a new team member or a non-author stakeholder — not a running log of your investigation.

⚠️ Critical Constraints

• Evidence, not impressions. Every architectural claim must trace to a file, directory, or command output. Why: a report read cold becomes the reader's mental model; an unsourced guess propagates as fact across the whole team.
• Snapshot, not history. Report the state at one commit (record the SHA in the header). Do not narrate how you found things. Why: a stakeholder wants the current map, not your search path — investigation logs belong in scratch notes, not the deliverable.
• Risks are named and rated, never buried. A health section that only says "looks good" is a failure. Each risk gets a one-line statement + Low/Med/High rating + a concrete next action. Why: the point of handing this to a stakeholder is to surface what they cannot see; a flattering summary defeats the purpose.
• No fabricated metrics. If you cannot compute a number, write "not measured" — do not estimate. Why: a made-up test-coverage or LOC figure is worse than an absent one because it reads as authoritative. WRONG: Coverage: ~70%. CORRECT: Coverage: not measured (no run).
• One commit, one artifact. Write a single file at the path in output_contract; do not scatter findings across many files. Why: the deliverable is shareable precisely because it is one link.

Why This Exists

Onboarding and stakeholder updates default to either a verbal tour (lost the moment it ends) or a sprawling wiki nobody maintains. Neither is a single artifact you can hand someone. This skill forces a fixed shape and an evidence discipline so the report is trustworthy, comparable across repos, and cheap to regenerate when the codebase moves.

Quick Start

# From the repo root you are reporting on:
git rev-parse --short HEAD                 # the SHA for the header
git log -1 --format='%cd' --date=short     # last-change date

Then walk the four phases below and emit docs/reports/CODEBASE-REPORT.md.

Workflow

Phase 1 — Orient (what is this?)

Establish the system's identity before touching internals.

• Read the entry docs: README*, CONTRIBUTING*, top-level *.md, package.json / go.mod / Cargo.toml / pyproject.toml description fields.
• Detect languages and the build/run system (look for Makefile, CI config, lockfiles).
• State in one paragraph: what the system does, who uses it, and how it runs.

Checkpoint: you can name the system's purpose in one sentence without quoting marketing copy. If not, keep reading entry docs before proceeding.

Phase 2 — Map (how is it structured?)

Build the module map — the spine of the report.

• Enumerate top-level directories and the role each plays (ls -d */, then sample each).
• Identify entry points (main, server bootstrap, CLI root, exported package surface).
• Trace the dependency direction between modules (who imports whom). Note any obvious layering (e.g. domain / adapters / transport) or its absence.
• Produce a table: one row per significant module — name, responsibility, key files, depends-on.

Checkpoint: every top-level source directory appears in the module table exactly once.

Phase 3 — Measure (what do the numbers say?)

Compute the metrics you can, mark the rest "not measured".

• Size: file count, LOC by language (scripts/collect-metrics.sh does this where tools exist).
• Activity: commit count, contributors, last-change date, hottest files (most-churned).
• Tests: count test files; run the suite if it is fast and safe; otherwise record "not run".
• Tooling signals: lint/typecheck config presence, CI pipeline steps, dependency counts.

Checkpoint: every number in the report came from a command, not a guess.

Phase 4 — Assess (where is the risk?)

Turn observation into a health/risk summary the reader can act on.

• For each risk: a one-line statement, a Low / Med / High rating, and a concrete next action.
• Cover at least: test coverage gaps, single-points-of-failure (one file/person owns a domain), dependency staleness/security, undocumented load-bearing areas, and any layering violations.
• End with a short "if you read nothing else" list: the 3–5 things a new owner must know.

Checkpoint: no risk is rated without a next action attached.

Output Specification

Write one file: docs/reports/CODEBASE-REPORT.md (override path per the calling repo's conventions; record the chosen path). Required sections, in order:

1. Header — repo name, commit SHA, date generated, author/agent.
2. What It Is — one-paragraph purpose + run model (from Phase 1).
3. Architecture Overview — prose + an ASCII or Mermaid diagram of module relationships.
4. Module Map — the table from Phase 2.
5. Metrics — the numbers from Phase 3 (mark gaps "not measured").
6. Health & Risk Summary — the rated risk list from Phase 4.
7. If You Read Nothing Else — the 3–5 must-knows.

Quality Rubric

• Sourced: every architectural claim cites a path or command; spot-check three at random.
• Complete map: the Module Map covers every top-level source directory, no orphans.
• Actionable risk: every risk row has a rating AND a next action — no bare observations.
• Self-contained: a reader who has never seen the repo understands it from the file alone.
• Honest metrics: no estimated numbers; gaps are explicitly marked "not measured".

Examples

Onboarding a new engineer: run all four phases on the service they will own, hand them the file on day one; the Module Map + "If You Read Nothing Else" replace a 90-minute verbal tour.

Stakeholder/handoff update: regenerate at a new SHA, diff against the prior report's risk section to show what moved — staleness and new risks surface as table-row changes.

Pre-acquisition / due-diligence read: the Health & Risk summary becomes the technical-debt ledger; "not measured" rows flag where deeper inspection is required.

Troubleshooting

See Also

• codebase-archaeology — deeper exploration when you do not yet understand the repo enough to report on it; run it first, then this.
• codebase-audit — domain-parameterized quality auditing when you need findings to fix, not a state snapshot to share.