code-wiki-recon

# Code Wiki Recon Bootstrap understanding of an unfamiliar codebase by pulling Google Code Wiki's auto-generated architecture documentation. Saves significant manual `grep`/`Read` exploration on the first encounter. ## When to invoke - User says "first time looking at X repo", "help me understand X's architecture", "what's in this codebase" - Before doing any non-trivial work on a repo Claude hasn't seen before in this session - When user shares a GitHub URL and asks for a high-level summary Do NOT invoke when: - The user is asking a specific runtime/optimization/debugging question — Code Wiki cannot answer these (see [references/limitations.md](references/limitations.md)) - The repo is small/trivial (<50 files) — just read it directly - A cache already exists at `~/.claude/cache/code-wiki/{org}-{repo}.md` and the user hasn't asked for a refresh ## Required tool Code Wiki is a SPA (Angular/boq) — its TOC and content are JS-rendered, so curl/WebFetch cannot extract them. A real browser is required. Use **chrome-devtools-mcp** (preferred) or **playwright-mcp**. If neither is available on this bot, fall back to manual exploration (see Step 6 below) and tell the user Code Wiki recon is not possible in this environment. ## Workflow ### Step 1 — Detect coverage ``` chrome_navigate(https://codewiki.google/github.com/{Org}/{Repo}) chrome_take_snapshot() ``` Repo segment is **case-sensitive** in the URL — match the canonical GitHub casing (e.g., `AI-Hypercomputer/maxtext`, not `ai-hypercomputer/maxtext`). If unsure, navigate to the GitHub repo first and use the URL bar's casing. Check the RootWebArea title in the snapshot: - `"{org}/{repo} | Code Wiki"` → covered → continue - `"Not Found | Code Wiki"` → not covered → skip to Step 6 (fallback) ### Step 2 — Pull the TOC Run via `chrome_evaluate_script`: ```javascript () => { const tree = document.querySelector('[role="tree"]'); if (!tree) return null; return Array.from(tree.querySelectorAll('[role="treeitem"]')).map(el => ({ level: parseInt(el.getAttribute('aria-level') || '1'), text: el.innerText.trim().split('\n')[0] })); } ``` The TOC is Code Wiki's most valuable artifact — it's Gemini's section-by-section decomposition of the codebase. ### Step 3 — Capture the main overview The default landing page has the auto-generated architecture diagram + intro. Grab the body text: ```javascript () => document.querySelector('.body-content')?.innerText.slice(0, 8000) || null ``` Optionally take a full-page screenshot. The save path is constrained by the MCP — try `~/.playwright-mcp/codewiki-{org}-{repo}-overview.png`. If the MCP rejects the write (some chrome-devtools-mcp instances disallow file output), skip silently — the screenshot is non-essential, the body text + TOC are the value. ### Step 4 — Section summaries (usually free) **Check the body text from Step 3 first.** Code Wiki's main overview page typically includes one paragraph per top-level section already (it's the auto-generated "executive summary"). If the body covers all level-1 sections from the TOC, **skip the per-section clicks** — you have what you need. Only if a level-1 section is missing from the main overview, click it via its uid from the snapshot, wait ~1s, then: ```javascript () => document.querySelector('.body-content')?.innerText.slice(0, 500) ``` Never pull every leaf section. Detail is fetched on demand by Claude later. ### Step 5 — Cache to disk Write `~/.claude/cache/code-wiki/{org}-{repo}.md` using the template at [references/cache-template.md](references/cache-template.md). Required frontmatter fields: - `repo`, `source`, `fetched_at` (HKT, absolute date), `codewiki_commit` (from page footer if visible) The cache file MUST begin with the authority warning verbatim: > **Authority warning**: This summary is auto-generated by Gemini from public README/code. It is reliable for **architecture and module boundaries**, unreliable for **runtime behavior, optimization, or non-obvious design decisions**. Verify by reading actual code before acting on details. ### Step 6 — Hand-off After cache is written, report to the user in one short message: - Where the cache lives - TOC top-level section count + names - 2-3 sentence architecture summary - Suggested next step based on the user's goal In subsequent turns of the same session, `Read` the cache file when architecture context is needed. Don't re-fetch unless the user asks or > 30 days have passed since `fetched_at`. ## Fallback (Code Wiki doesn't cover the repo) If Step 1 returned "Not Found", or no browser MCP is available: 1. `Read` `README.md` (always) 2. `Read` `ARCHITECTURE.md`, `CONTRIBUTING.md`, `docs/index.*` if they exist 3. `Glob "**/*.{md,rst}"` and pick the top-level / overview docs 4. List top-level directory layout (`Glob "*"` + `Glob "*/"`) 5. Write a manual recon doc at the same cache path, mark `source: local-exploration` in frontmatter, drop the codewiki-specific authority warning, replace with: "Manually compiled from repo docs — verify details by reading actual code." Never silently skip the recon step just because Code Wiki doesn't cover the repo. The cache file is the contract for downstream Claude turns. ## Authority boundary — READ BEFORE CITING **Always read [references/limitations.md](references/limitations.md) before answering follow-up questions that lean on Code Wiki's content.** Failure risks relaying shallow auto-generated answers as expert knowledge. Quick rule: if the user's follow-up is about *what code exists / how it's organized*, citing the cache is fine. If it's about *why a design choice was made, how to fix a bug, or how to tune performance*, **drop the cache and read actual source code**.