
code-intelligence
Codebase exploration, navigation, mapping, and static analysis tools for understanding unfamiliar codebases.
- version
- 2.6.0
- GitHub stars
- 404
Install
/plugin install code-intelligence@oaustegard-claude-skillsRun it inside Claude Code after adding the marketplace with /plugin marketplace add oaustegard/claude-skills.
Contents
Discovered from sourceSkills 14
Assessing Impact
Cheap, ad-hoc impact analysis for a single target. Not a graph database — a focused walk over an AST cache plus a complementary text scan, clustered into a report that's easy to summarize.
Use this when you're about to refactor / rename / delete a symbol in a repo you don't work in daily, and you want a single artifact that says: "these N files will need to change, in these M packages, with these tests likely affected."
Don't use this for deep ongoing impact analysis on your own codebase — stand up GitNexus, SourceGraph, or your IDE's index. This skill is for the one-shot case.
Setup
uv venv /home/claude/.venv 2>/dev/null
uv pip install --python /home/claude/.venv/bin/python tree-sitter
export PYTHON=/home/claude/.venv/bin/python
export IMPACT=/mnt/skills/user/assessing-impact/scripts/impact.py
The script depends on the tree-sitting skill — it imports engine.py
directly. The bundled grammars live with tree-sitting; no separate
language-pack install needed.
Workflow
1. Run the report
$PYTHON $IMPACT /path/to/repo SYMBOL_NAME
Or target a whole file:
$PYTHON $IMPACT /path/to/repo path/to/module.py
2. Read the data, write the summary
The script prints a structured markdown report. Treat it as input for your final summary, not the deliverable. It deliberately doesn't assign a "high/medium/low" risk label — that's your job, after weighing:
- Refs concentrated in one package (low blast) vs. fanned across many (high)
- Test refs present (good — the change has a verification surface) vs. absent
- Doc mentions (renames need to update docs too)
- Caveats listed at the bottom (what the script can't see)
3. Drill if needed
If a particular package looks suspicious, follow up with tree-sitting
to read the actual call sites:
TREESIT=/mnt/skills/user/tree-sitting/scripts/treesit.py
$PYTHON $TREESIT /path/to/repo --no-tree 'source:caller_function'
Options
| Flag | Default | Purpose |
|---|---|---|
--features PATH | _FEATURES.md | Root _FEATURES.md — when present, refs get clustered by feature in addition to by package. |
--skip DIRS | (defaults from tree-sitting) | Extra comma-separated dirs to skip. |
--limit-per-name N | 500 | Cap refs per symbol name. Bump if you suspect truncation. |
--json | off | Emit JSON instead of markdown — for downstream tooling. |
Output Sections
# Impact Report: <target>
## Target
Kind, definition sites with line ranges.
## Direct & Textual References (N total)
Top-line counts, then refs grouped by:
- Code references by package
- Test references
- Documentation mentions
## Affected Features (from _FEATURES.md) ← only if file present
Feature name → ref count + file count.
## Suggested Test Surfaces
Test files that already reference the target, plus tests neighboring
the definition. Likely the regression net for the change.
## Caveats
What the scan can't see (dynamic dispatch, cross-language, cross-repo).
Composition with Other Skills
- Run after
exploring-codebasesif the repo also has a freshly generated_FEATURES.md— the impact report will cluster refs by feature, which makes the blast radius story much more legible than raw package directories. - Use
tree-sittingto drill specific call sites once impact has identified them. - Use
searching-codebaseswhen you want regex/AST search over the same corpus rather than impact analysis on a known target.
Honest Limits
- Text-based ref discovery. Refs are matched by symbol name, not by
type-resolved call edges. Common names (
run,init,handler) will pick up unrelated symbols. Prefer running this on distinctive names; otherwise expect noise and read the snippets. - No type/MRO resolution. Dynamic dispatch (
getattr, duck-typed method calls, virtual dispatch in C++) is missed or over-matched. - No cross-language tracing. A TS frontend calling a Python backend handler over HTTP appears as zero refs — they're not in the same AST.
- No cross-repo tracing. Consumers in separate repos (downstream packages, sibling services) are invisible. For multi-repo impact, reach for GitNexus / SourceGraph.
- No persistent index. Each run re-scans. Fine for single-shot use; acceptable cost (~700ms scan + sub-ms queries) for a few hundred files.
- Diff input not yet supported. v0.1 takes a symbol or file path. Diff → affected-symbols extraction is a planned follow-up.
Files
scripts/impact.py— Single-entry CLI. Resolves target → walks AST refs → augments with text scan → clusters by package and (optionally) by feature → renders markdown or JSON.
declaring-invariants
Two scripts over one idea: a test that enumerates a domain must loop the registry rather than a copy of it. Someone also has to say which domains matter in the first place.
python3 scripts/totality_lint.py <repo> # tests that copy a domain
python3 scripts/claims.py <repo> # what the repo declares, and what backs it
Python only, stdlib ast only: no install, no config file, no network.
The failure it catches
A test that loops a hand-written list passes its runner and proves nothing about completeness. When the same members also exist as a registry in the source, the list is a copy, and the copy drifts the moment someone adds a member to the registry and not to the test. Nothing goes red.
Measured on oaustegard/remex, 2026-08-24: adding a fourth member to
ROTATION_CODES with no construction behind it left the entire 267-test
suite green. Four separate tests looked total; each parametrized
["haar", "rht"] against a three-member registry. Only a test that looped the
registry itself caught it.
Adapted from the meta-oracle in daniloc/coherence
(src/oracle-domain.ts), which classifies an oracle's iteration root as LIVE
or LITERAL by parsing the oracle's own AST. That harness needs spec files, a
claim grammar, a ledger and Node; the check does not.
totality_lint.py — tests that copy a domain
| finding | meaning |
|---|---|
sampled-domain | a parametrize or for over a literal whose members are a strict subset of a source registry. The uncovered members are named. |
ratchet-broken | a hand-list marked ratchet names a member the registry no longer contains. Detected statically, without running anything. |
unratcheted | a registry enumerated live with nothing pinning its membership. Suppressed when no-floor already claimed the same line. |
no-floor | a test iterates a live registry with no len(...) >= n assertion in the file, so an emptied registry passes vacuously. |
stale-ack | an acknowledgement on a test that now covers the whole domain. |
python3 scripts/totality_lint.py <repo> # the report
python3 scripts/totality_lint.py <repo> --json
python3 scripts/totality_lint.py <repo> --strict # exit 1 if any finding
python3 scripts/totality_lint.py --selftest # fixtures, no repo
A partial domain is often correct. Say so on the test and it stops being a finding:
# totality: partial — mojo has no construction for "none"
@pytest.mark.parametrize("rotation", ["haar", "rht"])
def test_save_params_accepts_every_mojo_rotation(rotation): ...
The marker also works as totality: partial — <why> inside the docstring. An
acknowledgement on a test that later covers the whole domain is reported as
stale-ack, so a suppression cannot become a silence.
Why a hand-list is the second form
An enumeration loops whatever the domain currently holds, so it is
structurally blind to the domain narrowing. Remove a member and the loop simply
ranges over fewer of them, green. Raised by Yep, 2026-08-24; reproduced on
oaustegard/remex before being believed:
perturbation of ROTATION_CODES | domain floor | enumeration | parity | hand-list |
|---|---|---|---|---|
grow — add "hadamard2" | pass | RED | RED | pass |
shrink — drop "none" | RED | pass | RED* | pass |
substitute — "none" → "xyz" in both spellings | pass | pass | pass | pass |
* only because the other spelling of the domain did not shrink, which is incidental to that repository.
In the substitution row cardinality holds, both spellings agree, and five green tests cover a registry that quietly stopped supporting a rotation every index on disk was written with. The floor is a cardinality check; it cannot see a member swapped for another.
The second form is a ratchet: a hand-list asserting the domain keeps containing it. Mark it and the linter checks the pin rather than taking the marker's word for it.
# totality: ratchet — these three shipped; one leaving is a compatibility break
def test_no_shipped_rotation_is_ever_removed():
for shipped in ("haar", "rht", "none"):
assert shipped in ROTATION_CODES
Under that same substitution the linter reports ratchet-broken naming
'none' statically, before any test runs, and the test itself goes red
while the other five pass.
So: an enumeration proves every current member is handled, and a ratchet proves
no member left without a decision. unratcheted names a registry that has the
first and not the second. Neither half alone is the answer.
A ratchet covers shrink only. Over a strict subset it still reports
sampled-domain for the members it never listed, because pinning two of three
says nothing about the third. Suppressing that would make the marker a
laundering channel — the escape hatch these notes criticise via guard for
being in coherence. It was one: until 2026-08-25, # totality: ratchet over
two of three members silenced the report entirely and checked nothing about the
third. Caught by an adversarial pass on this skill, not by its own tests.
claims.py — what the repo declares
totality_lint asks whether a test's domain is complete. It presumes a test
exists. This asks the prior question, the one coherence's own Known Limits
concedes it does not answer: nothing enforces exists ⇒ declared.
A claim is a test whose docstring opens with invariant:. No new file
format, and the claim inherits its test's pass/fail:
def test_every_skipped_directory_is_actually_skipped(self):
"""invariant: every name in SKIP_DIRS is excluded from the walk.
refuted: replaced the walk's `part in SKIP_DIRS` check with
`part in {"node_modules"}` -> this test went red naming `.coherence`,
while the other 25 tests in this file stayed green.
"""
| finding | meaning |
|---|---|
unrefuted | a claim nobody has watched fail |
literal | the claiming test iterates a copy of the registry, so the claim cannot see a new member |
unanchored | a registry no invariant names — a question, not a verdict |
A claim whose test carries a ratchet marker is reported as pinning its
registries rather than copying them, and a ratcheted registry is not
unanchored.
python3 scripts/claims.py <repo> [--json] [--strict] [--selftest]
Write the refutation from what you observed
refuted: is the half that costs something. Break the chokepoint, watch the
claim go red by name, restore, and record what you saw. A green test and an
unfalsifiable one look identical from outside; the refutation is what separates
them.
Never write a refutation you have not run. The first refutation authored
for the SKIP_DIRS invariant above asserted a failure that did not occur — the
fixture placed the registry outside the test's reachability, so the test passed
under perturbation for an unrelated reason. A vacuous claim, written while
building the tool that catches vacuous claims, and caught only by running the
perturbation instead of trusting the sentence.
Procedure, in order:
- Break the chokepoint the claim names, with one edit in the source rather than in the test.
- Run the claiming test. Read the failure text. Note the member it named.
- Run the rest of the file. Confirm the others stay green — if everything goes red, the claim is not localised and the refutation says nothing.
- Restore the source.
- Write
refuted: <the edit> -> <what went red, by name>.
Wiring it into a commit gate
The reference wiring lives in oaustegard/claude-workspace
(scripts/tdd_hook.py): a commit where a registry gained a member and no
invariant: test iterates it live is denied, naming the registry and what it
gained. Override with no-invariant: <why> in the commit body.
Registry shrink is gated the same way, and needs a ratchet rather than an enumeration to clear it. A new function or a new branch is behavioural growth too, but neither is diffable without guessing, and a gate that guesses stops being consulted. A brand-new registry is not gated. Declaring one is a judgement call; growing one has already made it.
Where the two filters came from
Both filters exist because the unfiltered version was noise. Reproduce either by removing the filter and re-running against a real repo.
no-floorfires only on a name independently recognised as a registry. Firing on everyfor x in <local>produced 27 findings onremex, all noise: numpy arrays, query matrices, loop counters.- A literal matches a registry only when reachable — the test imports its
module or package, shares its top-level directory, or is its paired
tests/test_<mod>.py. Matching against any registry in the tree joined a test indiscrepancy/to registries inkb-k-sweep/andremex-vs-higgs-ablation/on a monorepo, because small integer sets collide by chance. Four findings became one, and the survivor was real.
The join key is membership, not names: [1, 2, 3, 4, 8] and
SUPPORTED_BITS share no token, so containment is what ties them together. No
naming convention is assumed, and none is required.
Limits
- Python only. The extractors are
_registries_pyand_domains_py; a tree-sitter pair for another language slots in beside them. The join, the acknowledgements and the reports are all language-independent. - Report, not gate, by default.
--strictopts into a nonzero exit. The tool this was adapted from gates by default, and its parity arm false-fails a correct oracle that binds its domain to a local name first. A gate that false-fails stops being consulted. - A registry is a collection of constants. A dict/set/tuple/list of literals, or an Enum body, with at least three members. A domain assembled at runtime is invisible here.
- Multi-parameter tables are out of scope. Only single-name
parametrizeis read. unanchoredis a question. Most registries need no invariant. Treat the list as candidates for declaration, never as a backlog to clear.- A registry is modelled as a SET OF KEYS, so a value swap is invisible.
This is the largest hole in the design, and it undercuts the motivating
example.
ROTATION_CODES = {"haar": 0, "rht": 1, "none": 2}exists to pin bytes on disk; permuting it to{"haar": 0, "rht": 2, "none": 1}keeps every key, every count and every ratchet intact, and every index already written decodes under the wrong rotation. Verified 2026-08-25 on a fixture: the linter reports nothing and the gate's registry half reports nothing. (The gate denied that fixture, but on the unrelated TDD rule — checked, because claiming otherwise would have been the overclaim this skill exists to catch.) Nothing here checks a name-to-code mapping. Extracting(key, value)pairs as the member set would, at the cost of breaking the subset join against aparametrizelist of keys. - A co-ordinated rename defeats the ratchet. A global find/replace that
renames a member in the registry AND in the hand-list leaves the pin intact,
and this reports nothing. Verified 2026-08-25 on a fixture: renaming
"none"to"identity"in both files was silent, while every index already on disk still decodes byte 2 as the old name. Both sides of a co-located hand-list move together, so no static check over one working tree can see it. The commit gate can, because it diffs against git history — and only if the ratchet itself is untouched in that commit, which it now requires. - A brand-new registry is neither gated nor pinned. Create one with five
members and never grow it and no gate ever fires.
unanchoredandunratchetedsurface it in the report; the gate deliberately does not, on the grounds that gating every new module is how a gate stops being consulted. That is a judgement, not a proof, and it is the largest hole a cross-model review found. - A decorator-built registry is invisible.
@register("name")populating a dict at import time is the common Python registry idiom and is not a literal, so nothing here sees it. Named because it is the shape most likely to be mistaken for coverage. - Reachability is path-based, so a disconnected integration test is missed. A test that neither imports the module, shares its top-level directory, nor pairs with it by filename will not be joined to the registry it samples. The filter trades that recall for the cross-project precision it was measured to buy.
- The precision numbers come from three repositories, and the filters were fitted to two of them. 27 noise findings on one, 3-of-4 cross-project joins on another. Those are the measurements that justified each filter; they are not a false-positive rate on a corpus, and should not be read as one.
- Split and merge are invisible. The diff is keyed on registry NAME, so renaming a registry, splitting one in two, or merging two into one falls through both the gained and lost paths.
- A claim that passes is not a claim that is right. This checks that a declared invariant loops the domain it names. Whether it is the right invariant is human judgement, and it is not automatable.
Related
verifying-claimscovers the prose layer: does the documentation match reality? Agent-judged, non-deterministic, run as a triggered review. This skill is the deterministic half, over code and tests rather than prose.tree-sittinglocates the registry or the test before you edit it.building-property-testsfinds the bugs; its step 9 promotes the properties a codebase depends on intoinvariant:claims checked here. Draw its generators' domains from the registry, as a test's parametrize list should.
Describing products
A product description treats the product as a large state chart the user moves through with input. The repo describes that state chart feature by feature, in plain language, from the user's side, with one skeleton for every document so that gaps and inconsistencies show up by comparison. Documents are drafted from source and tests, verified by hand against the running product, and every suspected defect lands in one triage file.
Adjacent skills: featuring inventories what a codebase does, by capability; this skill specifies how each capability behaves under every input and interruption. A _FEATURES.md is a good seed for this repo's structure, not a substitute for it.
{skill} below is this skill's directory.
| File | Use |
|---|---|
references/product-kinds.md | Map the template onto a canvas editor, web app, CLI, chat product, or library/SDK. Read in Phase 0. |
references/README-template.md, goal-template.md, glossary-guide.md | Skeletons for the three files that steer the build. goal-template.md carries the writing rules. |
references/document-template.md | The eight-section skeleton every feature document follows. |
references/verification-template.md, bug-triage-template.md | Skeletons for the checking half. |
scripts/check_links.py | Every relative link and heading anchor resolves (GitHub slug rules). Links to documents the coverage table lists as not started are reported as planned; --strict counts them as broken. |
scripts/check_structure.py | Coverage table matches disk; sections in order; footer present; modifier, interrupt and concern rows identical across documents; no empty cells. --exclude names extra non-feature files. |
Both scripts are stdlib Python 3, take the repo root, and exit 1 on failure.
Outputs
README.md purpose, conventions, document template, method, structure, coverage table
goal.md standing instructions for whoever drafts (you, subagents, a future session)
glossary.md the vocabulary; source of truth for every term of art
AGENTS.md "Read README.md, then goal.md. The coverage table in README.md is the work list."
CLAUDE.md "Read @AGENTS.md."
{area}/{feature}.md one document per feature, all on the same skeleton
verification/ README.md (protocol) + one checklist file per cluster of documents
bug-triage.md every suspected defect, deduplicated, with repro, cause, severity, decision needed
Phase 0: scope
Settle these before writing a file. Ask only for what the conversation and the source repo cannot answer; record the answers in the README's "Scope decisions".
- Product and surface. Which app, route, role or configuration, with what customization (usually none). One surface per repo.
- Source of truth. Path to the source repo (read-only) and its commit. Every document footer cites
git rev-parse --short HEADof that repo. - Where to run it. The command and URL, binary, or account that brings the surface up for verification.
- Out of scope. Name each exclusion and why, so readers do not take it for an omission.
- Where the repo goes. A new directory with
git initand a first commitInitial commit, or a directory inside an existing repo when the user keeps such work there (then follow that repo's conventions too, and pass its extra files, such as aRESULTS.md, tocheck_structure.py --exclude). - The product's shape. From
product-kinds.md, decide once: the unit of interaction and its five phase names; the variant axis; the fixed interrupt list; the cross-cutting concerns and their order. These go into the README's "Document template" and the glossary before the pilot, and do not change afterwards without revisiting every document.
Then reconnoitre the source repo for: where interaction state lives (state machines, reducers, controllers, route handlers, command definitions), the behavior tests that read as executable specs of edge cases, the UI, and where defaults and thresholds are defined. Use tree-sitting or exploring-codebases for this when available rather than reading files whole. The findings fill the README's "Reference" section and goal.md's reading order.
Phase 1: scaffold
Write, in order, from the templates:
- README.md from
README-template.md. The structure section is the plan: every expected document with a one-line gloss, grouped by how the user meets the feature (foundations, then the product's areas, then cross-cutting concerns), never by package or module. The coverage table lists every document asnot started. Revise both as you learn; they must always mirror the files on disk. - glossary.md from
glossary-guide.md. Start with the terms the foundations need and the interrupt words from Phase 0. A term used in a document but absent from the glossary is a consistency bug. - goal.md from
goal-template.md. It drives all drafting. Its "Things already established" section starts empty. - AGENTS.md and CLAUDE.md with the contents shown under Outputs. AGENTS.md is what a fresh session reads first; never leave it empty.
Commit: docs: add README, glossary, goal.
Phase 2: pilot, foundations, the hardest area
Do these yourself, in sequence. They fix the template, tone, depth and vocabulary everything else copies.
- Pilot. One small, self-contained feature with a real interaction in it (
product-kinds.mdnames one per kind), on the full eight-section template. Iterate until it is right. A small feature done properly runs 150–200 lines with every phase narrated, every variant and interrupt cell filled, and the cross-cutting list walked in full; a thin section means the feature has not been read closely enough. Runcheck_structure.pyon the repo once the pilot exists; it is the reference shape from here on. - Foundations. The documents everything links to: the input or invocation model (events, thresholds, what cancels, completes, interrupts), the core object or data model, the mode, tool or navigation model, the viewport or session model. They own the facts other documents link to. As each lands, add its essential facts (numbers, defaults, rules) to goal.md's "Things already established".
- The hardest area. The bulk of the experience (the selection tool, the main editor, the
buildcommand, the composer plus the streaming response). Read all of its state handling before writing any of its documents: the states hand off to each other and the documents must agree on where one ends and the next begins. Record which document owns which state in goal.md.
Commit after each document or coherent group: docs: add {path}.
Phase 3: draft the rest in parallel
The remaining documents are independent. Fan out one document or small cluster per subagent, with this prompt:
Read
goal.md,README.md,glossary.md,{pilot}, and{the foundation document this feature depends on}. Write{area}/{feature}.mdon the same skeleton, at the same depth. Use the glossary's words. Do not editglossary.md,README.md,goal.mdor any other existing document: if you need a term the glossary lacks, use it and list it in your report with a proposed definition and section. Do not modify the source repo. End with "## Open questions and verification" and the footer. Report what you could not determine from code and tests, and the proposed glossary terms.
Parallel drafters must not write shared files: two agents editing glossary.md at once lose each other's terms, and two coined definitions for one word are a consistency bug that surfaces only in Phase 4. Merge the proposed terms yourself, once, picking one word per concept, and fix the drafts that used the losing synonym.
Review every result before accepting it: glossary words used correctly, established facts not contradicted, interrupt table complete (every row, even "no effect"), suspected bugs stated plainly in "Open questions" rather than smoothed over. check_links.py and check_structure.py --reference {pilot} catch the mechanical half.
Update the coverage table to drafted as each lands. Commit in groups: docs: add {paths}.
Phase 4: consistency pass
Mechanical, both must exit 0:
python3 {skill}/scripts/check_links.py {repo} --strict
python3 {skill}/scripts/check_structure.py {repo} --reference {pilot}
Without --strict, links to documents still not started are listed but do not fail; use that during Phases 2 and 3.
By reading, over the whole set:
- Same term for the same thing everywhere; every term of art defined in the glossary; glossary definitions agree with the documents.
- No two documents describe the same behavior differently. Where two documents touch, one owns the behavior and the other links.
- Variant and interrupt answers agree where the same mechanism is involved (the scripts check rows, not content).
Commit: docs: revise the set after the consistency review. Then deepen the documents whose open questions were thinnest; expect a second revision on a handful.
Phase 5: verification checklists
Drafting reads the code; verification watches the product. From verification-template.md:
verification/README.md: how to bring up the surface, confirm the commit, run a pass, record results, file failures, and when a document moves fromdraftedtoverified.- One checklist file per cluster of documents, one table per document, one row per observable claim: stable ID (
AREA-NN), priority (P1 established fact or suspected bug, P2 ordinary claim, P3 a number, color or timing), what it needs (device, role, network condition), the claim linked to its section, setup, numbered steps, expected result, Result (—until run). Claims not checkable by hand go under "Not checkable by hand".
For a library or a CLI, every item is a short script: write verification/run_pass.py with one function per checklist ID, and probe claims with those scripts while drafting rather than after. Each automated item must assert the exact expected outcome (exception type and message, file names, values); a check that accepts any exception will pass a wrong claim.
If you can drive the product (Playwright or other browser automation, a console handle on the app, a shell for a CLI, a test harness), run a first pass on what that can observe, record results in the Result columns, and state in verification/README.md exactly what the pass did and did not cover (a scripted pass checks output, exit codes and stored state, not what was on screen or how long it took to appear). Never mark a document verified on an automated pass alone. A failed item is not automatically a product bug; sometimes the document is wrong, and the Status line says which.
Phase 6: bug triage
From bug-triage-template.md: collect every suspected defect from every document's body and open questions, merge by root cause (one cause raised by many documents is one entry with many "Raised by" links), and write each up with where the user meets it, what happens vs. what was expected, reproduction steps, the cause in code with file and line, a severity, and the decision needed (fix or product call). Summary table on top, sorted by severity. Entries a verification pass touched carry a Status line.
Filing upstream is outward-facing. Offer it; never do it unasked. If the user wants issues filed, confirm the repo and format first, file them, then add an Issue line to each entry and a link column to the summary (docs: revise bug-triage.md with links to the filed issues).
Resuming and extending an existing repo
A later session, or a request to add an out-of-scope feature, starts here rather than at Phase 0.
- Read
AGENTS.md,README.md(structure, coverage, scope decisions),goal.md(established facts) andglossary.md. Read the pilot to recalibrate depth. Run both scripts to see the repo's current state. - Confirm the source repo's commit. If it moved, decide with the user whether new documents cite the new commit (and say so in their footer) or the repo pins the old one.
check_structure.pywarns when documents cite more than one commit; never let that happen silently. - To add a document: add it to the README structure and coverage table first, write it, add its checklist table to the right
verification/file (new ID prefix, numbered from 01), add any new triage entries with the nextB-NN, and commit each step:docs: add {path},docs: add the {name} checklist ({PREFIX}-01 to {PREFIX}-NN) to verification/{cluster}.md,docs: add B-NN to B-MM to bug-triage.md from the {name} work. - To revise after a verification pass: change the document, update the checklist row's Result and note, update the triage entry's Status, commit
docs: revise {path}. - Never renumber checklist or triage IDs once a pass or an issue has used them.
Writing rules
They live in goal-template.md and are copied into goal.md, which every drafter reads. The ones most often broken:
- Describe the experience, not the code: "the form stays disabled until the server answers", not "the mutation sets isPending". Mechanism goes only in
> Technical note:block quotes, and only when it changes what the user would expect. - Every table cell filled, "No effect." included. An empty cell is an unasked question.
- When code and tests cannot settle a behavior, write what they do settle, put the rest in "Open questions", and move on. Do not guess; do not block.
- Never modify the source repo.
- Follow the target repo's convention on AI attribution in commit messages.
What never changes, whatever the product
The outside-in stance; one skeleton for every document; the interrupt list asked of every feature in the same order; a glossary that owns the words; foundations written first so they own the numbers; a pilot that sets the depth; drafting from code and tests, then verifying against the running product, then triaging what looks wrong. product-kinds.md covers what to rename; this list is what stays fixed.
Adapted from Steve Ruiz's product-description skill (gist.github.com/steveruizok/83ae5c53f2784ebf8f5fe0a3fb94480f), first used on a ~65-document description of a canvas editor.
Exploring Codebases
Exploratory code analysis for unfamiliar repositories. Orchestrates tree-sitting (structural) and featuring (semantic) over a local copy.
Workflow
Five numbered steps, in order. Do not skip step 0.
0. Setup (once per session)
uv venv /home/claude/.venv 2>/dev/null
uv pip install tree-sitter --python /home/claude/.venv/bin/python
export PYTHON=/home/claude/.venv/bin/python
export TREESIT=/mnt/skills/user/tree-sitting/scripts/treesit.py
export GATHER=/mnt/skills/user/featuring/scripts/gather.py
If step 2's --stats reports Symbols: 0 on a repo you know contains code,
the tree-sitter core package isn't installed — come back here and install it
(the engine bundles its own grammars and does NOT use tree-sitter-language-pack).
Treesit exits 0 and prints no error in that case, so zero symbols is the only
signal you get. There is no Errors: line: that one appears for parse
failures, and an absent parser never reaches parsing. The full signal is in
the tree-sitting skill's Setup section.
1. Get the repo (tarball, not per-file)
OWNER=...
REPO=...
REF=main # branch name, tag, or SHA. For a PR: pull/N/head
curl -sL -H "Authorization: Bearer $GH_TOKEN" \
"https://api.github.com/repos/$OWNER/$REPO/tarball/$REF" -o /tmp/$REPO.tar.gz
mkdir -p /tmp/$REPO && tar -xzf /tmp/$REPO.tar.gz -C /tmp/$REPO --strip-components=1
ls /tmp/$REPO | head # sanity check — did extraction land?
One HTTP call gets the whole repo. Do NOT curl README, cat files, or
fetch via contents/PATH first — they're in the tarball. The
Authorization header is only needed for private repos; public repos
work without it.
Ref selection matters. If exploring a feature branch, PR, or tag,
set REF accordingly. The default main will silently give you stale
code if the question is about an unmerged branch.
2. Structural scan
$PYTHON $TREESIT /tmp/$REPO --stats
Read the output. It gives file counts, symbol counts, languages, and per-directory symbol density. This IS the orienting artifact — treat it as the product of this step, not warm-up.
Drill only if you have a specific question. For pure "what is this repo" exploration, skip drilling and go to step 3 — featuring surfaces the interesting paths for you. Drill when a user asked about a specific subsystem, or when step 3's output raises a question that needs source.
When you do drill, batch queries in one invocation. Every treesit call pays the full scan cost. Multiple queries added to the same command share that scan and each additional query adds ~0ms. If you're about to make a second treesit call on the same path, fold it into the first.
# GOOD — one scan, three answers
$PYTHON $TREESIT /tmp/$REPO --path=SUBDIR --detail=full \
'find:*Handler*:function' 'source:main' 'refs:Config'
# BAD — three scans, three answers (3× the cost for the same information)
$PYTHON $TREESIT /tmp/$REPO --path=SUBDIR --detail=full
$PYTHON $TREESIT /tmp/$REPO 'find:*Handler*:function'
$PYTHON $TREESIT /tmp/$REPO 'refs:Config'
3. Feature synthesis
Pick the mode from your DELIVERABLE, before you run it.
| Your deliverable | Command | Size |
|---|---|---|
| Your own understanding — a review, an orientation read, answering a question | --orient | ~115 lines |
A written _FEATURES.md that must cite every symbol | full output | thousands of lines |
# Default. Complexity assessment, decomposition ranking, directory tree, entry points.
$PYTHON $GATHER /tmp/$REPO --skip tests,.github,node_modules --orient
# Only when you are about to WRITE the inventory into a file:
$PYTHON $GATHER /tmp/$REPO --skip tests,.github,node_modules --source-budget 8000
Output includes a "Candidate areas for sub-files (by symbol density)" list near the top — that's your drill-target picker, ranked.
Never pipe the full output through head. If you are about to truncate it,
--orient was the correct mode and you have paid for thousands of lines you
will not read. One review's full gather ran to 5,697 lines and was cut at line
120; every finding in it came from treesit drilling and targeted reads
instead. --orient returns the ~115 lines that get used. The full mode's
symbol inventory exists to be CITED, not read.
4. Reason about the combined output
Synthesize 2+3: capabilities, feature groups, architecture, entry
points, anomalies. Produce _FEATURES.md when warranted. This is the
LLM step; everything before was mechanical.
When to Use This vs Other Skills
| Situation | Use |
|---|---|
| "I just cloned this, what is it?" | exploring-codebases (this skill) |
| "Where is the retry logic?" | searching-codebases |
"Find all files matching class.*Error" | searching-codebases |
| "Show me the symbols in auth.py" | tree-sitting directly |
| "Which files are most about CSRF / sessions / queryset filtering?" | bm25 |
| "Rank these docs by relevance to a multi-word concept" | bm25 |
| "Document what this codebase does" | featuring directly |
| "Teach me this codebase" (a human is learning) | orienting-codebases |
| "Get me this repo" — fetch, no analysis | accessing-github-repos, cloning-project |
Exploring is the divergent skill — you don't know what you're looking for yet. Searching is the convergent skill — you know what you want.
orienting-codebases runs the same tree-sitting + featuring pipeline and is
the nearest thing in the catalogue to this skill. The split is the audience:
this one builds Claude's understanding so work can proceed; that one builds
the user's understanding through guided exercises and HTML artifacts. If
nobody is being taught, this is the right skill.
Pairing bm25 with this workflow
Once steps 2–3 have surfaced the rough shape of the repo, bm25 is the
natural complement when you want ranked content search beyond grep
and beyond exact-symbol lookup. It ranks files by lexical relevance to a
multi-word query, which is useful for "what's this codebase actually
about when I search for X?" — particularly when you don't yet know the
symbol name to feed to tree-sitting.
BM25=/mnt/skills/user/bm25/scripts/bm25.py
# Pass multiple queries — index builds once, all queries reuse it
python3 $BM25 /tmp/$REPO 'auth flow' 'session backend' 'middleware pipeline' \
--exclude 'tests/*' --exclude '*/tests/*' --top-k 5
Two patterns that pair especially well:
- bm25 → tree-sitting. Use bm25 to find the top-ranked files for a
concept; then
tree-sitting source:Symbol:path/to/file.pyto read the actual implementation. - bm25 with
--exclude 'tests/*'. Test directories tend to dominate keyword queries because test names redundantly mention domain terms. Excluding them up front lands you on implementation files.
bm25 is corpus-agnostic — it'll also work on project knowledge stores
or uploads/ if your exploration spans docs, transcripts, or PDFs.
Delegating to subagents
Only when the repo is large (>1000 files or several distinct subsystems) and this environment exposes a subagent tool (Agent/Task in Claude Code and CCotw). Claude.ai chat and bare-skill runs have none: run steps 2-4 inline and skip this entirely. Never simulate fan-out by other means when the tool is absent.
Steps 2-3 stay inline either way. Only step 4's judgment work fans out, one agent per subsystem, and a subagent inherits nothing -- not the conversation, not this file, not the knowledge that scan artifacts are already on disk. Read references/subagent-delegation.md before writing the first agent prompt; it carries the four things every prompt must include and what happens when they are missing.
Notes
- Large repos (>100 files): use
--skip tests,vendored,docs,...in step 2 to focus the scan. - Monorepos: treat each package/service as a separate exploration.
Generate per-subsystem
_FEATURES.mdfiles linked from a root index. - Drill heuristics (if step 2 drilling is warranted): directories
with high symbol-to-file ratio (dense logic), entry-point names
(
main,cli,app,server,routes), files with many imports (integration points).
Featuring
Generate _FEATURES.md files — top-down documentation of what a codebase does,
organized by feature/capability, anchored to specific source symbols.
tree-sitting tells you WHAT symbols exist. _FEATURES.md tells you WHY they exist and what they accomplish together.
For large codebases, the root _FEATURES.md decomposes into sub-feature files
linked by capability area — not by folder structure. An agent starts at the root
and is drawn into sub-files only when working on a relevant area.
Dependency
Requires tree-sitting skill. Uses its engine for AST scanning.
uv venv /home/claude/.venv 2>/dev/null
uv pip install tree-sitter-language-pack --python /home/claude/.venv/bin/python
tree-sitting caches its scan to /tmp/treesit-cache, keyed by repo path plus
skip set. That cache persists symbols and imports but NOT file source, so a
cache HIT returns source=None. gather.py re-reads those files from disk;
do not assume entry.source is populated if you write against the engine
directly. (Before this was handled, gather crashed on its second run against a
repo while the first succeeded — diagnosed 2026-08-22.)
For quick structural orientation before running gather.py, use tree-sitting's CLI:
TREESIT=/mnt/skills/user/tree-sitting/scripts/treesit.py
# Complete tree, sparse detail — see the full shape
/home/claude/.venv/bin/python $TREESIT /path/to/repo --depth=-1 --detail=sparse
Workflow: Multi-Pass Synthesis
Feature documentation is built in three passes. The overview is written LAST, after all features are understood — not first.
Pass 1: Orientation (quick scan)
/home/claude/.venv/bin/python /mnt/skills/user/featuring/scripts/gather.py /path/to/repo \
--skip tests,.github,node_modules --source-budget 8000
--orient when you are not writing the file. The full output is a complete
symbol inventory — 5,697 lines on a 71k-line repo — and it exists so a
_FEATURES.md can cite every symbol. When the deliverable is your own
understanding (a review, an orientation read), pass --orient: complexity
assessment, decomposition ranking, directory tree and entry points, and nothing
else. ~115 lines. Reaching for head on the full output means --orient was
the right mode.
Pass 1 of THIS skill is the case that wants the full output — you are about to write the inventory down.
Read the gather output. Before writing anything, form a hypothesis:
"This codebase appears to be a [what it is] that provides [capability A], [capability B], and [capability C]."
Write this down as a DRAFT overview. It will be wrong or incomplete — that's fine. The point is to orient before diving into detail.
How to identify capability areas:
- What can a user/consumer DO with this? (commands, API endpoints, UI actions)
- What problems does it solve? (the WHY behind the code)
- What are the main workflows? (how features compose)
- What are the constraints/invariants? (rules the code enforces)
Pass 2: Detailed feature extraction
For each capability area identified in Pass 1:
- Gather the symbols that implement it (from gather output + targeted
get_source()) - Understand how they collaborate — the workflow
- Identify constraints and invariants
- Write the feature section
During this pass, you'll discover:
- Capabilities you missed in Pass 1
- Features that are more complex than expected (decomposition candidates)
- Features that are simpler than expected (merge candidates)
- Cross-cutting concerns that span multiple capability areas
Hierarchy decision (per feature, during this pass):
| Signal | Action |
|---|---|
| ≤6 key symbols, self-contained | Inline in root _FEATURES.md |
| >6 key symbols OR clear sub-capabilities | Own _FEATURES.md sub-file |
| Spans many files but is ONE capability | Inline (breadth ≠ complexity) |
| Has sub-features that are independently useful | Own sub-file |
| Is infrastructure (logging, DB layer) | Inline briefly, unless it IS the product |
Pass 3: Overview rewrite
NOW — after all features are documented — rewrite the overview. The Pass 1 draft was a hypothesis. Pass 3 replaces it with a proper progressive-disclosure overview that:
- States what the codebase is in one sentence
- Lists the top-level capability areas (3-8 items)
- For each area that has a sub-file: one sentence + link + "read when" guidance
- For inline features: just the list entry (detail is below in the same file)
This is the most important part. The overview IS the entry point for every agent session. It must be accurate, complete, and fast to scan.
_FEATURES.md Format
Root file
# Features: {project-name}
> One-sentence description of what this codebase is and does.
**Capability areas:**
- **[Area A]** — one-sentence summary
- **[Area B]** — one-sentence summary → [details](path/to/_FEATURES.md)
- **[Area C]** — one-sentence summary
## {Inline Feature Name}
{2-3 sentences: what this feature does from a user perspective.}
**Key symbols:**
- `file.py#function_name` — role in this feature
- `file.py#ClassName` — role in this feature
**Workflow:** {How a user exercises this feature or how symbols collaborate.}
**Constraints:** {Invariants, limits, rules.}
---
## {Complex Feature Area}
> One-sentence summary of what this area covers.
This area is documented in detail in [{area-name}/_FEATURES.md]({path}).
Read it when working on {specific trigger — e.g., "the memory retrieval pipeline",
"adding a new API endpoint", "modifying the build system"}.
At a glance, this area provides:
- {sub-capability 1} — one line
- {sub-capability 2} — one line
- {sub-capability 3} — one line
Sub-feature files
Sub-feature files follow the SAME format as the root, recursively. They can contain inline features and further sub-file references. Each sub-file:
- Has its own
# Features: {area-name}header - Has its own overview paragraph
- Is self-contained — an agent reading only this file understands the area
- Links back to the root:
← [Root features](../_FEATURES.md)
Format rules
- Organized by capability, not by file/directory
- Symbol references use
file#symbolnotation (relative to repo root) - Leading paragraph per feature: what a user gets, not implementation details
- Key symbols: the 2-6 most important symbols, with their role explained
- Workflow: how the feature works end-to-end (include when non-obvious)
- Constraints: rules/invariants (include when they exist)
- No source code in _FEATURES.md — it's a map, not a mirror
- "Read when" guidance on every sub-file link — tells agents WHEN to drill in
What makes a good feature entry
Good: "Memory Storage — Persist observations across sessions. Stores typed, tagged memories to a Turso database with BM25 full-text search. Memories have priority levels that affect retrieval ranking."
Bad: "memory.py — Contains remember(), recall(), forget(), and
supersede() functions."
The first tells you WHAT you can do. The second describes file contents — tree-sitting already gives you that.
Hierarchy design principles
The hierarchy is feature-driven, not folder-driven. Folders are natural candidates for decomposition boundaries, but the decision is based on:
- Does this capability area have enough complexity to warrant its own file? (>6 key symbols, multiple sub-workflows, or independently useful sub-features)
- Would an agent working on this area benefit from focused context? (if yes, a sub-file saves them from parsing unrelated features)
- Is this area likely to be read independently of the rest? (if yes, it should be self-contained in its own file)
Counter-examples — do NOT split just because:
- The code lives in a separate folder (folder ≠ feature)
- There are many files (files ≠ complexity)
- A class has many methods (one class = one feature unless methods serve distinct user-facing purposes)
Identifying features
Heuristics for finding feature boundaries:
- Entry points (main, CLI commands, route handlers) often map 1:1 to features
- Public API functions that aren't helpers are usually feature surfaces
- Type hierarchies (class + methods) often represent a cohesive feature
- Config/constants clusters sometimes reveal features (e.g., a group of timeout constants → a retry feature)
- Import clusters — files that import each other heavily are likely co-implementing a feature
Features to SKIP in _FEATURES.md:
- Pure infrastructure (logging, error handling) unless it's the project's purpose
- Internal utilities that only serve other features
- Test code (unless the testing approach IS a feature, e.g., a testing framework)
Keeping _FEATURES.md in Sync
Three mechanisms, layered:
1. Check script (detect drift)
/home/claude/.venv/bin/python /mnt/skills/user/featuring/scripts/check.py /path/to/repo \
[--features _FEATURES.md] [--skip tests,.github]
Parses file#symbol references from ALL _FEATURES.md files (root + sub-files),
resolves them against the live codebase via tree-sitting, and reports:
- Broken refs — symbol deleted or renamed (exit code 1)
- Moved symbols — symbol exists but in a different file than referenced
- Dead features — ALL key symbols in a feature section are gone
- Uncovered symbols — new public API not mentioned in any feature
- Orphan sub-files — sub-feature files not linked from any parent
Exit code 0 = clean, 1 = drift detected. Suitable for CI or pre-commit hooks.
2. Agent instructions (prevent drift)
Add to CLAUDE.md or equivalent:
## Feature Documentation
- `_FEATURES.md` documents what this codebase does, organized by capability.
- Start here when orienting to the codebase. Follow sub-file links as needed.
- After changing behavior (new feature, renamed API, deleted functionality):
run `python featuring/scripts/check.py .` and fix any broken refs.
- After adding a new public API surface: add it to the appropriate feature
section, or create a new feature section if it's a new capability.
- Run check before committing. Broken refs = broken documentation.
3. Targeted regeneration (fix drift)
When check reports broken refs, the fix is usually surgical: update the
file#symbol reference to the new name/location. For dead features (all refs
gone), either delete the section or regenerate it.
Full regeneration (re-running all three passes) is the nuclear option. Prefer targeted updates — they're cheaper and preserve hand-written narrative.
CI Integration
# .github/workflows/features-check.yml
name: Check _FEATURES.md
on: [push, pull_request]
jobs:
check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: astral-sh/setup-uv@v4
- run: uv pip install tree-sitter-language-pack
- run: python featuring/scripts/check.py . --skip tests
Claude Code Integration
In Claude Code, use tree-sitting's CLI or engine directly. The agent should:
- Run
treesit.py /path --depth=-1 --detail=sparsefor full structural overview - Pass 1: Form a hypothesis about what the codebase does
- Run
treesit.py /path --path=DIR --detail=fullfor each capability area - Run
treesit.py /path --no-tree 'source:symbol_name'where intent isn't clear - Pass 2: Write detailed feature sections, deciding hierarchy per-feature
- Pass 3: Rewrite the overview now that all features are documented
Add to CLAUDE.md:
## Codebase Understanding
Read `_FEATURES.md` for top-down feature orientation before modifying code.
Follow links to sub-feature files when working on a specific area.
Use tree-sitting MCP tools for structural queries (symbol lookup, source retrieval).
After adding new features or changing behavior, update the relevant _FEATURES.md.
Example: Small Codebase (flat)
A CLI tool with 15 public symbols → single _FEATURES.md, all features inline.
No sub-files needed.
Example: Large Codebase (hierarchical)
The remembering skill (memory system for an AI agent) has ~60 public symbols
across 8 files. Hierarchical decomposition:
_FEATURES.md (root — overview + 3 inline features + 3 sub-file refs)
├── scripts/_FEATURES.md (memory operations — storage, retrieval, lifecycle, maintenance)
└── utils/_FEATURES.md (utility modules — therapy, reminders, blog publishing)
Root _FEATURES.md would contain:
- Overview: "Persistent memory system for Muninn. Stores, retrieves, and maintains typed memories across sessions via Turso."
- Inline: Boot Sequence, Configuration, Task Tracking (simple, ≤4 symbols each)
- Sub-file ref: Memory Operations →
scripts/_FEATURES.md("Read when working on storage, retrieval, or memory lifecycle") - Sub-file ref: Utility Modules →
utils/_FEATURES.md("Read when working on therapy sessions, reminders, or blog publishing")
Relationship to Other Skills
| Skill | What it provides | Drift detection |
|---|---|---|
| tree-sitting | Structural inventory (symbols, signatures) | N/A (live queries) |
| featuring | Feature documentation (what/why), hierarchical | check.py — docs → code |
| generating-lattice | Bidirectional knowledge graph | lat check — docs ↔ code |
| mapping-webapp | Web app behavioral docs (pages, flows) | None |
featuring's check is lighter than lattice's: no source code annotations needed,
no @lat: comments, just reference resolution. The trade-off is that new code
without docs is only flagged as "uncovered symbols" — it's advisory, not
enforced. Use lattice when you need strict bidirectional traceability; use
featuring when you need good-enough orientation docs that catch renames and
deletions.
Hunting failing inputs
A trap is an operation with a precondition the input can break: an index in range, a slice end within the length, a non-zero divisor, a sum that must not wrap.
Not for
| Situation | Use instead |
|---|---|
| Races, deadlocks, async ordering | race detector or stress test |
| Whole programs, I/O, network, UI | fuzzing plus sanitizers; extract the pure core first |
| Wrong results no precondition expresses | building-property-tests, or reasoning-semiformally |
| Whether a test can go red | gating |
| Validating or minifying WGSL | compiling-wgsl |
Stop and report a trap as unmodelled (never as safe) when its model needs
more than about 15 unrolled loop iterations, needs heap state that a single
input cannot build, or returns unknown twice.
Setup
python3 -m pip install z3-solver tree-sitter-language-pack
SKILL=/mnt/skills/user/hunting-failing-inputs
python3 $SKILL/scripts/selftest.py # optional: SKIP means a missing toolchain, not a pass
Procedure
-
List the traps.
python3 $SKILL/scripts/list_traps.py FILE... [--func NAME]printsfile:line:col kind on-failure func source.on-failureisraises,silentorUB(C, which is silent without sanitizers). Model thesilentandUBtraps first. Strike any trap that an earlier guard already makes safe, and in JS strike object lookups. For Go, usebce_targets.pyinstead (seereferences/go.md). -
Read
references/<lang>.mdfor the target's language:python,javascript,c,wgslorgo. Each one has the failure semantics, the predicate to model each trap with, the strict harness, and a runnable example inexamples/<lang>/. -
Model one pure function. Include the guards its callers enforce as constraints. Without them, Z3 invents inputs the program can never produce.
-
Write the model from
scripts/z3traps.py, copying the nearestexamples/<lang>/model*.py:import sys; sys.path.insert(0, f'{SKILL}/scripts') from z3traps import * n, base = harness(max_len=64) b0 = byte_at('b0') base += [n >= 2] # every early return the path got past solve_traps(base, {'f.py:10 b[k:k+2]': slice_truncates(k, k + 2, n)}, show=(n, b0))- Do arithmetic at the width the language uses, and
widenexactly where the source converts. Python ints never wrap. C narrows on a store or a cast, JS|0truncates to 32 bits, and WGSLu32and Gouint8wrap. - Write each guard the way the source writes it, including its overflow. A guard written the way it was meant models the fixed code.
- Use the precondition the runtime actually checks. Go checks slices
against
cap. Python wraps silently only for-len <= i < 0. - Use
in_order=Truewhen the traps are on one straight-line path, and leave it off when they are on different branches. - For loops, try concrete lengths
L = 1, 2, …with symbolic bytes, and stop at the firstsat. - z3py's
<and>=on bit-vectors are signed. For unsigned values, widen first or useULT/UGE.
- Do arithmetic at the width the language uses, and
-
Replay each
satinside the strict harness.literal(bytes, lang)renders the input for a test. Use the harness for the language:language strict harness Python parse(strict(data)),scripts/strict.pyJS / TS decode(strict(u8)),scripts/strict.mjsC -fsanitize=address,undefined -fno-sanitize-recover=all, input in an exact-sizemallocWGSL scripts/wgsl_guard.pycounts bad indexes in an extra_oobbufferGo d = d[:len(d):len(d)]Then read the result:
Z3 replay meaning satfails at the trap's line A bug. Report it with the reproducer. satfails at an earlier line Re-solve with in_order=True.satdoesn't fail, or fails differently The model is wrong. Fix it, and never report this as a bug. unsat— "None within len ≤ N", not "safe". unknown— Simplify the model. Never count it as unsat. -
Fix, and keep the harness. Patch the code, update the model and expect
unsat, and keep the reproducer as a regression test. Add the strict harness to the project's existing fuzz targets and property tests.
Verification
Every trap you didn't strike ends as one of:
- a reproducer that fails at that trap inside the strict harness
unsatwith a stated bound, plus a negative control that wentsat- unmodelled, with the reason
For the negative control, remove one guard or widen one field and expect
sat. If the model stays unsat, it is over-constrained and its unsat
means nothing.
Failure modes
- A
satinput doesn't fail as predicted. The model's precondition is wrong. On 2026-11-13, a Python model treated every negative index as a silent wrap, and its inputb'\x00\xc0'raisedIndexErrorinstead. - A later trap's
satinput fails at an earlier line. Usein_order=True. On 2026-11-13, the Go line-16 input panicked at line 14. - Every trap is
unsat, including the buggy ones. A guard was modelled with wide arithmetic where the source uses narrow. Run the negative control. - The strict harness passes, but Z3 says
sat. The wrapper covers only the object you wrapped. Buffers the function builds itself are unwrapped. - Random testing finds nothing, even when strict. Check the random source. On 2026-11-13, a JS LCG that lost precision past 2^53 never hit the bug.
- clang fails to link ASan or libFuzzer.
libclang-rt-<N>-devis missing. Install it, or use gcc.
Mapping Codebases (deprecated)
Use tree-sitting instead.
Why
This skill wrote _MAP.md files to disk — a persisted symbol inventory per
directory, generated once and read many times. That tradeoff made sense when
scanning was expensive. It isn't: tree-sitting parses a 250-file repo in about
700ms and answers queries against the in-memory AST in under a millisecond.
A persisted map costs what a runtime scan does not — it goes stale, it needs regenerating, it gets committed, and it must be excluded from every other tool that walks the tree. Nothing was gained for that.
Replacement commands
TREESIT=/mnt/skills/user/tree-sitting/scripts/treesit.py
# Was: codemap.py /path/to/repo → root orientation
python3 $TREESIT /path/to/repo
# Was: reading every _MAP.md in the tree → full inventory
python3 $TREESIT /path/to/repo --depth=-1 --detail=sparse
# Was: grepping _MAP.md for a symbol → direct lookup
python3 $TREESIT /path/to/repo --no-tree 'find:parse_input'
The archived version
The last working release is
mapping-codebases-v0.8.0
(2026-03-31). It carries scripts/codemap.py and the eleven bundled
parsers/*.so grammars. The release is the snapshot; nothing in this directory
reproduces it.
Note that v0.8.0 ships a latent bug: codemap.py:1216 calls an unimported
get_parser() inside a try swallowed by a bare except Exception, so HTML
inline-JavaScript symbol extraction silently returned nothing. It will not be
fixed.
Mapping Webapp
Generate _FEATURES.md files documenting what a web app does — screens, flows, states, behavioral invariants. Companion to tree-sitting, which surfaces code structure.
v0.3.0: Code-first architecture. The code IS the ground truth; screenshots are supplementary verification.
Prerequisites
- tree-sitting must be installed (structure is scanned at runtime)
- Claude API key available (via
api-credentialsskill orANTHROPIC_API_KEYenv var) - Optional: webctl for visual verification (not required for
--code-only)
Usage
# Code-only analysis (no browser needed):
python /mnt/skills/user/mapping-webapp/scripts/featuremap.py \
--app-url https://example.com --codebase /path/to/repo --code-only
# Full pipeline (code analysis + selective visual verification):
python /mnt/skills/user/mapping-webapp/scripts/featuremap.py \
--app-url https://example.com --codebase /path/to/repo
# Incremental update:
python /mnt/skills/user/mapping-webapp/scripts/featuremap.py \
--app-url https://example.com --codebase . --incremental
Options
| Flag | Default | Description |
|---|---|---|
--app-url | required | Base URL of the web app |
--codebase | required | Path to repo root |
--output | <codebase>/_FEATURES.md | Output path |
--max-pages | 100 | Cap on pages to discover |
--code-only | false | Skip all vision — code analysis only |
--verify-only | false | Only run vision on already-analyzed pages |
--batch-size | auto | Pages per batch (auto-detected from environment) |
--incremental | false | Only re-process changed pages |
--viewport | 1280x720 | Screenshot viewport (WxH) |
--routes | none | Comma-separated routes or path to routes file |
--screenshots-dir | <codebase>/screenshots | Where to store PNGs |
--model | claude-sonnet-5-5 (set in scripts/featuremap.py; that file is the source of truth) | Claude model for analysis/vision |
--dry-run / -n | false | Discover only, print sitemap |
Architecture: Code-First Pipeline
Phase 1: DISCOVER
Discovers pages from code structure, not browser crawling:
- Scans for HTML files (static sites)
- Detects framework routing conventions (Next.js, SvelteKit, etc.)
- Scans the codebase for page references
- Supplements with
--routesfor manual seeding
No browser required for discovery.
Phase 2: ANALYZE
Reads source code for each discovered page and uses Claude API (text, not vision) to generate behavioral descriptions:
- Finds relevant source files (HTML + referenced JS/CSS)
- Includes tree-sitting excerpts for code context
- Produces: what the user sees, interactions, invariants, code references
Code-derived descriptions are usable standalone. Vision is enrichment, not requirement.
Phase 3: VERIFY (optional)
Selective visual verification for pages where it adds value:
- Skips error pages (404, 500), gated pages, redirects
- Captures screenshots + accessibility trees via webctl
- Sends to Claude vision API to verify/enrich code descriptions
- Falls back to code description if vision fails
Skipped entirely with --code-only. Run only this phase with --verify-only.
Phase 4: ASSEMBLE
Compiles all descriptions into _FEATURES.md:
- Source badges indicate code-analyzed vs visually-verified
- Screenshot references only for verified pages
- Status summary with breakdown by source
Environment-Adaptive Batching
The skill auto-detects the runtime environment and adjusts batch size:
| Environment | Batch Size | Notes |
|---|---|---|
| Claude.ai container | 4 pages | Short bash timeouts |
| Claude Code on Web | 12 pages | Longer execution windows |
| Local CLI | Unbatched | Full control |
Override with --batch-size N.
Progress is checkpointed after each batch via _FEATURES_MANIFEST.json, so work survives if a conversation ends mid-pipeline.
Incremental Mode
Each run stores page hashes and descriptions in _FEATURES_MANIFEST.json. With --incremental:
- Code analysis: skips pages with existing descriptions
- Visual verification: skips pages with unchanged screenshots
- Descriptions from previous runs are preserved and merged
Auth / Gated Pages
Pages requiring authentication are detected during verification (redirect detection + text heuristics) and marked GATED. The skill generates step-by-step manual capture instructions in GATED_PAGES.md.
Output Format
# _FEATURES.md — App Name
Generated: 2026-03-22T12:00:00+0000
App URL: https://example.com
## Feature Inventory
### Status Summary
- **Documented:** 45 pages
- Code-analyzed: 40
- Visually verified: 5
- **Gated (auth required):** 2 pages
### Page Title (`/route`)
> *Derived from source code analysis*
**What the user sees:** Prose description from code analysis.
**Interactions:**
- Button "X" → does Y
**Invariants:**
- Rule 1
**Code:** `src/page.html` :1
---
Relationship to CLAUDE.md
_FEATURES.md is the behavioral source of truth. Structure is not persisted
alongside it — it is derived on demand:
tree-sitting→ structure, scanned at runtimemapping-webapp→_FEATURES.md(behavioral)- Merge the behavioral layer into CLAUDE.md architecture/concepts sections
Limitations
- Code analysis requires Claude API calls (tokens)
- Visual verification requires webctl + a running app instance
- SPAs with client-side routing may need
--routesflag - Auth-gated pages require human intervention for visual verification
- Code analysis quality depends on source code readability
Orienting Codebases
Interactive codebase orientation for the human, not the agent. Same tree-sitting + featuring pipeline as exploring-codebases, but synthesizes into guided HTML exercises via composing-html instead of analysis documents. See README.md for design rationale.
Pipeline
0. Setup (once per session)
uv venv /home/claude/.venv 2>/dev/null
uv pip install tree-sitter-language-pack --python /home/claude/.venv/bin/python
export PYTHON=/home/claude/.venv/bin/python
export TREESIT=/mnt/skills/user/tree-sitting/scripts/treesit.py
export GATHER=/mnt/skills/user/featuring/scripts/gather.py
export COMPOSE=/mnt/skills/user/composing-html/scripts/build.py
1. Get the repo
OWNER=... REPO=... REF=main
curl -sL -H "Authorization: Bearer $GH_TOKEN" \
"https://api.github.com/repos/$OWNER/$REPO/tarball/$REF" -o /tmp/$REPO.tar.gz
mkdir -p /tmp/$REPO && tar -xzf /tmp/$REPO.tar.gz -C /tmp/$REPO --strip-components=1
For local repos, skip the curl — point directly at the path.
2. Structural scan
$PYTHON $TREESIT /tmp/$REPO --stats
3. Feature gathering
$PYTHON $GATHER /tmp/$REPO \
--skip tests,.github,node_modules --source-budget 8000
4. Targeted source extraction
For each exercise target identified from gather output, extract the actual source using treesit queries:
# Entry point source
$PYTHON $TREESIT /tmp/$REPO --no-tree 'source:main'
# Specific function for an exercise
$PYTHON $TREESIT /tmp/$REPO --no-tree 'source:validate_token'
# Imports for a hub file
$PYTHON $TREESIT /tmp/$REPO --no-tree 'imports:src/api.py'
This source feeds directly into the HTML artifact — the user sees real code, syntax-highlighted, without having to navigate the repo.
Do not show raw pipeline output to the user. It's material for exercise design. The user sees HTML artifacts and conversation.
Orientation session
After the pipeline steps, synthesize into an interactive orientation. Three phases.
Phase A: Framing (1 message, no artifact)
Summarize the repo in ONE sentence (what it does, who it's for). Then:
I can walk you through a hands-on orientation — about 15 minutes, two exercises that'll give you a working mental model of this codebase. Want to try it?
Do not start exercises without confirmation.
Phase B: Exercises (2 exercises, interactive)
For each exercise, generate an HTML artifact using composing-html's
freeform template, then continue the conversation around it.
Artifact structure per exercise
Build a spec with body_html containing:
<section class="stack">
<div class="eyebrow">EXERCISE 1 OF 2</div>
<h2>[Exercise title]</h2>
<div class="card">
<div class="eyebrow">CONTEXT</div>
<p>[Brief explanation of what this code does in the system
and why it matters for orientation.]</p>
</div>
<div class="card">
<div class="eyebrow">CODE</div>
<pre><code>[Actual source extracted by treesit — entry point,
function, config, imports, or test names. Escaped properly.]</code></pre>
</div>
<details class="card">
<summary>
<span class="badge badge--clay">Your turn</span>
[Specific comprehension/synthesis question]
</summary>
<div style="margin-top:1rem">
<div class="eyebrow">KEY POINTS</div>
<p>[Pre-generated feedback covering what the code reveals about
the system's architecture, design decisions, or workflow.
This is the "answer key" — hidden until clicked.]</p>
</div>
</details>
</section>
Answers live inside <details> — the DOM hides them until the user
clicks. Do not preview or summarize the key points in chat after
presenting the artifact; that defeats the exercise.
Build and present the artifact:
python3 $COMPOSE build freeform --spec /tmp/exercise_N.json --out /tmp/exercise_N.html
Two interaction modes
After presenting the artifact, tell the user:
Take a look at the code and the question. You can either:
- Tell me your answer in chat and I'll give you specific feedback
- Click to reveal the key points in the artifact when you're ready
If they respond in chat: give personalized feedback based on what they actually said — confirm what's right, be specific about gaps, explore misconceptions. This is pedagogically richer than pre-canned feedback.
If they click through: that's fine too — the artifact's hidden feedback covers the essential points. Move to the next exercise.
Exercise design from pipeline signals
Each exercise type maps to specific pipeline output:
Entry-point walkthrough — gather found clear entry points: Show the main function/handler source. Ask what the program does on startup and what the 2-3 most important operations are.
Architecture synthesis — treesit --stats shows clear directory structure: Show the directory tree with file counts and symbol density. Ask what the system's main components are and how they relate.
Dependency detective — gather found import clusters: Show a hub file's imports. Ask what the import list reveals about the file's role — integration point, orchestrator, leaf node?
Config reader — manifest/config files are rich: Show the config file. Ask which 2-3 settings they'd change first for a new project and why.
Test-as-spec — test files present and readable: Show test names (not bodies). Ask what the tests tell them about what the module is supposed to do.
Phase C: Synthesis (1 message after exercises)
After both exercises, ask in chat (no artifact needed):
What's one thing about this codebase that surprised you, or that you want to dig into further?
Use their answer to either:
- Point them to a specific file or symbol for independent exploration
- Offer a targeted follow-up exercise — but only if they want more
Producing orientation.html (optional)
If the user asks for a persistent orientation document, or if the session produced insights worth preserving, generate a standalone HTML artifact that any teammate can open in a browser without tooling.
Build via composing-html freeform with this body structure:
<section class="stack">
<div class="card">
<div class="eyebrow">PURPOSE</div>
<p>[One-line: what this repo does and why it exists.]</p>
</div>
<div class="card">
<div class="eyebrow">LANGUAGES</div>
<p>[From treesit --stats.]</p>
</div>
<h2 class="rule">Key files</h2>
<div class="grid grid--2">
[For each of 6-10 key files from gather's density ranking:]
<div class="card card--soft">
<code>[path/to/file]</code>
<p>[What it does — why a new developer should read it.]</p>
</div>
</div>
<h2 class="rule">Core concepts</h2>
[For each of 3-5 concepts:]
<details class="card">
<summary><strong>[Concept name]</strong> — [one-line summary]</summary>
<p>[Where it lives in the code. Why it matters.]</p>
</details>
<h2 class="rule">Orientation exercises</h2>
<p>Two exercises to build a working mental model. Read the code,
answer the question, then click to check your understanding.</p>
[Exercise 1 — same card+details structure as Phase B artifacts]
[Exercise 2 — same structure]
</section>
Spec keys:
{
"title": "Orientation: [repo name]",
"eyebrow": "CODEBASE ORIENTATION",
"subtitle": "[one-line purpose]",
"show_masthead": true,
"page_class": "page page--narrow",
"body_html": "..."
}
Build and present:
python3 $COMPOSE build freeform --spec /tmp/orientation_spec.json \
--out /mnt/user-data/outputs/orientation.html
Feedback and scaffolding
Feedback after chat responses
When the user responds in chat (rather than clicking the reveal):
- If correct: confirm briefly, then extend ("Right — and that connects to [next concept] because...")
- If partially correct: acknowledge what's right, be specific about what's missing, explore the gap
- If wrong: say so directly without softening, then walk through the actual behavior together
- Do not attribute understanding the user didn't demonstrate. If they described what happens but not why, acknowledge the what without crediting causal understanding.
Fading scaffolding
Adjust the amount of code shown and question specificity based on demonstrated familiarity — but always keep the answer as the user's responsibility.
| Level | Artifact shows | Question asks | Use when |
|---|---|---|---|
| High | Full function source, line numbers, file path | "What does this function check?" | First exercise, unfamiliar language |
| Medium | Function signature + key lines only | "What's the validation logic here?" | Second exercise, or user nailed the first |
| Low | File path only, no source in artifact | "Where would you look to change how auth works?" | Follow-up if user wants more |
Fading adjusts the difficulty of finding and reading the code, not explaining it. At every level the user still produces the synthesis.
If the user struggles, move UP the ladder (show more code, be more specific), not sideways (hint at the answer).
When to use this vs. other skills
| Situation | Use |
|---|---|
| "I just cloned this, what is it?" (Claude needs to understand) | exploring-codebases |
| "Help me understand this codebase" (user needs to understand) | orienting-codebases (this skill) |
| "Where is the retry logic?" | searching-codebases |
| "I want to set a learning goal" | learning-goal |
| "Help me learn [specific concept] from my code" | learning-opportunities (if installed) |
This skill is the orientation layer — first-encounter mental model building. For ongoing learning during development (exercises after commits, retrieval check-ins, prediction drills), pair with learning-opportunities from DrCatHicks/learning-opportunities.
python-lsp
A thin, dependency-free Python client that owns the LSP lifecycle against
pyright-langserver --stdio and exposes high-value semantic queries.
Why, over tree-sitter / ripgrep: tree-sitter gives a CST — structural queries, call-site enumeration by name. It cannot do name resolution, type inference, or cross-file binding. ripgrep matches text, so it false-positives on shadowed / same-named symbols. pyright resolves bindings. This client is that semantic overlay.
Setup (self-installing)
The client bootstraps pyright on first use. Run the bootstrap explicitly, or
let LSPClient do it via ensure_pyright():
sh /mnt/skills/user/python-lsp/scripts/bootstrap.sh
# or, equivalently, the one-liner it wraps:
command -v pyright-langserver >/dev/null || uv tool install pyright
pyright wheels vendor the langserver JS bundle and run it on system node —
no npm install, no separate fetch when node is present. Measured cold (caches
wiped): uv tool install pyright ~0.7s, first working server ~1.8s total; warm
sub-second.
Node prerequisite. The clean path assumes system node (v18+) is present.
With no node, pyright-python falls back to downloading node from nodejs.org,
which may be blocked in locked-down containers. The bootstrap detects node and
fails loudly (exit 1, clear message) rather than hanging.
Usage: CLI
LSP=/mnt/skills/user/python-lsp/scripts/lsp_client.py
python3 $LSP bootstrap # ensure pyright installed
python3 $LSP <root> definition <file> <line> <col>
python3 $LSP <root> references <file> <line> <col>
python3 $LSP <root> hover <file> <line> <col>
python3 $LSP <root> diagnostics <file>
python3 $LSP <root> symbols <file> # documentSymbol outline
python3 $LSP <root> wsymbols <query> # workspace/symbol search
Positions are zero-based line/character (LSP spec). <file> is relative to
<root> or absolute.
Usage: library
The scripts/ module lands on the boot .pth, so it is importable directly.
import sys; sys.path.insert(0, "/mnt/skills/user/python-lsp/scripts")
from lsp_client import LSPClient
with LSPClient("/path/to/repo") as c: # context manager reaps the subprocess
c.open_all("pkg/service.py", "pkg/models.py")
c.wait_for_index() # REQUIRED before querying — see below
defs = c.definition("pkg/service.py", 4, 8) # -> [Location], follows imports
refs = c.references("pkg/models.py", 8, 4) # -> [Location], binding-resolved
typ = c.hover("pkg/service.py", 4, 4) # -> "(variable) u: User"
diags = c.diagnostics("pkg/bad.py") # -> [diagnostic dicts]
outln = c.document_symbols("pkg/models.py") # -> [SymbolInfo], file outline
hits = c.workspace_symbols("User") # -> [SymbolInfo], project-wide
Location has .path, .start_line, .start_char, .end_line, .end_char
(all zero-based) and .as_dict(). Convert 1-based UI input with
Position.from_one_based(line, col).
The root you pass is split into two roles. Relative <file> arguments resolve
against it (call that the scope), but pyright is rooted at the enclosing
project root — by default LSPClient climbs out of any package the scope
sits inside (every ancestor with an __init__.py) via find_project_root. This
is what makes a query scoped to a sub-package (scipy/optimize) still resolve
the project's own absolute imports (from scipy.optimize._x import Y); without
it, references silently undercount — same blindness as a text grep, opposite
direction. The promotion is announced on stderr. Pass auto_root=False to pin
pyright at the scope verbatim.
Methods
| Method | Returns | Notes |
|---|---|---|
definition(file, line, col) | list[Location] | Go-to-definition across files/imports. |
references(file, line, col) | list[Location] | Binding-resolved — the win over ripgrep. Excludes same-named, unrelated symbols. |
hover(file, line, col) | str | None | Inferred type / signature string. |
diagnostics(file) | list[dict] | pyright type/error diagnostics for the file. |
document_symbols(file) | list[SymbolInfo] | One file's outline (classes/functions/methods); nesting via .container. |
workspace_symbols(query) | list[SymbolInfo] | Project-wide fuzzy symbol search. Empty query = every symbol (expensive). |
SymbolInfo has .name, .kind (int), .kind_name (e.g. "Class"), .location (a Location), .container, and .as_dict().
The lifecycle gotchas (the parts that bite)
- Wait for indexing before querying. Querying mid-index returns empty
results — the most common silent failure.
wait_for_index()blocks on pyright's$/progressbegin/end cycle (with a diagnostics-arrival fallback). Always call it afterdid_open/open_alland before any query. - Don't advertise
workspace.configurationorworkspace.workspaceFolders. If the client claims either capability, pyright defers all analysis until the corresponding negotiation completes — the server starts its service instance and then goes silent (no diagnostics, no progress, queries hang).start()advertises neither, so pyright uses its defaults and analyzes open files immediately — nodidChangeConfigurationnudge needed. Relevant if you reimplement the lifecycle or add capabilities. (Bisected against the fixture;workspace.symbolis safe to advertise.) - Reap the subprocess. Use the context manager (or call
stop()) so sessions don't leakpyright-langserverprocesses.stop()sendsshutdown+exit, then waits/terminates/kills as needed. - Open the files you query. Queries auto-
did_opentheir target file, but for cross-filereferencesopen all relevant files first so pyright has built their models. - Root at the project, not the sub-package. pyright resolves absolute
intra-project imports only when rooted where the top-level package is
importable. Rooted at a sub-package, those imports fail and references
undercount with no error.
LSPClientauto-detects this (climbs out of the enclosing package; seefind_project_root) and prints the promotion to stderr;auto_root=Falseopts out. This was a live silent-undercount bug:--refs ScalarFunctionoverscipy/optimizereturned 3 references rooted at the sub-package vs 30 rooted at the project root.
Tests
cd /mnt/skills/user/python-lsp
python3 -m pytest tests/test_lsp_client.py -v
Round-trips against tests/fixture/ (a small multi-file package): definition
follows an import, references excludes an unrelated same-named symbol, hover
returns an inferred type, diagnostics flags an intentional type error, the
indexing-wait is verified deterministic, and subprocess cleanup is checked for
orphans.
Semi-Formal Code Reasoning
Structured certificate templates that force mandatory checkpoints before conclusions.
Skip Conditions
Do NOT apply semi-formal reasoning when:
- The change is trivial: docs, formatting, version bumps, config changes
- The bug is locally obvious: typo, off-by-one in the same function, missing comma
- No execution paths cross scope boundaries
- The task is not code analysis (text editing, data extraction, summarization)
If any skip condition is met, proceed with standard reasoning.
Model-Specific Instructions
If you are Haiku-class (Haiku 4.5, Haiku 5.5):
Read haiku.md in this skill directory. It contains full procedural templates with worked examples.
If you are Sonnet-class or above (Sonnet 5, Sonnet 5.5, Opus, Fable):
Read sonnet.md in this skill directory. It contains compact verification checkpoints.
Composing Tasks
For complex tasks, apply templates sequentially:
- Fault localization to find the bug
- Patch verification to validate a proposed fix
- Patch equivalence to compare alternative fixes
Each output feeds the next as premises.
Searching Codebases
Find code in any codebase by pattern or concept. One entry point, two search strategies, automatic routing.
When NOT to use this skill
Python callers and definitions only. Every other code question is cheaper elsewhere, and the measurement below is why this skill is edge-case-only.
| Situation | Use |
|---|---|
| What symbols does this file contain? | tree-sitting |
| Where is X defined, so I can read it? | tree-sitting |
| Any structure question, any language | tree-sitting |
| A literal string or regex | plain ripgrep |
| Which files are most about a concept? | bm25 |
| First look at an unfamiliar repo | exploring-codebases |
Non-Python code has no pyright binding resolution to offer, so there is no version of this skill that applies to it.
Prerequisites
uv tool install ripgrep
tree-sitting installs automatically when needed — for --expand context
expansion and for the binding-resolved --refs/--def/--hover tier, which
uses it to resolve symbol positions. Only the bare tree-sitter package is
fetched; the language grammars ship bundled.
Primary Command
SKILL_DIR=/mnt/skills/user/searching-codebases
python3 $SKILL_DIR/scripts/search.py SOURCE "query1" ["query2" ...] [OPTIONS]
SOURCE is any of:
- Local directory path
- GitHub URL (downloads tarball automatically)
uploads(uses/mnt/user-data/uploads/)project(uses/mnt/project/)- Path to a
.zipor.tar.gzarchive
Search Modes
Regex mode (patterns, identifiers, literal text):
python3 $SKILL_DIR/scripts/search.py ./repo "def handle_error"
python3 $SKILL_DIR/scripts/search.py ./repo "class.*Exception" --regex
python3 $SKILL_DIR/scripts/search.py ./repo "TODO|FIXME|HACK"
Semantic mode (concepts, natural language):
python3 $SKILL_DIR/scripts/search.py ./repo "retry logic with backoff" --semantic
python3 $SKILL_DIR/scripts/search.py ./repo "authentication flow"
python3 $SKILL_DIR/scripts/search.py ./repo "error handling strategy"
Auto-detection: short queries and code-like tokens → regex. Multi-word
natural language → semantic. Override with --regex or --semantic.
Binding-resolved mode (Python only — pyright via the python-lsp skill):
python3 $SKILL_DIR/scripts/search.py ./repo --refs SYMBOL # find all real uses
python3 $SKILL_DIR/scripts/search.py ./repo --def SYMBOL # go-to-definition
python3 $SKILL_DIR/scripts/search.py ./repo --hover SYMBOL # inferred type/signature
Regex mode matches text, so a cross-reference for a function false-positives
on shadowed and same-named-but-unrelated symbols. --refs is binding-resolved:
pyright excludes the unrelated same-named symbol and follows imports. Use it when
you need a true "find all callers/users" for a .py symbol, not a text grep.
The tier is engaged lazily — pyright's index cost is paid only when you ask
for --refs/--def/--hover, never on ordinary searches. It is Python-only;
for non-.py sources, or when pyright/node is unavailable, it prints a one-line
degradation note and falls back to the regex text path. Each takes a single bare
symbol name and is mutually exclusive with the other two and with text queries.
Options
--regex/--semantic: Force search mode--refs SYMBOL/--def SYMBOL/--hover SYMBOL: Binding-resolved Python queries via pyright (see Binding-resolved mode above)--expand: Return full function bodies via tree-sitting AST context--benchmark: Compare indexed regex vs brute-force ripgrep--branch NAME: Git branch for GitHub URLs (default: main)--skip DIRS: Comma-separated directories to skip--json: Machine-readable output-v: Show index stats and query routing decisions
How It Works
Regex search builds a sparse n-gram inverted index over all files. Queries are decomposed into literal fragments, looked up in the index to identify candidate files (typically 90-99% reduction), then verified with ripgrep. Frequency-weighted n-grams make rare character sequences more selective.
Semantic search builds a TF-IDF index over code chunks (functions, classes, structural entries). Queries are ranked by cosine similarity.
Context expansion (--expand) uses tree-sitting's AST cache to
identify function/class boundaries, returning complete structural units
rather than line fragments. On first use, tree-sitting scans the repo
(~700ms for 250 files); subsequent expansions are sub-millisecond.
Small codebases (< 20 files) skip indexing entirely — direct ripgrep is faster when there's nothing to narrow.
Mixed Queries
Multiple queries can use different modes in a single invocation. Each query is auto-routed independently, and indexes are built once per mode:
python3 $SKILL_DIR/scripts/search.py ./repo \
"class.*Error" \
"error recovery strategy" \
"def retry"
Dependencies
- tree-sitting: Provides AST context expansion for
--expandand the symbol→position resolution that seeds the binding-resolved tier (--refs/--def/--hover). Auto-installs the baretree-sitterpackage when either is used (grammars are bundled). Regex and semantic search work without it. - ripgrep: Required for regex verification. Install via
uv tool install ripgrep. - scikit-learn: Required for semantic mode. Installs automatically.
- python-lsp: Provides the binding-resolved tier (
--refs/--def/--hover). Self-bootstraps pyright on first use and requires systemnode(v18+). Not required — without it those flags degrade to the regex text path.
When to Use — narrow, by design
The ONE recommended use: binding-resolved Python symbol queries.
- "find all callers of
X" / "where isXreally defined" for a.pysymbol, when same-named-but-unrelated symbols would pollute a text grep. Empirical basis:rg geton psf/requests returned 232 hits, 224 of them false;--refs getexcluded all 224 (2026-06-15).
When NOT to Use — which is most of the time
Everything else. Measured head-to-head on real issue-localization tasks (7 scikit-learn issues with merged fix-PRs, gold = PR diff files, 2026-07-04, replicating the file-discovery metric of arXiv:2602.11988):
- Literal tokens / identifiers: naive
rg -ltied or beat the indexed tier on recall@10 in every instance, at 0.4s vs 25s. - Concept / natural-language search: the TF-IDF semantic tier never beat identifier grep — not even on identifier-poor issues, which are themselves rare (~0.3% of merged-PR traffic in the sample).
- First encounter / "what is this repo": use exploring-codebases.
- Repos under ~20 files: read them.
The self-test before invoking: would plain rg return the same answer?
If yes, use rg. The indexed-regex and semantic tiers are retained for
completeness and for corpora where they may yet earn their cost (very
large repos, non-code document collections), but they carry the burden
of proof.
Files
scripts/search.py— Entry point, query routing, output formattingscripts/resolve.py— Input source resolution (GitHub, uploads, archives)scripts/context.py— tree-sitting-based AST context expansionscripts/ngram_index.py— Sparse n-gram inverted index, regex decompositionscripts/sparse_ngrams.py— Core n-gram algorithms, frequency weightsscripts/code_rag.py— TF-IDF semantic search over code chunksscripts/lsp_refs.py— Binding-resolved Python tier: symbol→position resolution (tree-sitting), pyright queries (python-lsp), soft fallback
Semantic Grep
jina-grep-style semantic search, done in-process via Python rather than as an external CLI. Embeds query + corpus chunks with gemini-embedding-2, ranks by cosine similarity, returns grep-format output.
When Semantic Search Helps
The core trade-off (lifted from jina-grep-cli's own docs and validated in testing):
| Task | Tool |
|---|---|
| Known exact string, filename, or regex | grep / rg / searching-codebases |
| "What files discuss concept X" when X may not appear verbatim | semantic-grep |
| Hybrid: prefilter with grep, rerank by concept | grep → rerank_candidates() |
Regression test result (workshop session corpus, 135 docs):
- "handling regulatory constraints" → top hit "Engineering AI Systems Under Sovereignty Constraints" (0.67). ✓
- "sessions about GEPA" → top hit "Gemma, DeepMind's Family of Open Models" (0.69). ✗ — false positive on phonetic neighbor. GEPA is mentioned verbatim in one session description; grep would find it correctly.
Rule: when the user query reads like a named entity or keyword, try grep first. Only reach for semantic-grep when paraphrase/concept matching is actually needed.
Setup
Credentials via proxy.env (Cloudflare AI Gateway w/ BYOK — same pattern as invoking-gemini):
CF_ACCOUNT_ID=...
CF_GATEWAY_ID=...
CF_API_TOKEN=...
Direct-API fallback: GOOGLE_API_KEY or GEMINI_API_KEY env var. No dependencies beyond requests + numpy.
Quick Start
import sys
sys.path.insert(0, '/mnt/skills/user/semantic-grep/scripts')
from semantic_grep import semantic_grep, format_grep
# Directory of .txt files
results = semantic_grep("error handling under load", "/path/to/notes",
top_k=5, granularity="paragraph")
print(format_grep(results))
# notes/incidents.txt:42: When the queue depth exceeds... [0.71]
# notes/postmortem.txt:8: Under sustained traffic we saw... [0.68]
Core API
semantic_grep(query, corpus, *, top_k=10, threshold=None, ...)
Main search function.
query(str) — the search query (embedded withRETRIEVAL_QUERYtask type)corpus(str | Path | list[Chunk]) — a file, directory, or pre-chunked listtop_k(int | None) — max results;None= all above thresholdthreshold(float | None) — cosine similarity cutoff;None= no filter (top_k only)granularity("paragraph" | "line") — how to chunk files (default paragraph)include(str) — filename-glob filter whencorpusis a directory (default"*.txt"). Matches againstPath.nameonly, not the full path —"*.md"works,"docs/*.md"does not.model(str) — default"gemini-embedding-2".gemini-embedding-001is retired (text-only) and warns if passed explicitly.dim(int) — 128 / 768 / 1536 / 3072 (default 768; MRL-truncated + renormalized)task("text" | "code") — selects text vs code task types
Returns list[Match] where Match has path, line, text, score.
load_corpus(path, *, include="*.txt", granularity="paragraph") -> list[Chunk]
Load and chunk a file or directory without embedding. Useful for inspecting what gets embedded before paying for the API call.
embed_batch(texts, task_type, *, model, dim, group_size=100) -> np.ndarray
Lower-level: embed a list of strings directly via :batchEmbedContents. Returns (N, dim) float32 array, rows normalized when dim < 3072.
format_grep(matches, *, max_text_chars=200, show_score=True) -> str
Format matches as grep output: path:line: snippet [score].
Pipe-mode Rerank Pattern
The highest-leverage use isn't naive full-corpus semantic search — it's hybrid retrieval: fast coarse filter → semantic rerank.
import subprocess
from semantic_grep import Chunk, semantic_grep, format_grep
# Stage 1: fast exact/regex prefilter with rg
result = subprocess.run(
["rg", "-n", "--no-heading", "error|fail|timeout", "logs/"],
capture_output=True, text=True,
)
# Parse `path:line:text` into Chunks
chunks = []
for raw in result.stdout.splitlines():
path, line, text = raw.split(":", 2)
chunks.append(Chunk(path=path, line=int(line), text=text))
# Stage 2: semantic rerank on the prefiltered subset
ranked = semantic_grep("intermittent queue saturation during peak traffic",
chunks, top_k=10)
print(format_grep(ranked))
This is how you scale past the "embed the whole corpus every call" limit without needing a vector DB. The exact-match stage cheaply cuts millions of lines to thousands; semantic reranks those.
Task Types (Gemini)
- text mode (default): query →
RETRIEVAL_QUERY, docs →RETRIEVAL_DOCUMENT. Asymmetric — documented to outperform symmetric encoding for retrieval. - code mode: query →
CODE_RETRIEVAL_QUERY, docs →RETRIEVAL_DOCUMENT. Use when searching code with natural-language queries.
Use SEMANTIC_SIMILARITY (symmetric) only if you're doing pairwise sim, not retrieval. This module doesn't expose that path yet.
Model Notes
gemini-embedding-2 (GA since 2026-04-22) — general-purpose and multimodal.
Verified 2026-07-21 via the CF gateway: text, image and audio all embed to the
same space at the requested dim, L2-normalized. The retired gemini-embedding-001
was text-only and rejected non-text input with HTTP 400:
- 2,048 input token limit per text. Longer texts are truncated at ~8K chars (approximation).
- Matryoshka (MRL) — 3072 native dims, safely truncatable to 1536/768/256/128.
- 3072 is auto-normalized; lower dims need client-side renorm (handled here).
- Pricing: $0.15 / 1M input tokens. 135 medium paragraphs ≈ 15K tokens ≈ $0.002 per query.
gemini-embedding-2-preview (March 2026) is multimodal and currently top of MTEB. Set model="gemini-embedding-2-preview" to opt in once the preview stabilizes.
Limitations
- No persistent index. Every call re-embeds the corpus. Fine for <~1K chunks; prohibitive for real knowledge bases. Phase 2: cache embeddings by content hash.
- Token budget is approximated by char count (×1.5). Conservative for mixed-script text; over-truncates English slightly. Real tokenizer would use the Gemini tokenizer endpoint but costs an extra call per embed.
- Batch bulk-failure diagnostic. If one text in a group of 100 overflows or is rejected by safety filters, the whole batch fails and the 99 good ones are lost. No per-index fallback yet.
- No memory ceiling on corpus size.
semantic_greppre-allocates(N, dim)float32; 1M chunks at dim=768 ≈ 3GB. Caller is responsible for sane chunk counts.load_corpusalso follows symlinks viarglob— fine in a trusted single-user container, not for untrusted paths. - Sequential batch groups.
group_size=100per HTTP call; groups run serially. For >1K chunks, add asyncio — not needed yet. - No CLI shim. Called as a Python module, not a subprocess. Per design: "within an LLM rather than calling out to one."
- Embedding function lives here, not in
invoking-gemini. Should be factored up when invoking-gemini adds embedding support. Tracked as followup.
Related Skills
invoking-gemini— sibling; handles Gemini text + image generation through the same CF gateway. Shares credential pattern.searching-codebases— regex/AST search. Use first when the query is a known pattern.extracting-keywords— YAKE keyword extraction; orthogonal, but pairs well for building query terms from a long prompt.exploring-codebases— for understanding repo structure. Semantic-grep doesn't replace AST-based navigation.
Attribution
Conceptually inspired by jina-grep-cli — we kept the retrieval shape (grep-compatible output, asymmetric query/doc embeddings, threshold + top-k) but swapped the MLX/Apple-Silicon backend for a portable Gemini API call. The original's pipe-mode rerank pattern is the most generalizable idea it contributes and is preserved here.
tree-sitting
Tree-sitter symbol index over a local checkout. Every result carries line
ranges, so the next step is a scoped Read.
Setup
Needs Python 3.10+ and pip install tree-sitter. On macOS, /usr/bin/python3
is 3.9 and will not work; use a Homebrew or uv Python. Grammars are bundled
for Linux x86_64 (parsers/*.so) and macOS (parsers/*.dylib).
If a file's grammar doesn't load, the file is skipped and stderr prints
WARNING: no grammar for … with the fix. Resolve that before trusting an empty
result. On other platforms, run python3 scripts/build_grammars.py (needs git
and cc). It writes to $TREESIT_PARSERS_DIR, or ~/.cache/tree-sitting/parsers/
when that is unset, and grammars there take precedence over the bundle.
Installed tree-sitter-<lang> wheels are the last fallback.
Use
scripts/treesit.py in this skill's directory scans the repo on every call
(cached on disk; invalidated when files or grammars change), prints a tree
overview, then answers the queries. Batch queries so one scan serves them all.
python3 scripts/treesit.py REPO # overview, depth 1
python3 scripts/treesit.py REPO --path=src/core --detail=full # drill in
python3 scripts/treesit.py REPO --no-tree 'find:Parser*' 'source:parse_input' 'refs:ParseState'
| Query | Returns |
|---|---|
find:PATTERN[:KIND[:LIMIT]] | symbols by name, substring or glob |
symbols:FILE | every symbol in a file |
source:SYMBOL[:FILE] | the symbol's source |
refs:SYMBOL[:LIMIT] | textual references |
imports:FILE | a file's imports |
dir:PATH | directory overview |
Flags: --depth N (-1 = all), --detail sparse|normal|full, --path DIR,
--skip DIRS, --no-tree, --stats, --no-cache, --rebuild-cache.
scripts/engine.py exposes CodeCache for use inside one Python process.
Languages: Python, JavaScript, TypeScript/TSX, Go, Rust, Ruby, Java, C, HTML,
Markdown (heading outline), Mojo. Other languages get generic extraction if
their tree-sitter-<lang> wheel is installed.
Use something else for
- a repo that isn't on disk:
accessing-github-repos - what a codebase does:
featuring - a first look at an unfamiliar repo:
exploring-codebases - binding-resolved Python callers:
searching-codebases --refs - literal text or regex:
rg
Sponsors
Details
- Marketplace
- oaustegard/claude-skills
- Source
- plugins/code-intelligence
- Category
- Code Intelligence
- License
- MIT
- Keywords
- assessing-impact, declaring-invariants, describing-products, exploring-codebases, featuring, hunting-failing-inputs, mapping-codebases, mapping-webapp, orienting-codebases, python-lsp, reasoning-semiformally, searching-codebases, semantic-grep, tree-sitting
More from oaustegard/claude-skills
All 14- data-and-visualizationv1.0.0
- deciding-with-confidencev0.4.0
- declaudingv0.14.0
- delegating-with-contextv0.3.0
- development-toolsv1.2.1
- environment-and-configv2.0.0
- github-and-gitv2.0.1
- knowledge-and-memoryv1.3.0
- media-processingv2.3.0
- skill-developmentv2.6.0
- social-and-lifestylev1.0.0
- web-and-retrievalv1.0.4
- ai-and-reasoningv2.9.1