scip-query 0.19.5 → 0.19.8

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

@@ -0,0 +1,117 @@
+# 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> --json --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> --json --full` | Compare nearby files for missing handling. |
+| `scip-query change-surface <suspect-file> --json --full` | Bound the fix: exports, consumers, and blast-radius risk (bounded coverage). |
+| `scip-query affected <suspect-symbol> --json` | 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> --json --full
+scip-query similar <suspect-symbol> <similar-symbol> --plan
+scip-query similar-files <suspect-file> --json --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> --json --full
+scip-query affected <suspect-symbol> --json
+```
+
+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-probe-reachability/SKILL.md → scip-diagnose/references/probe-reachability.md}

@@ -1,38 +1,22 @@
----
-name: scip-probe-reachability
-description: Prove whether a parser/AST branch is actually reachable by running the real parser on minimal inputs. Use for unreachable or dead node-type/shape branches, wrong node-type strings, tree-sitter grammar mismatches, or any conditional written for an AST or parser output that has never been checked against the real parser.
-commands:
-  - template: 'scip-query outline <file> --signatures'
-    when: 'Enumerate branches: symbol tree with signatures for the target file.'
-  - template: 'scip-query code <symbol>'
-    when: "Enumerate branches: read each branch condition's exact node-type check."
-  - template: 'scip-query trace <symbol>'
-    when: "Enumerate branches: confirm the function's only caller/entry point."
----
+# Probe reachability: prove a parser/AST branch reachable or dead
 
-# scip-probe-reachability
+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.
 
-Use this skill 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.
+Load shared mechanics from [`../../_shared/SKILL.md`](../../_shared/SKILL.md) only when this shortlist is insufficient.
 
-Load shared mechanics from [`../_shared/SKILL.md`](../_shared/SKILL.md).
+## Commands used in this mode
 
-<!-- BEGIN GENERATED SKILL COMMANDS -->
-## Commands for this skill
-
-| Command | Purpose | Returns | Coverage | When |
-| --- | --- | --- | --- | --- |
-| `scip-query outline <file> --signatures` | Tree view of symbols in a file, with line ranges | symbol names, nesting, and line ranges | `complete` | Enumerate branches: symbol tree with signatures for the target file. |
-| `scip-query code <symbol>` | Read the source code for a symbol (bounded to its definition range) | definition identity, source, and line range | `complete` | Enumerate branches: read each branch condition's exact node-type check. |
-| `scip-query trace <symbol>` | Trace a symbol: definition + all references | definition sites with source and signature; referencing files with line numbers | `bounded` | Enumerate branches: confirm the function's only caller/entry point. |
-
-Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only when it is insufficient.
-<!-- END GENERATED SKILL COMMANDS -->
+| 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 skill'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.
+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.
 
@@ -51,7 +35,7 @@ This step is complete only when every node-type/shape branch in the target funct
 
 ### 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 branch (siblings in a walk).
+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.
 

package/skills/scip-diagnose/references/root-cause.md

@@ -0,0 +1,145 @@
+# Root cause: recurring bug family → design flaw → least invasive remedy
+
+Use this mode to move from a family of related bugs to the design flaw that
+produces them, and to the least invasive remedy that eliminates the class.
+Debug mode takes one failure to one minimal fix; the maintainability scenario
+in `scip-audit` finds structural smells without bug evidence; this mode starts
+from evidence that patching has not worked — the same kind of bug keeps
+recurring — and asks what the system's design gets wrong.
+
+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 trace <mechanism-symbol>` | Assemble the family: mechanism and violated invariant for each bug (bounded coverage: definition sites with source/signature, referencing files with line numbers). |
+| `scip-query code <mechanism-symbol>` / `scip-query dataflow <mechanism-symbol>` | Assemble the family: trace each bug's mechanism to source rather than a symptom description. |
+| `scip-query co-change <fix-site-file>` | Assemble the family: files that historically changed together with each fix site without a dependency edge — hidden coupling candidates, and a way to find family members the user forgot (bounded coverage: file pairs, co-change counts, confidence, history context). |
+| `scip-query system <system-scope>` | Define the system's real responsibilities, files, and dependencies in and out (complete coverage: module file paths, exported symbols with line ranges, internal and reverse dependencies). |
+| `scip-query surface <system-scope>` | Define the system: referents for its public surface alongside `system`. |
+| `scip-query similar <fixed-symbol> --json --full` | Predict: hunt latent instances among sibling implementations of the fixed code (bounded coverage). |
+| `scip-query refs <invariant-carrier>` | Predict: every site that touches the violated invariant's state (bounded coverage: referencing file paths, reference line numbers grouped by file). |
+| `scip-query affected <remedy-symbol> --json` | Choose the remedy rung: blast radius of the candidate remedy (bounded coverage: transitive closure of symbols that could break). |
+
+## Terms
+
+A **bug family** is a set of failures whose mechanisms violate the same invariant; what makes it a family rather than a coincidence is that one stated flaw derives every member, so fixing members one at a time treats symptoms of a shared cause.
+
+A **design flaw** is a mismatch between what a system's design assumes and what its real responsibilities require; what makes it the root cause is that it is the earliest fact from which every family member's mechanism follows, so removing it removes the class.
+
+**Retrodiction** is deriving each already-known bug from the hypothesized flaw; what makes it a test is that a family member the flaw cannot derive either shrinks the family or kills the hypothesis.
+
+A **latent instance** is a not-yet-reported bug the flaw predicts must exist in unfixed code; what makes it decisive is that it is checkable now — finding one confirms the diagnosis and becomes a fix target, while an honest hunt that finds none weakens the diagnosis and must be reported as weakening it.
+
+The **remedy ladder** is the ordered set of interventions from least to most invasive; what makes the order binding is that each rung is only justified when a constructed family member survives the rung below it.
+
+## Rules
+
+1. Every bug in the family gets a mechanism traced to source, not a symptom description: which invariant broke, where, and what the fix did. Sources: fix commits (`git log --follow`, `git show`) plus `trace`/`code`/`dataflow`.
+2. The flaw hypothesis must be falsifiable and stated as a design claim — "the design assumes X, but the system's responsibilities include Y" — never as a narrative about unlucky bugs.
+3. State at least two rivals and kill them with evidence: unrelated coincidences, caller misuse rather than design, one missed edge case rather than a structural flaw.
+4. The hypothesis must retrodict every family member and predict at least one latent instance, and the latent-instance hunt must be executed (`similar`, `refs` over the invariant's carriers, or a constructed probe), not merely argued.
+5. Choose the lowest remedy rung that kills the whole class — retrodicted and latent members both. Climb a rung only when a constructed family member survives the rung below, and keep that counterexample in the record.
+6. Root-cause stories are the most rationalization-prone artifact in software: prefer delegating the attack on the diagnosis and the remedy to a fresh subagent given only the family table, system definition, and hypothesis — briefed to win by refuting it. Solo fallback: write the rival hypotheses and the latent-instance predictions before reading any more code.
+7. The verdict is derived with counts, and the diagnosis hands off to
+   `scip-plan` for implementation — this mode does not edit application code
+   itself.
+
+## Workflow
+
+### 1. Assemble the bug family
+
+For each reported or fixed bug, fill one row:
+
+```markdown
+| Bug | Symptom | Mechanism (file:symbol) | Invariant violated | Fix applied | Source |
+| --- | ------- | ----------------------- | ------------------ | ----------- | ------ |
+```
+
+Evidence: the user's description, fix commits (`git log --follow`, `git show`), `scip-query trace`/`code` on the mechanism symbols, `scip-query co-change` on fix sites to find members the user forgot.
+
+This step is complete only when every row has a source-traced mechanism and a named invariant — a bug whose mechanism cannot be traced is listed as `unconfirmed member`, not silently included.
+
+### 2. Define the system
+
+Define the system that owns the family, contextually: its wider class, then the essential responsibility that explains its other traits in this codebase — with referents from `scip-query system <scope>` and `surface <scope>`. Then list the design's load-bearing assumptions as the code actually embodies them (not as the README states them), each with a `Source:` citation.
+
+This step is complete only when the system's real responsibilities and embodied assumptions are stated with citations.
+
+### 3. Hypothesize the flaw — and its rivals
+
+State the flaw as a falsifiable design claim:
+
+```markdown
+Flaw hypothesis: the design assumes <X> (Source: <citation>), but the system's
+responsibilities include <Y> (Source: <citation>); every family member is an
+instance of the X∧Y collision.
+
+Rivals:
+
+- R1. Coincidence — the members have unrelated causes. Killed by: <evidence> | ALIVE
+- R2. Misuse — callers hold the bug, the design is sound. Killed by: <evidence> | ALIVE
+- R3. <next-most-plausible> — Killed by: <evidence> | ALIVE
+```
+
+A rival still marked `ALIVE` at the end of the workflow caps the diagnosis at `CANDIDATE`, not `CONFIRMED`.
+
+### 4. Retrodict and predict
+
+Retrodiction: derive each family-table row from the flaw in one sentence each. A member that cannot be derived is removed from the family (say so) or refutes the hypothesis (start over).
+
+Prediction: the flaw implies unfixed instances exist. Name where they must be, then hunt:
+
+```bash
+scip-query similar <fixed-symbol> --json --full
+scip-query refs <invariant-carrier>
+```
+
+plus a constructed probe when the claim is cheaply executable. Record each prediction with an executed result:
+
+```markdown
+- L1. <predicted latent instance> → FOUND at <file:line> (new fix target) | NOT FOUND after <hunt executed>
+```
+
+This step is complete only when every family member is retrodicted and every prediction has an executed hunt result. Zero latent instances found is a reportable weakness of the diagnosis, not a detail to omit.
+
+### 5. Choose the lowest rung
+
+The remedy ladder, in order:
+
+1. **Enforce the invariant at a boundary** — type, guard, constraint, lint, trigger — without moving code.
+2. **Consolidate the responsibility into one owner** — the scattered decision gets one named mechanism.
+3. **Redesign the core behind its existing interface** — consumers untouched.
+4. **Redesign the interfaces** — last resort; consumers migrate.
+
+For the chosen rung, run the attack: construct a family member — retrodicted
+or latent — that survives the rung. If one survives, keep the counterexample
+in the record and climb one rung. Check blast radius with
+`scip-query affected` before proposing any rung above 1. For protocol- or
+lifecycle-shaped flaws whose remedy must hold across interleavings, note the
+escalation path to the TLA+ mode in `scip-plan`.
+
+This step is complete only when the chosen rung has an attack record showing no family member survives it, and every rejected lower rung keeps its surviving counterexample.
+
+### 6. Report and hand off
+
+```markdown
+## Root-cause diagnosis
+
+System: <definition with referents>
+Bug family: <n> members traced, <u> unconfirmed
+Flaw: <the design claim> — CONFIRMED | CANDIDATE (rival <id> alive)
+Rivals: <r> stated, <k> killed with evidence
+Retrodiction: <n>/<n> members derived
+Latent instances: <p> predicted, <f> found (each a fix target), hunts executed
+Remedy: rung <1-4> — <the intervention>; lower rungs rejected by <counterexamples>
+Blast radius: <affected summary>
+Escalation: <none | scip-plan TLA+ mode for <property>>
+```
+
+Hand the diagnosis to `scip-plan`: the flaw and invariants constrain current
+flow and risks, the family table and hunt results constrain the slices, and
+the surviving-counterexample record seeds the verification attacks.
+
+The diagnosis is complete only when the verdict line carries the counts and every count is backed by an entry in the record above it.

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

@@ -0,0 +1,119 @@
+# Triage: raw report → grounded fix packet
+
+Use this mode to turn a report into a grounded fix packet. Triage is the evidence pass that determines whether the issue is reproducible, where it enters the codebase, what root cause is likely, and what test should fail before the fix.
+
+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 <issue-term>` | Map ownership: locate files for the reported term (complete coverage: matching file paths). |
+| `scip-query outline <candidate-file>` | Map ownership: enumerate symbols in a candidate owner file. |
+| `scip-query system <module-or-scope>` / `scip-query surface <module-or-scope>` | Map ownership: the module's real shape and public surface for broad subsystems. |
+| `scip-query kind-counts` / `scip-query by-kind` | Map ownership: orient in broad or unfamiliar subsystems. |
+| `scip-query trace <entry-or-error-symbol>` | Trace the failing path: definition plus every reference (bounded coverage: definition sites with source/signature, referencing files with line numbers). |
+| `scip-query code <entry-or-error-symbol>` | Trace the failing path: read the exact source (complete coverage: definition identity, source, line range). For stack traces, read the exact range with `scip-query code 'file:start-end'`. |
+| `scip-query call-graph <entry-symbol>` | Trace the failing path: callers and callees (bounded coverage). |
+| `scip-query dataflow <state-or-input-symbol>` / `scip-query slice <state-or-input-symbol>` | Trace the failing path: data flow and slices from the suspect input or state. |
+| `scip-query similar <suspect-symbol> --json --full` | Compare and bound: nearby implementations for missing handling (bounded coverage: symbol pairs, similarity scores, shared evidence). |
+| `scip-query similar <suspect-symbol> <comparison-symbol> --plan` | Compare and bound: two specific implementations directly. |
+| `scip-query similar-files <suspect-file> --json --full` | Compare and bound: nearby files for missing handling. |
+| `scip-query co-change <suspect-file> --json --full` | Compare and bound: files that historically changed with the suspect file. |
+| `scip-query change-surface <suspect-file> --json --full` | Compare and bound: exports, consumers, and blast-radius risk. |
+| `scip-query affected <suspect-symbol> --json` | Compare and bound: transitive impact bound for the fix plan (bounded coverage). |
+
+## Rules
+
+1. Do not file or implement a fix from the issue title alone.
+2. Use scip-query for code evidence: entry points, references, call flow, data flow, blast radius, and similar implementations.
+3. Prefer a failing test plan before a code plan.
+4. If the user asks only for triage, stop at the packet. If they also asked to fix it, implement only after the packet is clear.
+
+## Workflow
+
+### 1. Normalize the report
+
+Record summary, observed behavior, expected behavior, reproduction, affected surface, severity, user impact, and logs/screenshots/tests/links.
+
+Ask the user only for product intent, credentials, private data, or external system state that the repo cannot answer.
+
+This step is complete only when missing facts are either recovered or named.
+
+### 2. Map ownership
+
+```bash
+scip-query files <issue-term>
+scip-query outline <candidate-file>
+scip-query system <module-or-scope>
+scip-query surface <module-or-scope>
+```
+
+Use `kind-counts` and `by-kind` for broad subsystems.
+
+This step is complete only when likely owner files and surfaces are named.
+
+### 3. Trace the failing path
+
+```bash
+scip-query trace <entry-or-error-symbol>
+scip-query code <entry-or-error-symbol>
+scip-query call-graph <entry-symbol>
+scip-query dataflow <state-or-input-symbol>
+scip-query slice <state-or-input-symbol>
+```
+
+For stack traces, read the exact range with `scip-query code 'file:start-end'`.
+
+This step is complete only when a suspected root cause is tied to source evidence or labeled unproven.
+
+### 4. Compare and bound
+
+```bash
+scip-query similar <suspect-symbol> --json --full
+scip-query similar <suspect-symbol> <comparison-symbol> --plan
+scip-query similar-files <suspect-file> --json --full
+scip-query co-change <suspect-file> --json --full
+scip-query change-surface <suspect-file> --json --full
+scip-query affected <suspect-symbol> --json
+```
+
+This step is complete only when the packet has a narrow test shape and an impact bound.
+
+## Packet
+
+```markdown
+## Issue
+
+<one-sentence mismatch>
+
+## Reproduction
+
+<steps, command, failing test, or missing data>
+
+## Evidence
+
+- <scip-query command>: <fact>
+
+## Suspected Root Cause
+
+<earliest code fact that explains the symptom>
+
+## Impact
+
+- users/surfaces affected
+- blast radius
+
+## Fix Plan
+
+1. Add or update failing test/smoke check.
+2. Make the smallest code change.
+3. Run targeted test.
+4. Invoke `scip-verify`.
+
+## Open Questions
+
+- <product intent or external state only>
+```
+
+If no root cause is proven, label the issue `needs reproduction` or `needs product decision` rather than asserting one.

package/skills/scip-explore/SKILL.md

@@ -1,121 +1,90 @@
 ---
 name: scip-explore
-description: Explain how code works, where a feature is implemented, what calls or consumes it, how data flows, or what a change could affect. Uses scip-query to explore an unfamiliar system before answering or editing.
+description: Use to understand a system before editing it: what calls what, how data flows, what depends on it, what a change would reach, and what historically changed together. Includes choosing high-signal commands for an unfamiliar language and rendering the result as a flow, dependency, or blast-radius diagram. For understanding a failure mode class rather than this codebase, use `engineering-lenses`.
 commands:
-  - template: 'scip-query stats'
-    when: 'Orient: repo-wide size and shape before naming a scope.'
-  - template: 'scip-query system <module-or-scope>'
-    when: 'Orient: map files, symbols, deps in/out for the scope.'
-  - template: 'scip-query trace <entry-symbol>'
-    when: 'Trace entry points: definition plus every reference.'
-  - template: 'scip-query call-graph <entry-symbol>'
-    when: 'Trace entry points: callers and callees for the path.'
-  - template: 'scip-query dataflow <symbol-or-variable>'
-    when: 'Follow data and state through producers and consumers.'
-  - template: 'scip-query affected <symbol> --json'
-    when: 'Map dependencies and consumers: downstream blast radius.'
+  - template: "scip-query system <module-or-scope>"
+    when: "Orient to a module's files, symbols, dependencies, and consumers."
+  - template: "scip-query trace <entry-symbol>"
+    when: "Connect an entry symbol to its definition and references."
+  - template: "scip-query affected <symbol> --json"
+    when: "Measure the transitive downstream blast radius of a change."
 ---
 
-# scip-explore
+## Purpose
 
-Use this skill to produce verified understanding. Exploration is the evidence pass that traces code from entry points to effects using the SCIP index rather than memory or folder guesses.
-
-Load shared mechanics from [`../_shared/SKILL.md`](../_shared/SKILL.md).
+Build verified understanding of how a system works end to end — entry points, call flow, data flow, dependencies, consumers, and risk — before answering or editing. Exploration means tracing code from entry points to effects against the SCIP index, not against memory or folder guesses. Load shared mechanics from `../_shared/SKILL.md`; use this skill's own shortlist first and open `_shared` only when it is insufficient.
 
 <!-- BEGIN GENERATED SKILL COMMANDS -->
 ## Commands for this skill
 
 | Command | Purpose | Returns | Coverage | When |
 | --- | --- | --- | --- | --- |
-| `scip-query stats` | Show index statistics | document, symbol, definition, reference, size, and build-time totals | `complete` | Orient: repo-wide size and shape before naming a scope. |
-| `scip-query system <module-or-scope>` | Full module map: files, symbols, deps in/out | module file paths; exported symbols with line ranges; internal dependencies; reverse dependencies | `complete` | Orient: map files, symbols, deps in/out for the scope. |
-| `scip-query trace <entry-symbol>` | Trace a symbol: definition + all references | definition sites with source and signature; referencing files with line numbers | `bounded` | Trace entry points: definition plus every reference. |
-| `scip-query call-graph <entry-symbol>` | Show incoming callers and outgoing callees for a symbol | caller and callee symbol identities with files | `bounded` | Trace entry points: callers and callees for the path. |
-| `scip-query dataflow <symbol-or-variable>` | Reference-level dataflow: definition sites, usage sites, producers, consumers | definition sites, usage sites, producer symbols, and consumer symbols | `bounded` | Follow data and state through producers and consumers. |
-| `scip-query affected <symbol> --json` | Transitive closure of symbols that could break if this symbol changes | affected symbol identities, files, and traversal depths | `bounded` | Map dependencies and consumers: downstream blast radius. |
+| `scip-query system <module-or-scope>` | Full module map: files, symbols, deps in/out | module file paths; exported symbols with line ranges; internal dependencies; reverse dependencies | `complete` | Orient to a module's files, symbols, dependencies, and consumers. |
+| `scip-query trace <entry-symbol>` | Trace a symbol: definition + all references | definition sites with source and signature; referencing files with line numbers | `bounded` | Connect an entry symbol to its definition and references. |
+| `scip-query affected <symbol> --json` | Transitive closure of symbols that could break if this symbol changes | affected symbol identities, files, and traversal depths | `bounded` | Measure the transitive downstream blast radius of a change. |
 
 Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only when it is insufficient.
 <!-- END GENERATED SKILL COMMANDS -->
 
-## Rules
-
-1. Use a current index before trusting graph facts.
-2. Relationship, consumer, and completeness claims cite scip-query; literal local-source claims may cite a native file read.
-3. Resolve ambiguous symbols before describing behavior. `scip-query code` is useful but not mandatory when an exact native range is already known.
-4. Follow the graph before trusting folder structure.
-5. Start wide, then narrow.
-6. Descriptions need citations; conclusions need discriminators. A conclusion — why something happens, what a unit is for, which intent explains a shape — states one rival explanation and the trace evidence that rules it out.
-
-## Workflow
+## Evidence rules (apply to every step below)
 
-### 1. Orient
+- Use a current index before trusting graph facts: apply `_shared`'s freshness gate once before the first graph claim. After source changes, let an active watcher refresh and use manual reindex only as the documented fallback.
+- Relationship, consumer, and completeness claims must cite a `scip-query` command. Literal local-source claims may cite a native file read instead.
+- Resolve ambiguous symbols before describing behavior — `scip-query code` is the usual tool, but it isn't mandatory when you already have an exact native range.
+- Follow the graph before trusting folder structure. Start wide, then narrow.
+- Descriptions need citations; conclusions need discriminators. A conclusion — why something happens, what a unit is for, which intent explains a shape — must state one rival explanation and the trace evidence that ruled it out.
 
-```bash
-scip-query stats
-scip-query kind-counts
-scip-query system <module-or-scope>
-scip-query outline <entry-file>
-scip-query by-kind function --scope <scope>
-```
+Each `scip-query` command below carries a coverage rating: **complete** (exhaustive) or **bounded** (capped — a follow-up command may be needed to fill in the picture).
 
-This step is complete only when the module files, key symbols, dependencies, and reverse dependencies are mapped.
+## The core workflow
 
-### 2. Trace entry points
+Run these five steps in order. Skip a step only when its evidence is already in hand from an earlier step.
 
-```bash
-scip-query trace <entry-symbol>
-scip-query call-graph <entry-symbol>
-scip-query code <entry-symbol>
-scip-query dataflow <entry-symbol>
-```
+**1. Orient.** Run `stats` (repo-wide size/shape, complete), `kind-counts`, `system <module-or-scope>` (file paths, exported symbols with line ranges, internal/reverse deps, complete), `outline <entry-file>`, and `by-kind function --scope <scope>`.
+Done when: module files, key symbols, dependencies, and reverse dependencies are mapped.
 
-Repeat for important callees until the path reaches side effects, returned values, or terminal outputs.
+**2. Trace entry points.** Run `trace <entry-symbol>` (definition + every reference, bounded), `call-graph <entry-symbol>` (incoming callers, outgoing callees, bounded), `code <entry-symbol>`, `dataflow <entry-symbol>` — repeat for important callees until the path reaches a side effect, a returned value, or a terminal output.
+Done when: the traced path connects entry point to observable effect.
 
-This step is complete only when the explored path connects entry point to observable effect.
+**3. Map dependencies and consumers.** Run `deps <file>`, `rdeps <file>`, `fan-out <file>`, `surface <module>`, `affected <symbol> --json` (transitive closure of symbols that could break if this symbol changes: identities, files, traversal depths, bounded).
+Done when: direct dependencies, public surface, and downstream blast radius are named.
 
-### 3. Map dependencies and consumers
+**4. Follow data and state.** Run `dataflow <symbol-or-variable>` (definition sites, usage sites, producers, consumers, bounded), `slice <symbol-or-variable>`, `slice <symbol-or-variable> --forward`.
+Done when: producers, transformations, storage, and consumers are identified — or explicitly marked unavailable.
 
-```bash
-scip-query deps <file>
-scip-query rdeps <file>
-scip-query fan-out <file>
-scip-query surface <module>
-scip-query affected <symbol>
-```
+**5. Assess risk.** Run `complexity <symbol>`, `complexity-hotspots`, `bottlenecks`, `change-surface <file>` (pre-change briefing: exports, consumers, blast-radius risk), `cycles`, `deep-chains --min-depth 5` (longest condensed dependency-component chains — flags fragile long call paths).
+Done when: the explanation names the risky symbols, or states that no relevant risks appeared.
 
-This step is complete only when direct dependencies, public surface, and downstream blast radius are named.
+## Route by question type
 
-### 4. Follow data and state
+| Question | Commands |
+|---|---|
+| Function behavior | `code`, `hierarchy`, `call-graph`, `dataflow`, `complexity` |
+| User-action flow | `files` or `outline` to find the handler, then `code` and `call-graph` down the path |
+| Safe to change? | `change-surface`, `affected`, `similar` |
+| Module architecture | `system`, `surface`, `deep-chains`, `bottlenecks`, `cycles`, `hotspots` (`hotspots` lists the most-referenced symbols — choke points where any change ripples widely) |
+| Relationship between two units | `coupling`, `similar --plan`, `similar-chains` |
 
-```bash
-scip-query dataflow <symbol-or-variable>
-scip-query slice <symbol-or-variable>
-scip-query slice <symbol-or-variable> --forward
-```
+## Other owned commands
 
-This step is complete only when producers, transformations, storage, and consumers are identified or marked unavailable.
+These four don't have a dedicated workflow step above but come up constantly once you're inside a module — use them as needed, not in sequence:
 
-### 5. Assess risk
+- **`imported-by <symbol>`** — which files import this symbol. Run before changing or removing a shared export, to know exactly which files to check. If the list is empty, confirm with `dead` before deleting rather than trusting the empty result alone.
+- **`unused-imports <file>`** — imports not referenced in that same file. Run on a file you're about to touch, or one a de-bloat pass flagged; remove only entries you've confirmed are safe.
+- **`similar-signatures`** — functions with near-identical type signatures. Run when hunting duplicate-shaped functions to consolidate. This is a *good-with-review* signal — check each match with `code` before merging, don't act on the list alone.
+- **`co-change [file]`** — files that change together in git history with no dependency edge between them: hidden coupling. Run when `change-surface` or `affected` reports a small blast radius but you suspect the graph is missing something. This is also *good-with-review* — a paired file is a prompt to check manually, not proof the current change must touch it too. (`diff-gate`'s `co-change-partner` check is the automated version of this same signal.)
 
-```bash
-scip-query complexity <symbol>
-scip-query complexity-hotspots
-scip-query bottlenecks
-scip-query change-surface <file>
-scip-query cycles
-scip-query deep-chains --min-depth 5
-```
+## Report the exploration
 
-This step is complete only when the explanation includes the risky symbols or states that no relevant risks appeared.
+Cover: overview, entry points, call flow, data flow, dependencies, consumers, risk areas, and the command citation that proves each claim. For every conclusion-bearing claim, name the rival explanation you considered and the evidence that ruled it out. Exploration is complete only when the reader can see what was proven, what remains unverified, and which conclusions rest on a discriminator rather than a single story.
 
-## Question Recipes
+## Deeper references
 
-- Function behavior: `code`, `hierarchy`, `call-graph`, `dataflow`, `complexity`.
-- User action flow: `files` or `outline` for the handler, then `code` and `call-graph` down the path.
-- Safety to change: `change-surface`, `affected`, `similar`.
-- Module architecture: `system`, `surface`, `deep-chains`, `bottlenecks`, `cycles`, `hotspots`.
-- Relationship between units: `coupling`, `similar --plan`, `similar-chains`.
+| Need | Reference |
+|---|---|
+| Entering an unfamiliar language (TypeScript, Python, Java, Scala, Kotlin, Rust, Go, C, C++, Ruby, C#, Visual Basic, Dart, PHP, Clojure/ClojureScript, Vue) and picking the highest-signal commands, including de-bloat sets | `references/language-playbook.md` |
+| Turning exploration evidence into an HTML flow, dependency, data-flow, or blast-radius diagram | `references/diagrams.md` |
 
-## Report
+## Constraint
 
-Report overview, entry points, call flow, data flow, dependencies, consumers, risk areas, and the command citations that prove each claim. For each conclusion-bearing claim, name the rival explanation considered and the evidence that ruled it out. Exploration is complete only when the user can see what was proven, what remains unverified, and which conclusions rest on a discriminator rather than a single story.
+scip-explore's OpenAI-agent interface binds to display name "SCIP Explore" with default prompt "Use $scip-explore to understand this system end to end with SCIP-backed code evidence."