oaustegard avatar

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

Run it inside Claude Code after adding the marketplace with /plugin marketplace add oaustegard/claude-skills.

Contents

Discovered from source

Skills 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

FlagDefaultPurpose
--features PATH_FEATURES.mdRoot _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 N500Cap refs per symbol name. Bump if you suspect truncation.
--jsonoffEmit 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-codebases if 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-sitting to drill specific call sites once impact has identified them.
  • Use searching-codebases when 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

findingmeaning
sampled-domaina parametrize or for over a literal whose members are a strict subset of a source registry. The uncovered members are named.
ratchet-brokena hand-list marked ratchet names a member the registry no longer contains. Detected statically, without running anything.
unratcheteda registry enumerated live with nothing pinning its membership. Suppressed when no-floor already claimed the same line.
no-floora test iterates a live registry with no len(...) >= n assertion in the file, so an emptied registry passes vacuously.
stale-ackan 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_CODESdomain floorenumerationparityhand-list
grow — add "hadamard2"passREDREDpass
shrink — drop "none"REDpassRED*pass
substitute — "none" → "xyz" in both spellingspasspasspasspass

* 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.
    """
findingmeaning
unrefuteda claim nobody has watched fail
literalthe claiming test iterates a copy of the registry, so the claim cannot see a new member
unanchoreda 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:

  1. Break the chokepoint the claim names, with one edit in the source rather than in the test.
  2. Run the claiming test. Read the failure text. Note the member it named.
  3. 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.
  4. Restore the source.
  5. 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-floor fires only on a name independently recognised as a registry. Firing on every for x in <local> produced 27 findings on remex, 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 in discrepancy/ to registries in kb-k-sweep/ and remex-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_py and _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. --strict opts 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 parametrize is read.
  • unanchored is 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 a parametrize list 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. unanchored and unratcheted surface 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-claims covers 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-sitting locates the registry or the test before you edit it.
  • building-property-tests finds the bugs; its step 9 promotes the properties a codebase depends on into invariant: 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.

FileUse
references/product-kinds.mdMap 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.mdSkeletons for the three files that steer the build. goal-template.md carries the writing rules.
references/document-template.mdThe eight-section skeleton every feature document follows.
references/verification-template.md, bug-triage-template.mdSkeletons for the checking half.
scripts/check_links.pyEvery 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.pyCoverage 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".

  1. Product and surface. Which app, route, role or configuration, with what customization (usually none). One surface per repo.
  2. Source of truth. Path to the source repo (read-only) and its commit. Every document footer cites git rev-parse --short HEAD of that repo.
  3. Where to run it. The command and URL, binary, or account that brings the surface up for verification.
  4. Out of scope. Name each exclusion and why, so readers do not take it for an omission.
  5. Where the repo goes. A new directory with git init and a first commit Initial 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 a RESULTS.md, to check_structure.py --exclude).
  6. 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:

  1. 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 as not started. Revise both as you learn; they must always mirror the files on disk.
  2. 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.
  3. goal.md from goal-template.md. It drives all drafting. Its "Things already established" section starts empty.
  4. 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.

  1. Pilot. One small, self-contained feature with a real interaction in it (product-kinds.md names 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. Run check_structure.py on the repo once the pilot exists; it is the reference shape from here on.
  2. 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".
  3. The hardest area. The bulk of the experience (the selection tool, the main editor, the build command, 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}.md on the same skeleton, at the same depth. Use the glossary's words. Do not edit glossary.md, README.md, goal.md or 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 from drafted to verified.
  • 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.

  1. Read AGENTS.md, README.md (structure, coverage, scope decisions), goal.md (established facts) and glossary.md. Read the pilot to recalibrate depth. Run both scripts to see the repo's current state.
  2. 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.py warns when documents cite more than one commit; never let that happen silently.
  3. 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 next B-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.
  4. 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}.
  5. 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 deliverableCommandSize
Your own understanding — a review, an orientation read, answering a question--orient~115 lines
A written _FEATURES.md that must cite every symbolfull outputthousands 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

SituationUse
"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 analysisaccessing-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:

  1. bm25 → tree-sitting. Use bm25 to find the top-ranked files for a concept; then tree-sitting source:Symbol:path/to/file.py to read the actual implementation.
  2. 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.md files 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:

  1. What can a user/consumer DO with this? (commands, API endpoints, UI actions)
  2. What problems does it solve? (the WHY behind the code)
  3. What are the main workflows? (how features compose)
  4. What are the constraints/invariants? (rules the code enforces)

Pass 2: Detailed feature extraction

For each capability area identified in Pass 1:

  1. Gather the symbols that implement it (from gather output + targeted get_source())
  2. Understand how they collaborate — the workflow
  3. Identify constraints and invariants
  4. 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):

SignalAction
≤6 key symbols, self-containedInline in root _FEATURES.md
>6 key symbols OR clear sub-capabilitiesOwn _FEATURES.md sub-file
Spans many files but is ONE capabilityInline (breadth ≠ complexity)
Has sub-features that are independently usefulOwn 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:

  1. States what the codebase is in one sentence
  2. Lists the top-level capability areas (3-8 items)
  3. For each area that has a sub-file: one sentence + link + "read when" guidance
  4. 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#symbol notation (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:

  1. Does this capability area have enough complexity to warrant its own file? (>6 key symbols, multiple sub-workflows, or independently useful sub-features)
  2. Would an agent working on this area benefit from focused context? (if yes, a sub-file saves them from parsing unrelated features)
  3. 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:

  1. Run treesit.py /path --depth=-1 --detail=sparse for full structural overview
  2. Pass 1: Form a hypothesis about what the codebase does
  3. Run treesit.py /path --path=DIR --detail=full for each capability area
  4. Run treesit.py /path --no-tree 'source:symbol_name' where intent isn't clear
  5. Pass 2: Write detailed feature sections, deciding hierarchy per-feature
  6. 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

SkillWhat it providesDrift detection
tree-sittingStructural inventory (symbols, signatures)N/A (live queries)
featuringFeature documentation (what/why), hierarchicalcheck.py — docs → code
generating-latticeBidirectional knowledge graphlat check — docs ↔ code
mapping-webappWeb 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

SituationUse instead
Races, deadlocks, async orderingrace detector or stress test
Whole programs, I/O, network, UIfuzzing plus sanitizers; extract the pure core first
Wrong results no precondition expressesbuilding-property-tests, or reasoning-semiformally
Whether a test can go redgating
Validating or minifying WGSLcompiling-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

  1. List the traps. python3 $SKILL/scripts/list_traps.py FILE... [--func NAME] prints file:line:col kind on-failure func source. on-failure is raises, silent or UB (C, which is silent without sanitizers). Model the silent and UB traps first. Strike any trap that an earlier guard already makes safe, and in JS strike object lookups. For Go, use bce_targets.py instead (see references/go.md).

  2. Read references/<lang>.md for the target's language: python, javascript, c, wgsl or go. Each one has the failure semantics, the predicate to model each trap with, the strict harness, and a runnable example in examples/<lang>/.

  3. Model one pure function. Include the guards its callers enforce as constraints. Without them, Z3 invents inputs the program can never produce.

  4. Write the model from scripts/z3traps.py, copying the nearest examples/<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 widen exactly where the source converts. Python ints never wrap. C narrows on a store or a cast, JS |0 truncates to 32 bits, and WGSL u32 and Go uint8 wrap.
    • 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=True when 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 first sat.
    • z3py's < and >= on bit-vectors are signed. For unsigned values, widen first or use ULT/UGE.
  5. Replay each sat inside the strict harness. literal(bytes, lang) renders the input for a test. Use the harness for the language:

    languagestrict harness
    Pythonparse(strict(data)), scripts/strict.py
    JS / TSdecode(strict(u8)), scripts/strict.mjs
    C-fsanitize=address,undefined -fno-sanitize-recover=all, input in an exact-size malloc
    WGSLscripts/wgsl_guard.py counts bad indexes in an extra _oob buffer
    God = d[:len(d):len(d)]

    Then read the result:

    Z3replaymeaning
    satfails at the trap's lineA bug. Report it with the reproducer.
    satfails at an earlier lineRe-solve with in_order=True.
    satdoesn't fail, or fails differentlyThe 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.
  6. 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
  • unsat with a stated bound, plus a negative control that went sat
  • 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 sat input 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 input b'\x00\xc0' raised IndexError instead.
  • A later trap's sat input fails at an earlier line. Use in_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>-dev is 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

  1. tree-sitting must be installed (structure is scanned at runtime)
  2. Claude API key available (via api-credentials skill or ANTHROPIC_API_KEY env var)
  3. 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

FlagDefaultDescription
--app-urlrequiredBase URL of the web app
--codebaserequiredPath to repo root
--output<codebase>/_FEATURES.mdOutput path
--max-pages100Cap on pages to discover
--code-onlyfalseSkip all vision — code analysis only
--verify-onlyfalseOnly run vision on already-analyzed pages
--batch-sizeautoPages per batch (auto-detected from environment)
--incrementalfalseOnly re-process changed pages
--viewport1280x720Screenshot viewport (WxH)
--routesnoneComma-separated routes or path to routes file
--screenshots-dir<codebase>/screenshotsWhere to store PNGs
--modelclaude-sonnet-5-5 (set in scripts/featuremap.py; that file is the source of truth)Claude model for analysis/vision
--dry-run / -nfalseDiscover 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 --routes for 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:

EnvironmentBatch SizeNotes
Claude.ai container4 pagesShort bash timeouts
Claude Code on Web12 pagesLonger execution windows
Local CLIUnbatchedFull 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:

  1. tree-sitting → structure, scanned at runtime
  2. mapping-webapp → _FEATURES.md (behavioral)
  3. 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 --routes flag
  • 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.

LevelArtifact showsQuestion asksUse when
HighFull function source, line numbers, file path"What does this function check?"First exercise, unfamiliar language
MediumFunction signature + key lines only"What's the validation logic here?"Second exercise, or user nailed the first
LowFile 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

SituationUse
"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

MethodReturnsNotes
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 | NoneInferred 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)

  1. Wait for indexing before querying. Querying mid-index returns empty results — the most common silent failure. wait_for_index() blocks on pyright's $/progress begin/end cycle (with a diagnostics-arrival fallback). Always call it after did_open / open_all and before any query.
  2. Don't advertise workspace.configuration or workspace.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 — no didChangeConfiguration nudge needed. Relevant if you reimplement the lifecycle or add capabilities. (Bisected against the fixture; workspace.symbol is safe to advertise.)
  3. Reap the subprocess. Use the context manager (or call stop()) so sessions don't leak pyright-langserver processes. stop() sends shutdown + exit, then waits/terminates/kills as needed.
  4. Open the files you query. Queries auto-did_open their target file, but for cross-file references open all relevant files first so pyright has built their models.
  5. 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. LSPClient auto-detects this (climbs out of the enclosing package; see find_project_root) and prints the promotion to stderr; auto_root=False opts out. This was a live silent-undercount bug: --refs ScalarFunction over scipy/optimize returned 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:

  1. Fault localization to find the bug
  2. Patch verification to validate a proposed fix
  3. 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.

SituationUse
What symbols does this file contain?tree-sitting
Where is X defined, so I can read it?tree-sitting
Any structure question, any languagetree-sitting
A literal string or regexplain ripgrep
Which files are most about a concept?bm25
First look at an unfamiliar repoexploring-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 .zip or .tar.gz archive

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 --expand and the symbol→position resolution that seeds the binding-resolved tier (--refs/--def/--hover). Auto-installs the bare tree-sitter package 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 system node (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 is X really defined" for a .py symbol, when same-named-but-unrelated symbols would pollute a text grep. Empirical basis: rg get on psf/requests returned 232 hits, 224 of them false; --refs get excluded 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 -l tied 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 formatting
  • scripts/resolve.py — Input source resolution (GitHub, uploads, archives)
  • scripts/context.py — tree-sitting-based AST context expansion
  • scripts/ngram_index.py — Sparse n-gram inverted index, regex decomposition
  • scripts/sparse_ngrams.py — Core n-gram algorithms, frequency weights
  • scripts/code_rag.py — TF-IDF semantic search over code chunks
  • scripts/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):

TaskTool
Known exact string, filename, or regexgrep / rg / searching-codebases
"What files discuss concept X" when X may not appear verbatimsemantic-grep
Hybrid: prefilter with grep, rerank by conceptgrep → 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 with RETRIEVAL_QUERY task type)
  • corpus (str | Path | list[Chunk]) — a file, directory, or pre-chunked list
  • top_k (int | None) — max results; None = all above threshold
  • threshold (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 when corpus is a directory (default "*.txt"). Matches against Path.name only, not the full path — "*.md" works, "docs/*.md" does not.
  • model (str) — default "gemini-embedding-2". gemini-embedding-001 is 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_grep pre-allocates (N, dim) float32; 1M chunks at dim=768 ≈ 3GB. Caller is responsible for sane chunk counts. load_corpus also follows symlinks via rglob — fine in a trusted single-user container, not for untrusted paths.
  • Sequential batch groups. group_size=100 per 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'
QueryReturns
find:PATTERN[:KIND[:LIMIT]]symbols by name, substring or glob
symbols:FILEevery symbol in a file
source:SYMBOL[:FILE]the symbol's source
refs:SYMBOL[:LIMIT]textual references
imports:FILEa file's imports
dir:PATHdirectory 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