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:

Header — repo name, commit SHA, date generated, author/agent.
What It Is — one-paragraph purpose + run model (from Phase 1).
Architecture Overview — prose + an ASCII or Mermaid diagram of module relationships.
Module Map — the table from Phase 2.
Metrics — the numbers from Phase 3 (mark gaps "not measured").
Health & Risk Summary — the rated risk list from Phase 4.
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

Symptom	Cause	Fix
Report reads like a search log	Narrated investigation instead of state	Rewrite Phase-by-Phase as present-tense findings; delete "I then looked at…".
Module Map has gaps	Skipped a top-level dir	Re-run `ls -d */`; reconcile against the table — one row per dir.
Metrics section empty	Tooling absent and not noted	Mark each missing number "not measured"; never leave blank or estimate.
Health section is all green	Risk discipline skipped	Force at least the five risk categories in Phase 4; rate each.
Diagram out of sync with table	Edited one, not the other	Regenerate the diagram from the Module Map as the single source.

About this skill