scip-query 0.19.4 → 0.19.6

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

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 | When |
-| --- | --- | --- |
-| `scip-query outline <file> --signatures` | Tree view of symbols in a file, with line ranges | 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) | Enumerate branches: read each branch condition's exact node-type check. |
-| `scip-query trace <symbol>` | Trace a symbol: definition + all references | 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.
 
@@ -86,6 +70,7 @@ Branches:
 | --- | --- | --- | --- |
 
 Findings:
+
 - <branch> — dead branch / wrong node-type string — fix: <direction>
 ```
 

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.