scip-query 0.20.0 → 0.21.0

package/skills/scip-audit/references/maintainability.md

@@ -1,162 +0,0 @@
-# Maintainability: hidden policy, scattered concepts, weak boundaries
-
-Maintainability is the degree to which real code units let a maintainer
-understand, verify, and change behavior without rediscovering hidden
-knowledge. Use for hidden policies, scattered concepts, accidental
-variation, weak boundaries, system compression, architecture smells, and
-structural refactor opportunities beyond a health score.
-
-Ground all claims in files, symbols, references, call graphs, dependencies,
-surfaces, and blast radius rather than opinion. Do not chase health scores —
-detector counts are clues, not objectives. Name concrete referents (specific
-files/symbols) before naming a code smell. Only add an abstraction when it
-removes hidden policy, names a lifecycle, enforces a rule, or reduces
-concept count — never for its own sake; prefer deletion, inlining, merging,
-generation, or enforcement of an existing mechanism before introducing a
-broad new framework.
-
-## Vocabulary
-
-- **Code smell** — an observable codebase fact that predicts avoidable
-  future mistakes because the same knowledge must be rediscovered,
-  synchronized, or defended in more than one place.
-- **Concept boundary** — the line around code units that exist for one
-  reason to change.
-- **Hidden policy** — a rule for choosing among several plausible behaviors
-  that lives in local branches, comments, conventions, or caller folklore
-  instead of a named mechanism.
-- **Lifecycle** — a repeatable sequence of states or steps that makes a
-  result valid.
-- **Accidental variation** — difference in code shape that does not
-  correspond to behavior, domain facts, runtime constraints, or external
-  contracts.
-- **Essential variation** — difference that must remain because the real
-  units differ: language grammars, user-visible APIs, runtime environments,
-  or compatibility boundaries. Preserve it; do not remove it.
-- **System compression** — replacing several mechanisms that perform the
-  same role, policy, lifecycle, or surface job with fewer named mechanisms
-  that preserve behavior.
-- **Unifying definition** — the single essential trait that makes several
-  code sites one concept. Any scattered-concept or consolidation claim must
-  ship its unifying definition; if no such trait covers every cited site,
-  the variation is essential and the sites must not be consolidated. Failing
-  to state it proves the sites are not one concept — consolidating anyway
-  packages essential variation into a false abstraction.
-
-## Step 1 — Bound the review
-
-Restate the review question as: "What future-maintenance mistakes does this
-structure invite, and what smaller named mechanisms would prevent them
-without hiding real variation?" Name the scope as one of: repo, module,
-command family, query family, runtime surface, fixture set, or feature path.
-
-**Complete when:** the review question and scope are both concrete.
-
-## Step 2 — Map evidence
-
-Run, in sequence: `scip-query stats`, `system <scope>`, `surface <scope>`,
-`files <pattern>`, `outline <file>`, `deps <file>`, `rdeps <file>`, `trace
-<symbol>`, `call-graph <symbol>`, `affected <symbol>`, `change-surface
-<file>`.
-
-- `stats` maps repo-wide index size before bounding the review (complete
-  coverage).
-- `system <scope>` gives the full module map — files, exported symbols with
-  line ranges, internal deps, reverse deps (complete coverage).
-- `surface <scope>` shows which symbols consumers actually use — consumer
-  paths and consumed symbol identities (complete coverage).
-- `change-surface <file>` gives a pre-change briefing of defined symbols,
-  external consumer counts, and risk levels (bounded coverage).
-- `affected <symbol>` computes the transitive closure of symbols that could
-  break if a candidate symbol changes (bounded coverage).
-- `drift --patterns --architecture` finds drift candidates — unused imports
-  plus declared architecture boundary violations (bounded coverage; opt-in
-  pattern hits are leads, not confirmed findings).
-
-Use the cleanup-oriented commands `health`, `similar`, `similar-files`,
-`similar-chains`, `extract-candidates`, `wrapper-candidates`,
-`passthrough-candidates`, `stale-abstractions`, `drift`, and `cycles` as
-evidence-gathering probes during this step, not as final verdicts.
-
-**Complete when:** concrete units, consumers, tests, fallbacks, adapters,
-generated artifacts, and compatibility constraints are all visible.
-
-## Step 3 — Build the role inventory
-
-For each cluster, ask what one concept appears in several places and what
-single essential trait makes them one concept — if the trait cannot be
-stated, they are not one concept. Also ask: what policy is hidden, what
-lifecycle is unnamed, which differences are essential, what must a
-maintainer know that the local interface does not admit, and would a
-smaller mechanism remove a reason to change, versus merely move code?
-
-**Complete when:** every candidate smell names its referents and its
-future-maintenance failure mode.
-
-## Step 4 — Rank pressure
-
-Severity tiers, most to least severe:
-
-1. Hidden correctness or evidence policy spread across modules.
-2. A repeated lifecycle or pipeline with no owner.
-3. Public surface exposing accidental internals.
-4. A large module with unrelated reasons to change.
-5. Tests that encode incident history without contract vocabulary.
-6. Adapter families with repeated capability or fallback shapes.
-7. Suppression comments that document architecture decisions instead of
-   exceptions.
-8. Thin wrappers and passthroughs that do not buy clarity.
-
-Reject and do not act on smells that are aesthetic, unverifiable, or false
-compression.
-
-**Complete when:** each target is ranked, skipped, or deferred with
-evidence.
-
-## Step 5 — Choose a model
-
-For substantial changes, compare at least two of three models:
-
-- **Conservative** — delete or inline local bloat.
-- **Shape-level** — introduce one small mechanism for a repeated role or
-  lifecycle.
-- **Radical** — replace a scattered surface with metadata, generation, or
-  enforced policy.
-
-Evaluate: behavior preserved, concept count removed, blast radius, deletion
-potential, false-abstraction failure mode, migration path, and verification
-cost.
-
-**Complete when:** the chosen model removes a concept or policy duplication
-rather than merely extracting a helper.
-
-## Step 6 — Produce a register or atlas
-
-For a broad review, write a register under `docs/plans/` unless the user
-asks not to edit files; for an implementation, write an atlas before
-editing.
-
-Dispositions: merge, delete, inline, extract, generate, enforce, supersede,
-defer, skip.
-
-Every merge, extract, or generate entry must carry its unifying definition
-and its strongest dissenter (the cited site most likely to differ
-essentially), plus evidence that the dissenter does not actually differ
-essentially. If a dissenter survives review (it really does differ
-essentially), the entry moves to disposition `skip` with reason "essential
-variation" — but the dissenter stays recorded in the register either way.
-
-**Complete when:** each opportunity has evidence, disposition, dependency
-order, touch map, and validation plan recorded.
-
-## Step 7 — Implement and verify (when asked)
-
-Implement the smallest named mechanism that matches the real concept, and
-keep essential variation near the adapter or domain code that knows it.
-After implementing, run focused tests and the routed postchecks from
-`scip-verify`, then complete that verification skill.
-
-## Report
-
-State the smell addressed, the mechanism introduced or removed, what was
-deliberately not compressed, and verification results.

package/skills/scip-audit/references/twin-drift.md

@@ -1,104 +0,0 @@
-# Twin drift: same concept, silently diverged copies
-
-Use when the same concept exists in more than one place under the same or a
-near name and the bodies have silently diverged — same-name or near-name
-functions across files with diverged bodies, drifted policy thresholds,
-one-sided fixes, or consolidating a duplicated concept into one canonical
-helper.
-
-Command shortlist: `twin-drift --json --full` (detector), `duplicate-bodies
---json --full` (cross-check), `code <symbol>`, `refs <symbol>`, `diff-gate
---json`.
-
-## Definitions
-
-A **twin drift group** is a same-leaf-name family of callables spanning at
-least two files whose normalized-token bodies are neither identical (that's
-`duplicate-bodies`' job) nor unrelated (a homonym like `render` or `parse`)
-but partially overlapping — signaling a concept copied once and then edited
-independently in only some of its copies.
-
-**Near-name** means case-insensitive match, or edit-distance ≤ 2 for names of
-8 or more characters.
-
-## Detect
-
-Run `scip-query twin-drift --full` to surface every DIVERGENT and
-near-name group in scope; scope it to a module with `-s/--scope <path>` when
-the review should be bounded. Record group count, member count, and
-`maxDivergence` per group.
-
-Cross-check results against `scip-query duplicate-bodies --full` —
-IDENTICAL groups belong to `duplicate-bodies`, not here; do not re-report
-them. Homonyms — groups with similarity below `--min-similarity` (default
-0.3) — are noise and should not be chased unless `--include-homonyms` was
-explicitly requested.
-
-**Complete when:** every group in scope is enumerated with its relationship
-(divergent vs. suppressed homonym).
-
-## Classify each DIVERGENT group
-
-Use `scip-query code <symbol>` to read every member's body; use the group's
-`firstDivergentTokens` field as a starting point for locating where the
-bodies diverge. Assign exactly one label:
-
-- **Intentional variation** — the copies differ because the domains
-  genuinely differ (example: a React-specific vs. Vue-specific structural
-  comparator branching on framework-specific overlap checks). Essential
-  variation stays, and the reason must be recorded.
-- **Drifted policy** — the copies encode what should be one policy (a
-  threshold, a normalization rule, an edge-case guard) that only some copies
-  received when it last changed. This is a bug: pick the correct value and
-  propagate it, or extract the policy into one named function/constant.
-- **One-sided fix** — one copy was bugfixed or hardened and its twin(s)
-  were not. This is a bug: apply the same fix to every member, or
-  consolidate them.
-
-**Complete when:** every DIVERGENT group in scope has one of the three
-labels with a one-line reason.
-
-## Act
-
-Prefer consolidating a twin-drift group into one exported helper over
-leaving parallel copies; when consolidation is unsafe or premature, record
-the intent gap explicitly (comment or waiver) rather than silently accepting
-the drift.
-
-For groups being consolidated, pick the canonical member by comparing
-consumer counts via `scip-query refs <symbol-in-file-A>` and `scip-query
-refs <symbol-in-file-B>` — prefer the member with the most consumers, or the
-one in the more general/shared location when consumer counts tie.
-
-To consolidate: extract or move the canonical body to one exported helper
-and update the other members to call it, or delete them outright if they
-were pure duplication with different names for caller convenience. Preserve
-any classified-essential variation as a parameter or a thin caller-side
-branch, not as a second copy of the whole body.
-
-For groups marked intentional variation, do not force consolidation —
-instead record the reason in a comment near one of the members so the next
-`twin-drift` run and the next reader both see it was considered.
-
-**Complete when:** every DIVERGENT group is either consolidated (old copies
-gone or forwarding) or has a recorded reason it stays separate.
-
-## Verify
-
-After acting, rerun `scip-query twin-drift` to confirm consolidated groups
-no longer appear as DIVERGENT, and run the routed postchecks from
-`scip-verify`.
-
-The twin-partner check inside `scip-query diff-gate` is advisory and never
-blocks the gate by itself, but a finding there on your own diff means you've
-reproduced the exact defect class this workflow exists to catch — fix it or
-explicitly accept it before finishing.
-
-**Complete when:** `twin-drift` shows no unclassified DIVERGENT groups in
-scope and any `diff-gate` findings are resolved or explained.
-
-## Report
-
-List: scope; groups found (total/divergent/suppressed homonyms); each
-divergent group with classification and action taken; and the verification
-results of `twin-drift --json --full` and `diff-gate --json`.

package/skills/scip-diagnose/SKILL.md

@@ -1,52 +0,0 @@
----
-name: scip-diagnose
-description: Use in a scip-query-indexed repo when something is broken, crashing, failing a test, returning wrong data, or regressed — one bug, a recurring family pointing at one design flaw, or a raw issue/ticket needing a fix packet. Also use proactively to prove whether a parser/AST branch is reachable or dead, even with no reported failure. Distinct from the `debugging` skill: that one supplies the general method (reproduce on demand, observe rather than infer, one variable at a time); this one supplies SCIP evidence (trace, refs, dataflow) in an indexed repo. Use both together. Distinct from `incident-review`, which is postmortem methodology after an outage rather than finding a live cause.
-commands:
-  - template: "scip-query files <feature-or-error-term>"
-    when: "Locate the files that can explain an unnormalized report or error."
-  - template: "scip-query trace <candidate-symbol>"
-    when: "Connect a candidate cause to its definition and references."
-  - template: "scip-query call-graph <entry-symbol>"
-    when: "Trace callers and callees around the observed failure path."
----
-
-# scip-diagnose
-
-<!-- BEGIN GENERATED SKILL COMMANDS -->
-## Commands for this skill
-
-| Command | Purpose | Returns | Coverage | When |
-| --- | --- | --- | --- | --- |
-| `scip-query files <feature-or-error-term>` | Find files matching a pattern | matching file paths | `complete` | Locate the files that can explain an unnormalized report or error. |
-| `scip-query trace <candidate-symbol>` | Trace a symbol: definition + all references | definition sites with source and signature; referencing files with line numbers | `bounded` | Connect a candidate cause to its definition and references. |
-| `scip-query call-graph <entry-symbol>` | Show incoming callers and outgoing callees for a symbol | caller and callee symbol identities with files | `bounded` | Trace callers and callees around the observed failure path. |
-
-Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only when it is insufficient.
-<!-- END GENERATED SKILL COMMANDS -->
-
-## Purpose
-
-Move from a reported failure to a minimal verified fix. This skill covers four related but distinct situations — one bug, a recurring family of bugs pointing at one design flaw, a raw issue report that needs to become a fix packet, and an unverified parser/AST branch that needs to be proven reachable or dead — and routes each to its own evidence-gathering mode.
-
-This skill has no commands of its own; every mode below draws on the shared `scip-query` vocabulary. Load [`../_shared/SKILL.md`](../_shared/SKILL.md) for freshness, lookup, postcheck, and subagent rules whenever a mode's shortlist is insufficient.
-
-## Pick the mode
-
-| Situation | Mode | Reference |
-| --- | --- | --- |
-| One reported failure: broken, crashing, failing a test, wrong output, a regression — needs the smallest verified fix | **Debug** | [`references/debug.md`](references/debug.md) |
-| The same kind of bug keeps recurring in one subsystem, patching hasn't worked, or the user lists several fixed/observed bugs and asks what is really wrong | **Root cause** | [`references/root-cause.md`](references/root-cause.md) |
-| A raw bug report, GitHub issue, support ticket, TODO, or vague defect that has not yet been turned into evidence | **Triage** | [`references/triage.md`](references/triage.md) |
-| A conditional branches on a parser/AST node's type, tag, or shape and nobody has checked it against the real parser — dead-branch or wrong-node-type suspicion, tree-sitter grammar mismatch, even with no reported failure | **Probe reachability** | [`references/probe-reachability.md`](references/probe-reachability.md) |
-
-Pick exactly one mode before gathering evidence. Debug and triage both trace a single failing path, but debug assumes the failure is already pinned down enough to reproduce; triage exists because it isn't — normalize the report first. Root cause is not "debug but more bugs": it requires a falsifiable design-flaw hypothesis, killed rivals, retrodiction, and an executed latent-instance hunt, not just more patches. Probe reachability is the only mode that runs without a reported failure at all — it proves or disproves reachability of code nobody has verified against the real parser.
-
-## How the modes relate to each other and to other skills
-
-- **Debug → Root cause escalation:** if a debug fix is the second or third patch to the same mechanism, stop and switch to root-cause mode instead of shipping another narrow patch.
-- **Triage → Debug/Root cause handoff:** triage produces a fix packet with a suspected root cause and a failing-test plan; if the user also asked for the fix, implement from the packet using debug-mode discipline (smallest change, verify, `scip-verify`).
-- **Root cause → scip-plan handoff:** root-cause mode diagnoses and hands off; it does not edit application code. The flaw and invariants become `scip-plan`'s current-flow and risk evidence, and the family table and hunt results constrain its slices.
-- **vs. `debugging` skill:** that skill supplies the general method — reproduce on demand, observe rather than infer, change one variable at a time. This skill supplies the SCIP-specific evidence (trace, refs, dataflow, blast radius) that method needs in an indexed repo. Use both together; this skill does not replace that discipline.
-- **vs. `incident-review`:** that skill is postmortem methodology applied after an outage has already been resolved. This skill finds a live, unresolved cause.
-- **vs. `scip-audit`:** structural smells with no bug evidence go to the maintainability scenario in `scip-audit`. A recurring bug family with bug evidence goes to root-cause mode here.
-- **Verification:** every mode that ends in a code change verifies with the narrowest repo test or smoke command, then invokes the `scip-verify` skill. Triage-only requests stop at the packet.

package/skills/scip-diagnose/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "SCIP Diagnose"
-  short_description: "Find the cause of a failure with SCIP evidence"
-  default_prompt: "Use $scip-diagnose to trace this failure to its cause and produce the minimal verified fix."

package/skills/scip-diagnose/references/debug.md

@@ -1,117 +0,0 @@
-# Debug: one failure → minimal verified fix
-
-Use this mode to move from a reported failure to a minimal verified fix. A **bug** is a mismatch between expected behavior and observed behavior in a concrete execution path. A **root cause** is the earliest code fact in that path that explains the mismatch.
-
-Load shared mechanics from [`../../_shared/SKILL.md`](../../_shared/SKILL.md) only when this shortlist is insufficient.
-
-## Commands used in this mode
-
-| Command | When |
-| --- | --- |
-| `scip-query files <feature-or-error-term>` | Find the entry point from a feature name or error term (complete coverage: matching file paths). |
-| `scip-query outline <candidate-file>` | Enumerate symbols in a candidate file while narrowing the entry point. |
-| `scip-query trace <candidate-symbol>` | Find the entry point: definition plus every reference (bounded coverage: definition sites with source/signature, referencing files with line numbers). |
-| `scip-query code <candidate-symbol>` | Read the exact source at the candidate entry point or callee. |
-| `scip-query kind-counts` / `scip-query by-kind` | Orient in an unfamiliar codebase during entry-point discovery. |
-| `scip-query call-graph <entry-symbol>` | Follow execution: callers and callees along the failing path (bounded coverage). |
-| `scip-query refs <state-or-api-symbol>` | Follow execution: every referencing site of shared state or an API symbol. |
-| `scip-query fan-in <suspect-symbol>` / `scip-query fan-out <suspect-file>` | Follow execution: who depends on the suspect symbol/file, and what it depends on. |
-| `scip-query dataflow <symbol-or-variable>` | Follow data: producers, consumers, and usage sites (bounded coverage). |
-| `scip-query slice <symbol-or-variable>` / `--forward` | Follow data: backward and forward slices from the suspect value. |
-| `scip-query similar <suspect-symbol> --full` | Compare nearby implementations for missing guards or handling (bounded coverage: symbol pairs, similarity scores, shared evidence). |
-| `scip-query similar <suspect-symbol> <similar-symbol> --plan` | Compare two specific implementations directly. |
-| `scip-query similar-files <suspect-file> --full` | Compare nearby files for missing handling. |
-| `scip-query change-surface <suspect-file> --full` | Bound the fix: exports, consumers, and blast-radius risk (bounded coverage). |
-| `scip-query affected <suspect-symbol>` | Bound the fix: transitive closure of symbols that could break. |
-
-## Rules
-
-1. Reproduce or restate the failure before editing.
-2. Use scip-query to find entry points, call paths, data flow, and blast radius.
-3. Prefer one narrow fix over broad cleanup.
-4. Verify with the narrowest repo test or smoke command, then invoke `scip-verify`.
-5. A root-cause claim whose fix crosses a file boundary requires a rival: state the next-most-plausible explanation for the same symptom and run the observation that separates them. A root cause with no rival considered is a guess presented with unearned confidence.
-
-## Workflow
-
-### 1. Pin the failure
-
-Record observed behavior, expected behavior, the reproducing command/route/UI action/test/job/file, error text or wrong output, and the regression window if known.
-
-If no reproduction is provided, build the smallest runnable reproduction from existing tests, scripts, CLI, or app entry points.
-
-This step is complete only when the mismatch is concrete enough to test, or the missing external fact is named.
-
-### 2. Find the entry point
-
-```bash
-scip-query files <feature-or-error-term>
-scip-query outline <candidate-file>
-scip-query trace <candidate-symbol>
-scip-query code <candidate-symbol>
-```
-
-Use `kind-counts` or `by-kind` when the codebase is unfamiliar.
-
-This step is complete only when the failing path has a plausible entry point with source evidence.
-
-### 3. Follow execution and data
-
-```bash
-scip-query call-graph <entry-symbol>
-scip-query code <callee-symbol>
-scip-query refs <state-or-api-symbol>
-scip-query fan-in <suspect-symbol>
-scip-query fan-out <suspect-file>
-scip-query dataflow <symbol-or-variable>
-scip-query slice <symbol-or-variable>
-scip-query slice <symbol-or-variable> --forward
-```
-
-Stop expanding the trace when the first code fact that can cause the symptom is found.
-
-When a candidate cause emerges, state it as a hypothesis alongside one rival — the next-most-plausible explanation for the same symptom. Name the observation that distinguishes them (a log line, a probe, a narrower test) and execute it. Choose the discriminator that is cheapest to run, not the one most likely to confirm the preferred hypothesis.
-
-This step is complete only when the path explains the symptom or the missing evidence is made explicit.
-
-### 4. Compare nearby implementations
-
-```bash
-scip-query similar <suspect-symbol> --full
-scip-query similar <suspect-symbol> <similar-symbol> --plan
-scip-query similar-files <suspect-file> --full
-```
-
-Use implementation comparisons to find missing guards, conversions, lifecycle steps, or error handling, while preserving essential differences.
-
-This step is complete only when comparisons either support the fix or are rejected with a stated reason.
-
-### 5. Bound and fix
-
-```bash
-scip-query change-surface <suspect-file> --full
-scip-query affected <suspect-symbol>
-```
-
-Make the smallest code change that fixes the root cause.
-
-This step is complete only when the changed symbol/file is justified by blast-radius evidence.
-
-### 6. Verify
-
-Run the reproduction, a narrow test or smoke command, and invoke `scip-verify`.
-
-## Report
-
-```markdown
-Bug:
-Entry point:
-Root cause:
-Rival considered:
-Discriminator: <the executed observation that separated them>
-Fix:
-Verification:
-Remaining risk:
-```
-
-Do not present a guess as a root cause. A root cause with no rival considered and no executed discriminator is a guess. If no root cause is proven, state the missing evidence instead of asserting a cause.

package/skills/scip-diagnose/references/probe-reachability.md

@@ -1,77 +0,0 @@
-# Probe reachability: prove a parser/AST branch reachable or dead
-
-Use this mode for code that branches on a parser or AST node's type or shape (`node.type === '...'`, a grammar-specific tag, a regex over token shape) where nobody has verified the real parser ever produces that type or shape. A branch written from documentation, memory, or a similar grammar in another language can be permanently dead: it looks correct, compiles, and is never exercised by a single test, because the input that should reach it never reaches it under the actual parser. This mode runs without any reported failure — the trigger is an unverified branch, not a bug report.
-
-Load shared mechanics from [`../../_shared/SKILL.md`](../../_shared/SKILL.md) only when this shortlist is insufficient.
-
-## Commands used in this mode
-
-| Command | When |
-| --- | --- |
-| `scip-query outline <file> --signatures` | Enumerate branches: symbol tree with signatures for the target file (complete coverage: symbol names, nesting, line ranges). |
-| `scip-query code <symbol>` | Enumerate branches: read each branch condition's exact node-type check (complete coverage: definition identity, source, line range). |
-| `scip-query trace <symbol>` | Enumerate branches: confirm the function's only caller/entry point (bounded coverage). |
-
-## Rules
-
-1. Never trust a branch condition by reading it; run the real parser on an input constructed to hit it.
-2. Write scratch probe scripts only under the session scratchpad, never inside the repository — they are throwaway evidence, not product code.
-3. Never create a git worktree and never symlink `node_modules` for this mode's probes; import the parser module directly (from `src/` via a TypeScript runner, or from the built package) in a standalone script that needs no repo-root install step.
-4. A branch is a finding whether it is truly unreachable (dead code) or reachable but under a different node-type string than the code checks (a silent misclassification, which is worse than dead code because it fails without raising anything).
-5. Completion requires every node-type/shape branch in the target function to have either a reached probe or a filed finding — partial coverage is not done.
-
-## Workflow
-
-### 1. Enumerate branch conditions
-
-```bash
-scip-query outline <target-file> --signatures
-scip-query code <target-function>
-```
-
-List every conditional that tests a node's `type`, tag name, or shape (an `if`/`else if` chain over `node.type === '...'`, a `switch` on a grammar tag, or a regex matched against node text standing in for a type check). Record the exact string or pattern each branch expects.
-
-This step is complete only when every node-type/shape branch in the target function is listed with its file:line and the exact condition text.
-
-### 2. Construct a minimal input per branch
-
-For each branch, write the smallest source snippet in the target language that should, by the language's grammar, produce a node of that type or shape at that point in the tree. Prefer one snippet per branch; note when a single snippet is expected to exercise more than one sibling branch in a walk.
-
-This step is complete only when every branch has a candidate input snippet.
-
-### 3. Run the real parser
-
-Write one scratch script under the session scratchpad (never in the repo) that imports the actual parser module used by the target code — not a reimplementation, not a mental model of the grammar — and, for each candidate snippet:
-
-1. Parses it.
-2. Walks the resulting tree and collects every node type actually produced.
-3. Reports whether the branch's expected type/shape appears anywhere in that set.
-
-Run the script (for example `npx vite-node <scratch-script>` from the repo root, or a plain `node` script importing the built package) and record reached/unreached per branch.
-
-This step is complete only when every branch from step 1 has a recorded reached/unreached result from an actual parser run, not an inference.
-
-### 4. File findings for unreached branches
-
-For each unreached branch, determine and record which of these it is:
-
-- **Dead branch**: the grammar never produces this node type/shape anywhere reachable from valid source in this language; the branch is unreachable code. Fix: delete it, or replace it with the branch that actually covers the intended case (found by inspecting the node types the parser did produce for the candidate input).
-- **Wrong node-type string**: the intended case is real and common, but the branch checks the wrong string (a rename in the grammar, a typo, or a mismatch borrowed from a different language/version). Fix: correct the string to what step 3 actually observed.
-
-This step is complete only when every unreached branch has one of these two labels and a fix direction.
-
-### 5. Report
-
-```markdown
-Target: <file:function>
-
-Branches:
-| Branch condition | Candidate input | Reached? | Finding |
-| --- | --- | --- | --- |
-
-Findings:
-
-- <branch> — dead branch / wrong node-type string — fix: <direction>
-```
-
-Completion requires every branch from step 1 to appear in the table with a reached/unreached result.