Grok Repo

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.

   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:

   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

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 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.