scip-query 0.19.5 → 0.19.8

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

@@ -0,0 +1,130 @@
+# React and Vue maintainability
+
+Reviews React and Vue frontends as maintainable systems: React as
+components, hooks, JSX structure, and behavior lifecycles; Vue as single-file
+components, templates, scripts, styles, external scripts, components, and
+composables. Both follow the same four-step workflow below; framework-
+specific commands and definitions are called out per step.
+
+## Definitions
+
+- **Component duplicate candidate** (React or Vue) — a pair or group of
+  rendered structures that repeat the same user-facing arrangement,
+  controls, states, props, or data-presentation shape enough that a shared
+  component may reduce drift.
+- **React hook candidate** — a pair or group of component behaviors that
+  repeat the same state lifecycle, effects, requests, validation,
+  persistence, callback policy, or derived-data rule enough that a shared
+  hook may preserve behavior better.
+- **Vue composable candidate** — a pair or group of script behaviors that
+  repeat the same state lifecycle, effects, requests, validation,
+  persistence, or derived-data policy enough that a shared composable may
+  preserve behavior better.
+- **Large component/view pressure** — one component, SFC, or linked view
+  file contains several kinds of knowledge that change for different
+  reasons. A large file is review pressure, not proof of duplication, by
+  itself.
+
+## Step 1 — Bound and scan
+
+Pick the narrowest source root, feature area, or changed-file scope that
+still includes likely reuse partners.
+
+**Vue only:** if component references, imported composables, script blocks,
+or linked external scripts matter, run `scip-query augment-vue --project
+<path-to-tsconfig>` first — it adds compiler-resolved Vue SFC references to
+the SQLite index using Volar (complete coverage) and must run before
+scanning.
+
+Then run, all uncapped with `--full --json`:
+
+**React:**
+```
+scip-query react-component-duplicates --scope <scope> --full --json
+scip-query react-hook-candidates --scope <scope> --full --json
+scip-query react-large-component-pressure --scope <scope> --full --json
+scip-query recent-duplicates --scope <scope> --full --json
+scip-query health --scope <scope> --json
+```
+
+**Vue:**
+```
+scip-query vue-component-duplicates --scope <scope> --full --json
+scip-query vue-composable-candidates --scope <scope> --full --json
+scip-query vue-large-view-pressure --scope <scope> --full --json
+scip-query recent-duplicates --scope <scope> --full --json
+scip-query health --json
+```
+
+Every `*-duplicates`/`*-candidates`/`*-pressure` command has bounded
+coverage — `--full` is required for the uncapped scan.
+`react-component-duplicates`/`vue-component-duplicates` derive structural
+similarity from tags, props, events, and bindings (React) or tags, bindings,
+slots, and directives (Vue). `recent-duplicates` finds directional pairs:
+recent code that re-implements established callable, React, or Vue code.
+`health` gives a composite codebase health report (score, findings,
+priorities, baselines, coverage notes) scoped to the frontend area.
+
+**Complete when:** command scope, counts, and uncapped/full status are
+recorded.
+
+## Step 2 — Cross-check candidates
+
+- **Component-duplicate-only finding** — inspect for a shared presentational
+  component or existing component reuse.
+- **Hook/composable-candidate-only finding** — inspect for shared behavior,
+  lifecycle, request, validation, persistence, event, or derived-state
+  policy.
+- **Both overlap** — inspect for a feature-level concept that needs both a
+  component and a hook/composable boundary.
+- **Large-component/view-only finding** — split by reason to change, not by
+  line count.
+
+Use `scip-query outline <file>`, `deps <file>`, `rdeps <file>`,
+`similar-files --scope <scope>`, and (React) `similar
+<closest-existing-component-or-hook>` / (Vue) `recent-duplicates --scope
+<scope> --full --json` to validate candidates.
+
+**Complete when:** each top candidate is classified as reuse, extract,
+split, skip, or blocked.
+
+## Step 3 — Act on findings
+
+Prefer reuse over extraction.
+
+- **React:** extract a component for repeated UI structure, states, props,
+  slots/children, or design-system composition; extract a hook for repeated
+  state, effects, requests, subscriptions, memoized derivations, callbacks,
+  or persistence.
+- **Vue:** extract a component for repeated template structure, props,
+  slots, states, or design-system composition; extract a composable for
+  repeated state, lifecycle, requests, validation, persistence, derived
+  data, or event policy.
+
+Keep domain-specific/essential variation at the call site rather than
+abstracting it away.
+
+Anti-patterns to avoid as a side effect of acting on a finding: do not
+create boolean-soup APIs or wrapper components with no policy. Shared
+design-system primitives, icons, labels, route names, test IDs, or CSS
+utilities alone are not sufficient evidence to justify a duplicate/hook/
+composable claim. Similar JSX/templates with different domain lifecycles may
+justify a presentational component but does not justify a shared hook or
+composable.
+
+**Complete when:** the chosen action reduces future drift without creating
+boolean-soup APIs or wrapper components with no policy.
+
+## Step 4 — Verify
+
+Invoke `scip-verify` and use its authoritative postcheck table, including
+the applicable React/Vue, extraction, duplicate, parameter, wrapper,
+passthrough, and stale-abstraction checks.
+
+**Complete when:** acted-on candidate pairs disappear, weaken materially, or
+are explicitly accepted as essential variation.
+
+## Report
+
+Executive read, command evidence, candidate groups, recommended action,
+post-change proof, and remaining accepted variation.

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

@@ -0,0 +1,154 @@
+# Integrity: is this real?
+
+Structural review (`references/maintainability.md`) asks "is this well
+organized?" This drill set asks **"is this real?"** — it hunts decorative
+checkers, adapters written against imagined data, features that have
+silently never run, and numbers nobody ever recomputed.
+
+Command shortlist: `refs <symbol>`, `code <symbol>`, `trace <symbol>`,
+`call-graph <symbol>`, `twin-drift -s <scope> --json`,
+`twin-ab <symbolA> <symbolB>`, `outline <file> --signatures`,
+`decorative-checkers -s <scope> --json`, `not-implemented -s <scope> --json`,
+`test-quality -s <scope> --json`.
+
+## The stance
+
+A green result you have never seen fail is unverified: every status word,
+banner, and metric is testimony from the code, not evidence about the code,
+so cross-examine the producer before believing it. The most dangerous code
+is not broken code; it is code that reports success without doing the work.
+
+## Run all five drills over the chosen scope
+
+### Drill 1 — Falsify every checker
+
+Inventory everything in scope that accepts/rejects, passes/fails, or
+validates (checkers, gates, verifiers, validators) by finding producers with
+`refs`/`call-graph` on the status words in their output.
+
+For each one found, construct an input that MUST fail — a wrong binding, a
+corrupt file, an impossible value — and run it. A checker that passes its
+should-fail input is decorative and must be filed as a defect, not a note.
+
+Before filing, attempt the defense: an accusation triggers a rewrite, so
+search for the failure exit the drill may have missed — a config-gated
+branch, an async rejection, or one-hop delegation (the calibration's known
+noise archetypes). File the defect with the executed should-fail input
+attached and the defense attempt noted; a defense that succeeds clears the
+checker and stays in the record as its witness.
+
+**Complete when:** every checker in scope has been witnessed rejecting a
+constructed should-fail input, or is listed with a reason it cannot be.
+
+Mechanized by `scip-query decorative-checkers`, which finds
+`validate*`/`verify*`/`check*`/`assert*`/`is*`/`has*` callables with no
+reachable failure exit anywhere in their body. Run it first to shortlist
+candidates before hand-constructing should-fail inputs. It was calibrated
+2026-07-03 against two external repos, is standalone-only, and its noise
+archetypes past one-hop delegation are documented in
+`docs/validation/2026-07-03-integrity-detector-calibration.md`.
+
+### Drill 2 — Diff every adapter against captured reality
+
+For each parser/adapter of an external format (tool output, XML/JSON
+schemas, protocol messages), obtain ONE real sample from the actual source
+and diff it against the code's assumptions and the tests' fixtures. Ask of
+every fixture whether it was generated from reality or imagined. A parser
+and a hand-written fixture can validate each other's shared hallucination
+indefinitely, so fixture-vs-code agreement alone is not proof of
+correctness.
+
+**Complete when:** every adapter has been checked against at least one
+captured-real sample.
+
+### Drill 3 — Autopsy every fallback
+
+For every catch block, `??` fallback, and degraded mode in scope, produce an
+execution witness (a test, a probe, a log) that the PRIMARY path runs —
+because a primary path that has never worked looks identical to a healthy
+fallback. Use the probe-reachability mode in `scip-diagnose` for parser/AST
+branch reachability
+when autopsying fallbacks. A fallback that always fires means the feature
+above it is dead — "date of death: birth."
+
+**Complete when:** every fallback's primary path has a witness or a filed
+defect.
+
+Mechanized by `scip-query not-implemented`, which finds reachable placeholder
+stubs (`throw new Error('not implemented')`, TODO-comment + return-default,
+empty bodies) that a real caller, entry surface, or package-surface export
+can actually reach — distinguishing "primary path never built" from `dead`'s
+"primary path built but unreferenced." Standalone-only (calibrated
+2026-07-03; 0 live findings on two external repos post-fix). A clean run
+means "nothing this shape found," not proof that every fallback's primary
+path is live.
+
+### Drill 4 — Hand-compute every metric twice
+
+For each number the system reports (scores, counts, estimates), pick two
+concrete instances, compute the expected value by hand from first
+principles, and compare — off-by-a-factor errors (double counting, inflated
+estimates) survive for years when nobody recomputes a single sample.
+
+**Complete when:** every reported metric has two hand-verified samples.
+
+### Drill 5 — Cross-examine same-concept twins
+
+Where one concept is computed in more than one place, feed both
+implementations the same input and require the same answer. `twin-drift`
+finds same-name cases mechanically; same-concept-different-name pairs must be
+traced via `refs` and compared via `code` (see `references/twin-drift.md`
+for the full drift-classification workflow once a pair is found).
+
+Once a twin pair is identified, `scip-query twin-ab <symbolA> <symbolB>`
+scaffolds a table-driven vitest file that imports both implementations and
+asserts equal output — fill in the input table and run it. Disagreement
+between twins means at least one is wrong — determine which before
+consolidating them.
+
+**Complete when:** every discovered twin pair has been compared on a shared
+input.
+
+## Severity
+
+Rank findings by what the failure does to a user who trusted the output: a
+decorative checker or false "verified" banner outranks everything; a
+dead-but-fallbacked feature outranks a wrong metric; a wrong metric outranks
+structural mess. Route structural findings to `references/maintainability.md`
+instead of reporting them here — they are real but they are not lies.
+
+## Reporting
+
+File each finding with: the claim as displayed, the producer (file:line),
+the drill that exposed it, the should-fail input or real sample used, and the
+fix. The audit is complete only when every drill's exit criterion is met for
+the scope, and every defect found has a regression artifact (a test,
+fixture, or model) that fails on the pre-fix behavior.
+
+End with a derived verdict, not an impression:
+
+```
+Integrity: <scope> — <c> checkers witnessed failing, <a> adapters diffed
+against reality, <f> fallback primaries witnessed live, <m> metrics
+recomputed, <t> twins compared; <d> defects filed, <u> unverifiable (reasons)
+```
+
+A suspect scope that produces zero defects is itself a claim: state what
+made the suspicion wrong, or rerun the drill that should have caught it.
+
+## Your own regression artifacts are in scope too
+
+A regression artifact that doesn't actually assert anything, or asserts the
+same literal it stubbed into its own mock, is a fake witness — the same
+"reports success without doing the work" failure mode this drill set hunts
+in production code, just relocated to the test suite.
+
+Run `scip-query test-quality -s <scope>` over the audit's own regression
+artifacts (and periodically over the suite at large) to catch fake
+witnesses. It catches assertion-free test bodies, a skipped-test ledger with
+git-blame age (a skip with no fix date attached is a claim nobody is
+checking), and mock-echo (a test that only proves its own stub).
+Standalone-only with mixed precision by sub-check (calibrated 2026-07-03):
+assertion-free and skipped are high-precision; mock-echo is intentionally
+low-precision (syntactic same-literal matching, not dataflow) — treat its
+output as a reviewed candidate list, not a verdict.

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

@@ -0,0 +1,162 @@
+# 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

@@ -0,0 +1,104 @@
+# 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 --json --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 --json --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

@@ -0,0 +1,52 @@
+---
+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

@@ -0,0 +1,4 @@
+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."