Grok Repo

---
name: grok-repo
description: Explain an unfamiliar codebase through a repository briefing, dataflow trace, or reconstruction of why and how a change was made. Use when asked for a repo tour, how something works, where a value comes from, or why a feature changed. Not for repo health (use repo-eval).
---

# grok-repo

Read declared intent, structure, mechanics, then history for the *why*; judge taste only after evidence.
Pick one mode by the question; every claim cites a file path or commit:

- **Scoped question** ("how does X work?", "where does Y come from?") → a **dataflow trace**.
- **Change question** ("why was X added?", "how did this feature evolve?") → **change archaeology**.
- **Whole-repo question** ("explain this codebase", "give me a tour") → the **full briefing**.

## Dataflow trace (scoped mode)

Follow one datum — request, message, config value, file — from entry to effect. The trace is the answer.

- Lead with a hop chain, one line per hop, each cited:
  `POST /jobs (api/handler.go:41) → validate → Job{} (job.go:12) → enqueue (redis) → worker.Run (worker.go:88) → status written (store.go:130)`
- At each hop name its holder (type/struct/schema), transformation, and every **shape change
  or rename** (JSON→struct, field rename, enum remap).
- Mark seams crossed: serialization, queue, process/network boundary, goroutine/thread handoff.
- Close with skipped side flows, error/edge paths worth a second trace, and surprises.
- If the *why* of a hop is odd, spot-check history: `git log -S '<symbol>'` or blame the line.

## Change archaeology (history mode)

Reconstruct one feature or decision, not the repository's entire chronology:

1. **Anchor the current concept** — find present symbols, paths, config names, tests, and user
   vocabulary. State what it does now before explaining how it arrived.
2. **Find its introduction** — use `git log -S '<literal>'` for appearance/disappearance,
   `git log -G '<regex>'` for matching changed lines, and `--follow` for renamed files. Try old names.
   Releases bound the search: `git tag --contains <sha>` names the first release carrying a commit,
   and `git log <prev-tag>..<tag> -- <path>` narrows the range when the question is version-shaped
   ("when did X change?", "why did upgrading break Y?").
3. **Read commits, not just subjects** — `git show` the introduction and its parent. Bodies,
   tests, deleted code, and nearby fixes are evidence; diffs alone imply.
4. **Search the issue tracker** — the pressure for a change is usually filed before it is
   committed, so search issues by the same literals used against `git log -S`, and read
   closed ones: a rejected proposal explains a design as well as an accepted one.
   ```bash
   gh issue list --search '<term>' --state all --limit 30
   gh issue view <n> --comments
   ```
   Weak git history (shallow, squashed, imported) shifts the rationale here — go to the
   tracker first, not last. Skip if `gh auth status` fails or the remote is not GitHub, and
   say so rather than presenting git-only evidence as the whole record.
5. **Pull the review thread** — the argument for a change usually outlives the commit message
   in its PR. Recover the number from the merge that carried the commit, then read the
   discussion, not just the description:
   ```bash
   git log --merges --ancestry-path --oneline <sha>..HEAD | tail -1
   gh pr view <n> --comments        # follow "Fixes #n" links back to the issue
   ```
6. **Trace the arc** — inspect follow-up fixes, refactors, reverts, and blame on surviving lines.

Lead with **before → pressure/evidence → introduction → corrections/reversals → current form**.
Cite SHA + path per stage; close with supported rationale, rejected alternatives, unresolved
context, and history limits. Never turn commit order into causality or invent motivation.

## Reading order (full briefing)

Work top-down. On large repos, sample representative components and say what you sampled.

1. **Orient** — read relevant first-party prose before code: README/docs and any architecture,
   design-principle, ADR/RFC, or governance docs. Verify their goals, non-goals, invariants, and
   rejected alternatives against code and history. A tracked `AGENTS.md` evidences workflow and
   conventions within its scope, not automatically product intent. Then scan layout, manifests,
   build/CI, and entry points; run it if cheap.
2. **Trace one real flow** end-to-end (a request, a command, a build) before generalizing.
   Architecture claims made without a trace are usually wrong.
3. **Map components and seams** — where modules meet: interfaces, wire protocols, DB schemas,
   queues, plugin points, process boundaries. For each seam ask *why here*: testability,
   swap-ability, deploy boundary, team boundary, or accident. Note which side owns the types.
4. **Mine git history** for rationale (commands below). First check whether history is shallow,
   squashed, imported, generated, or vendor-heavy; weak history produces clues, not rationale,
   and pushes the *why* into the issue tracker.
5. **Judge taste and pick highlights** last, from the evidence already gathered.

## Git archaeology

```bash
scripts/archaeology.sh [repo-dir]         # digest first, then drill into what it surfaces
git show --stat <sha>                     # read the big commits' messages in full
git log --follow --oneline -- <hot-file>  # evolution of a load-bearing file
git log -S '<symbol>' --oneline           # when/why a concept appeared or died
```

- Find "key changes" by size and message, not recency: rewrites, "refactor", "redesign",
  version-bump commits, and any commit whose message explains a tradeoff. Good projects
  hide design docs in commit messages — quote them.
- Cross-reference **frequently touched × fix-touched** to choose files for closer reading.
  This is a lead, not proof of fragility: formatting, generated code, and long-lived files
  can dominate counts.
- **Reverts are possible negative rationale**: verify that a rollback concerns the current
  design before using it to explain why an alternative did not survive.
- Test a "team boundary" seam hypothesis with `git shortlog -sn -- <dir>` on each side:
  disjoint author sets support but do not establish it; the same names weaken the hypothesis.
- `git blame` a surprising line before calling it a wart; it often has a fix-commit story.
- For a public repo, if its history leaves consequential rationale unresolved, check project-specific
  first-party posts by core maintainers—identified by governance/ownership and sustained contribution—
  in blogs, talks, GitHub discussions, or X/Twitter. Cite author, date, and direct URL; treat individual
  or retrospective statements as context unless repository evidence corroborates them.

## Briefing contract

The briefing is a map for the reader to learn the code themselves, not a substitute for
reading it — every concept must point at the file that teaches it. Produce these sections,
in this order; cite `path:line` or short SHAs throughout.

0. **Problem & users** — what pain it removes, for whom, and what the project deliberately
   does *not* do (non-goals are often stated in README/docs or early commits). Issues closed as
   not-planned state non-goals more bluntly than docs do: `gh issue list --state closed --search
   'reason:not-planned'`, plus the project's own refusal label if it has one (`--label wontfix`).
   GitHub issue search has no `OR`, so run one qualifier at a time. Cite the issue number.
1. **Architecture** — the 3-7 major components and the shape connecting them (pipeline,
   hub-and-spoke, layered, plugin host…). One paragraph plus a compact diagram or list.
2. **Design taste** — the authors' consistent choices, each backed by two or more examples:
   dependency policy, error-handling style, abstraction depth, naming, testing philosophy,
   concurrency model. Taste is what repeats; one instance is noise.
3. **Components & seams** — per component: responsibility, its inbound/outbound seams, and
   why the boundary sits there. Flag seams that leak (imports crossing the "wrong" way).
4. **History & rationale** — 3-6 pivotal commits/eras and what each reveals about why the
   design is what it is (e.g. "storage was swapped behind an interface in <sha> after X").
5. **Beautiful code** — if evidence warrants it, show 1-3 pieces that are novel,
   dense-but-clear, or do a lot with a little. Quote a short excerpt and say precisely what
   makes it good: the invariant it protects, the cases it collapses, or the API it keeps honest.
   If none stands out in the sampled code, say so instead of manufacturing praise.
6. **Hooks for curiosity** — the project's own vocabulary (5-10 jargon terms → the file
   that defines each), 2-3 flows that would make good dataflow traces, and open questions
   the analysis couldn't resolve — unexplained seams, suspicious code, undocumented decisions.
   Check the open issues before writing this section: they say which of your questions the
   maintainers already know about (link the issue) and which are genuinely unexamined, and
   the oldest open ones often mark the design's real soft spots. Note if the tracker is
   unused or disabled — that is itself a finding about how the project is maintained.

## Notes

- Separate observation from inference: "X calls Y via Z" is read from code; "probably for
  testability" is a guess — label guesses.
- Docs evidence stated intent; code determines current behavior. If they disagree, report both.
- Time-box: for repos over ~100k lines, deliver the briefing from entry points + one traced
  flow + history, and list which areas were not read.
- Close full briefings with coverage: what was inspected, what was sampled or skipped, which
  claims depend on inference, and whether tests or a real invocation were run.