grok-codebase

Files (3)

• GUIDE.md
• QUIZ.md
• SKILL.md

SKILL.md (first lines)

# grok-codebase — Lock a repo into long-term understanding

You are about to help the user **grok** this codebase: not just read it, but
internalize it well enough to explain it on a whiteboard in five minutes and
answer "what breaks if I change X" without re-checking. You will work the
**four-pillar model** in order, persist artifacts under
`.cheese/grok/<repo>/`, and finish with an adaptive Socratic quiz.

## Hard rules (read first, no skipping)

1. **Structural tools before raw reads.** Start with
   `mcp__tilth__tilth_list` for the directory tree (token rollups per dir
   give an instant size/shape read), then prefer
   `mcp__serena__get_symbols_overview`, `mcp__tilth__tilth_read`
   (outline mode), and `mcp__tilth__tilth_grok` over reading whole files.
   Whole-file `read_file` is a last resort for non-code files (README,
   manifests, CI YAML, env templates).
2. **One pillar at a time.** Don't skip ahead. Complete pillar 1 before
   starting pillar 2 — out-of-order grokking produces shallow understanding
   that fails on the quiz.
3. **Persist findings to disk.** After each pillar write an artifact to
   `.cheese/grok/<repo-name>/<pillar-slug>.md`. Pillar slugs:
   `01-building-blocks`, `02-entry-points`, `03-infrastructure`,
   `04-egress`, `05-trace.md`, `summary.md`, `quiz-results.md`. The user can
   review artifacts later; re-runs read them first.
4. **Stack-agnostic, TS/JS-leaning examples.** Look up language-specific
   conventions in `GUIDE.md §6` when you hit a stack you don't recognize.
5. **Token budget.** Aim for ≤30k tokens of tool output across phases 0–5
   combined. If a single tool call returns more, summarize the result,
   discard the raw output, and keep moving.
6. **Reader-first stance.** Read-only verbs only (`read_file`,
   `codebase_search`, `find_symbol`, `mcp__serena__*`, `mcp__tilth__*`
   except `tilth_write`, `@codebase`, `@docs`, `@web`). Edits are forbidden
   until the user explicitly invites them.
7. **Adaptive quiz comes last.** Only start Phase 6 after all four pillars
   are mapped AND the user confirms "yes, quiz me" (or equivalent). Drive
   it from `QUIZ.md` — don't improvise the question selection.

## Phase 0 — Reconnaissance (≤5 tool calls, ≤2 minutes)

Goal: enough context to confirm scope with the user.

Run in parallel where possible:

1. `git log --oneline -10 && git status` — recent activity, branch state.
2. `mcp__tilth__tilth_list` for the top-level directory tree (per-dir token
   rollups give an instant size/shape read) and
   `mcp__serena__get_symbols_overview` on the top source dirs.
3. Read `README.md`, the primary manifest (`package.json` / `pyproject.toml` /
   `go.mod` / `Cargo.toml` / `pom.xml`), and any `AGENTS.md` / `CLAUDE.md` /
   `.cursor/rules/` at the repo root.
4. `tokei` for a rough LOC-per-language breakdown.

Output a **5-bullet "first impressions"** summary and ask the user:
*"Scope looks like X. Proceed with full four-pillar grok, or focus on
<area>?"* Wait for confirmation.

## Phase 1 — BUILDING BLOCKS

**Question to answer:** "If I had to draw this system on a whiteboard in
5 minutes, which boxes would I draw?"

Workflow:

1. `mcp__tilth__tilth_list` over the source tree — the directory layout and
   per-dir token rollups are the closest quick proxy for a C4 Component
   diagram. Cross-check against the module boundaries the manifest declares
   (step 3).
2. For each top-level source directory:
   `mcp__serena__get_symbols_overview(relative_path=<dir>)`.
3. **TS/JS specifically:** read `package.json` `workspaces`, `exports`, and
   `tsconfig.json` `paths`/`baseUrl`. These define the *intended* module
   boundaries — compare against the *de facto* directory layout. When
   they diverge, that's a smell worth surfacing.
4. Identify 5–10 core domain symbols (`User`, `Order`, `Tenant`, …) and
   call `mcp__tilth__tilth_grok(target=<symbol>)` on each.
5. Spot god-nodes: gauge function size with `mcp__tilth__tilth_grok` /
   `mcp__tilth__tilth_read` and fan-in with
   `mcp__serena__find_referencing_symbols`. Flag any function >150 LOC or any
   module with >25 inbound references.

Write `.cheese/grok/<repo>/01-building-blocks.md` with a table:
`Block | Path | Public API | Key types | God-nodes?`.

## Phase 2 — ENTRY POINTS

**Question to answer:** "Every way control flow can begin." If no entry
point leads to a piece of code, that code is dead.

Workflow (TS/JS-first; other stacks in `GUIDE.md §6`):

1. `package.json` → `main`, `module`, `bin`, `scripts.start`,
   `scripts.dev`. Each is an entry point.
2. HTTP routes — match the framework, then probe:
   - **Next.js:** `mcp__tilth__tilth_list(patterns=["**/app/**/route.ts", "**/app/**/page.tsx", "**/pages/api/**"])`.
   - **Express:** `mcp__tilth__tilth_search(query="app.get,app.post,router.get,router.post", kind="content")`.
   - **NestJS:** `mcp__tilth__tilth_search(query="@Controller,@Get,@Post,@Put,@Delete,@Patch", kind="content")`.
   - **Fastify:** `mcp__tilth__tilth_search(query="fastify.get,fastify.post,fastify.register", kind="content")`.
3. **CLI:** `process.argv` usages, `commander` / `yargs` / `oclif`
   registrations.
4. **Workers / cron:** `node-cron`, BullMQ `Worker`, AWS Lambda handlers
   (`exports.handler`), Inngest functions, Cloudflare Workers.
5. **Real-time:** `socket.io`, tRPC routers, gRPC services.
6. For the top 3 entry points by importance, trace the downstream flow with
   `mcp__tilth__tilth_grok(target=<handler>)` (callees + tests) and
   `mcp__tilth__tilth_deps`.

Write `.cheese/grok/<repo>/02-entry-points.md` with one line per entry
point: `<method> <path> → <handler file:line>`. For each, also note
**SLA?** and **who calls this?** — if either can't be answered, that's
a doc gap.

## Phase 3 — INFRASTRUCTURE

**Questions to answer:** "What does it take to run this locally?" and
"What does it take to ship a change to production?" If you can answer
both in <2 minutes after the grok, the grok was good.

Workflow:

From paulnsorensen/dotfiles, MIT.

More from paulnsorensen/dotfiles