scip-query 0.17.2 → 0.19.0

package/skills/scip-query/SKILL.md

@@ -23,7 +23,7 @@ Load shared mechanics from [`../_shared/SKILL.md`](../_shared/SKILL.md) when you
 | --- | --- | --- |
 | `scip-query status --capabilities` | Show index status for this project | Before routing: confirm the index is fresh. |
 | `scip-query plan-context <target>` | Pre-edit planning context for a symbol, file, or module | Default loop: anchor a plan for the routed skill. |
-| `scip-query diff-gate --json` | Gate the current diff: echo candidates, incomplete migrations, missing co-change partners, unedited twin partners (advisory), uncited doc updates, unused params, new dead symbols; exit 1 on blocking findings | Default loop: the loop is complete only when this passes or is explained. |
+| `scip-query diff-gate --json` | Gate the current diff: architecture regressions plus echo, migration, coordination, doc-drift, unused-param, and new-dead candidates; exit 1 on blocking findings | Default loop: the loop is complete only when this passes or is explained. |
 
 Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only when it is insufficient.
 <!-- END GENERATED SKILL COMMANDS -->
@@ -44,6 +44,7 @@ The loop is complete only when `scip-verify` passes or each remaining finding ha
 | --- | --- | --- |
 | Understand a system before answering or editing | `scip-explore` | `system`, `trace`, `call-graph`, `dataflow` |
 | Root-cause a bug or regression | `scip-debug` | `trace`, `dataflow`, `change-surface` |
+| Diagnose the design flaw behind a family of recurring bugs | `scip-root-cause` | `co-change`, `similar`, `refs` |
 | Turn a report into a fix packet | `scip-triage-issue` | `files`, `trace`, `affected` |
 | Create a code flow, dependency, or blast-radius diagram | `scip-diagram` | `call-graph`, `dataflow`, `affected` |
 | Plan a feature, fix, or refactor | `scip-concrete-plan` | `plan-context` |
@@ -72,6 +73,7 @@ Routing is complete only when one owning skill is selected or the task is small
 
 - "Is this implementation real / does it actually work" → `scip-integrity-audit`; "is this well-organized" → `scip-maintainability`; same-name drifted twins specifically → `scip-twin-drift`.
 - One change → `scip-concrete-plan`; a program of changes with delegation → `scip-conductor`.
+- One failing behavior → `scip-debug`; a family of similar bugs whose fixes keep recurring, or "what is really wrong with this system" backed by bug history → `scip-root-cause`; structure smells with no bug evidence → `scip-maintainability`.
 
 - Use `scip-cleanup-audit` for reports, ranking, confirmation, or recent AI-residue triage without edits.
 - Use `scip-cleanup-improve` when the user asks to fix, improve, continue cleaning, or raise health autonomously.
@@ -105,6 +107,7 @@ Top commands per routed skill, generated from each skill's own `commands:` front
 | `scip-maintainability` | `scip-query stats`, `scip-query system <scope>`, `scip-query surface <scope>` |
 | `scip-probe-reachability` | `scip-query outline <file> --signatures`, `scip-query code <symbol>`, `scip-query trace <symbol>` |
 | `scip-react-maintainability` | `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-root-cause` | `scip-query trace <mechanism-symbol>`, `scip-query co-change <fix-site-file>`, `scip-query system <system-scope>` |
 | `scip-setup` | `scip-query setup --json`, `scip-query doctor`, `scip-query status --json` |
 | `scip-tla-model-system` | `scip-query tla scaffold <file>`, `scip-query tla verify <spec>`, `scip-query tla instrument <spec>` |
 | `scip-triage-issue` | `scip-query files <issue-term>`, `scip-query trace <entry-or-error-symbol>`, `scip-query code <entry-or-error-symbol>` |

package/skills/scip-root-cause/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: scip-root-cause
+description: Diagnose the design flaw behind a family of related bugs with scip-query evidence. Use when similar bugs keep recurring, the same subsystem keeps needing patches, or the user lists fixed/observed bugs and asks what is really wrong; produces a falsifiable flaw diagnosis, a latent-instance hunt, and the least invasive remedy that kills the class.
+commands:
+  - template: "scip-query trace <mechanism-symbol>"
+    when: "Assemble the family: mechanism and violated invariant for each bug."
+  - template: "scip-query co-change <fix-site-file>"
+    when: "Assemble the family: files that historically changed with each fix site."
+  - template: "scip-query system <system-scope>"
+    when: "Define the system: real responsibilities, files, dependencies in and out."
+  - template: "scip-query similar <fixed-symbol> --json --full"
+    when: "Predict: hunt latent instances among sibling implementations of the fixed code."
+  - template: "scip-query refs <invariant-carrier>"
+    when: "Predict: every site that touches the violated invariant's state."
+  - template: "scip-query affected <remedy-symbol> --json"
+    when: "Choose the rung: blast radius of the candidate remedy."
+---
+
+# scip-root-cause
+
+Use this skill 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. `scip-debug` takes one failure to one minimal fix; `scip-maintainability` finds structural smells without bug evidence; this skill starts from the evidence that patching has not worked — the same kind of bug keeps coming back — and asks what the system's design gets wrong.
+
+Load shared mechanics from [`../_shared/SKILL.md`](../_shared/SKILL.md).
+
+<!-- BEGIN GENERATED SKILL COMMANDS -->
+## Commands for this skill
+
+| Command | Purpose | When |
+| --- | --- | --- |
+| `scip-query trace <mechanism-symbol>` | Trace a symbol: definition + all references | Assemble the family: mechanism and violated invariant for each bug. |
+| `scip-query co-change <fix-site-file>` | Files that change together in git history without a dependency edge — hidden coupling candidates | Assemble the family: files that historically changed with each fix site. |
+| `scip-query system <system-scope>` | Full module map: files, symbols, deps in/out | Define the system: real responsibilities, files, dependencies in and out. |
+| `scip-query similar <fixed-symbol> --json --full` | Find heuristic function similarity candidates from callee fingerprints | Predict: hunt latent instances among sibling implementations of the fixed code. |
+| `scip-query refs <invariant-carrier>` | Find all files referencing a symbol | Predict: every site that touches the violated invariant's state. |
+| `scip-query affected <remedy-symbol> --json` | Transitive closure of symbols that could break if this symbol changes | Choose the rung: blast radius of the candidate remedy. |
+
+Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only when it is insufficient.
+<!-- END GENERATED SKILL COMMANDS -->
+
+## 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`, `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 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. 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-concrete-plan` for implementation — this skill does not edit application code.
+
+## 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 `scip-tla-model-system`.
+
+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-tla-model-system for <property>>
+```
+
+Hand the diagnosis to `scip-concrete-plan`: the flaw and invariants become its Definitions & Invariants, the family table and hunt results become premises, and the surviving-counterexample record seeds its attack pass.
+
+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-root-cause/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "SCIP Root Cause"
+  short_description: "Diagnose the design flaw behind a family of recurring bugs"
+  default_prompt: "Use scip-query to trace a family of related bugs to the design flaw that produces them: retrodict every member, hunt the latent instances the flaw predicts, and propose the least invasive remedy that eliminates the class."

package/skills/scip-tla-model-system/SKILL.md

@@ -21,19 +21,17 @@ Use this skill when a TypeScript system needs a TLA+ model tied to code evidence
 Load shared mechanics from [`../_shared/SKILL.md`](../_shared/SKILL.md).
 
 <!-- BEGIN GENERATED SKILL COMMANDS -->
-
 ## Commands for this skill
 
-| Command                                            | Purpose                                                                                                                                                                                  | When                                                                                    |
-| -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
-| `scip-query tla scaffold <file>`                   | TLA+ model workflow: verify a model and mapping contract, scaffold a draft model from indexed code, generate a trace recorder, or check a recorded trace against the next-state relation | Start here for a new model: derive a draft spec, config, and mapping from indexed code. |
-| `scip-query tla verify <spec>`                     | TLA+ model workflow: verify a model and mapping contract, scaffold a draft model from indexed code, generate a trace recorder, or check a recorded trace against the next-state relation | Mechanical conformance: referents, reads/writes, calls, and the model checker.          |
-| `scip-query tla instrument <spec>`                 | TLA+ model workflow: verify a model and mapping contract, scaffold a draft model from indexed code, generate a trace recorder, or check a recorded trace against the next-state relation | Generate a trace recorder plus wiring sites for each mapped action.                     |
-| `scip-query tla trace-check <spec> --trace <file>` | TLA+ model workflow: verify a model and mapping contract, scaffold a draft model from indexed code, generate a trace recorder, or check a recorded trace against the next-state relation | Semantic conformance: check a recorded execution against the model's Next relation.     |
-| `scip-query tla fetch-tools`                       | TLA+ model workflow: verify a model and mapping contract, scaffold a draft model from indexed code, generate a trace recorder, or check a recorded trace against the next-state relation | Download the pinned tla2tools.jar into the cache when the checker is unavailable.       |
+| Command | Purpose | When |
+| --- | --- | --- |
+| `scip-query tla scaffold <file>` | TLA+ model workflow: verify a model and mapping contract, scaffold a draft model from indexed code, generate a trace recorder, or check a recorded trace against the next-state relation | Start here for a new model: derive a draft spec, config, and mapping from indexed code. |
+| `scip-query tla verify <spec>` | TLA+ model workflow: verify a model and mapping contract, scaffold a draft model from indexed code, generate a trace recorder, or check a recorded trace against the next-state relation | Mechanical conformance: referents, reads/writes, calls, and the model checker. |
+| `scip-query tla instrument <spec>` | TLA+ model workflow: verify a model and mapping contract, scaffold a draft model from indexed code, generate a trace recorder, or check a recorded trace against the next-state relation | Generate a trace recorder plus wiring sites for each mapped action. |
+| `scip-query tla trace-check <spec> --trace <file>` | TLA+ model workflow: verify a model and mapping contract, scaffold a draft model from indexed code, generate a trace recorder, or check a recorded trace against the next-state relation | Semantic conformance: check a recorded execution against the model's Next relation. |
+| `scip-query tla fetch-tools` | TLA+ model workflow: verify a model and mapping contract, scaffold a draft model from indexed code, generate a trace recorder, or check a recorded trace against the next-state relation | Download the pinned tla2tools.jar into the cache when the checker is unavailable. |
 
 Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only when it is insufficient.
-
 <!-- END GENERATED SKILL COMMANDS -->
 
 ## Choose the Slice

package/skills/scip-twin-drift/SKILL.md

@@ -29,7 +29,7 @@ Load shared mechanics from [`../_shared/SKILL.md`](../_shared/SKILL.md).
 | `scip-query duplicate-bodies --json --full` | Find exact duplicate small-body candidates across files | Cross-check: IDENTICAL groups are duplicate-bodies' job, not this skill's. |
 | `scip-query code <symbol>` | Read the source code for a symbol (bounded to its definition range) | Classify a divergent group: read every member's body. |
 | `scip-query refs <symbol>` | Find all files referencing a symbol | Pick the canonical twin: consumer count per member. |
-| `scip-query diff-gate --json` | Gate the current diff: echo candidates, incomplete migrations, missing co-change partners, unedited twin partners (advisory), uncited doc updates, unused params, new dead symbols; exit 1 on blocking findings | Verify: the twin-partner check must not flag a one-sided fix. |
+| `scip-query diff-gate --json` | Gate the current diff: architecture regressions plus echo, migration, coordination, doc-drift, unused-param, and new-dead candidates; exit 1 on blocking findings | Verify: the twin-partner check must not flag a one-sided fix. |
 
 Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only when it is insufficient.
 <!-- END GENERATED SKILL COMMANDS -->

package/skills/scip-verify/SKILL.md

@@ -30,7 +30,7 @@ Load shared mechanics from [`../_shared/SKILL.md`](../_shared/SKILL.md).
 | `scip-query doctor` | Diagnose config, index freshness, dependency readiness, and project capabilities | Prove the workspace: index freshness and dependency readiness. |
 | `scip-query status --capabilities` | Show index status for this project | Prove the workspace: which evidence and verification capabilities are available. |
 | `scip-query diff-impact --json` | Compute changed symbols and downstream consumers from current git diff | Assess the diff: changed symbols and downstream consumers. |
-| `scip-query diff-gate --json` | Gate the current diff: echo candidates, incomplete migrations, missing co-change partners, unedited twin partners (advisory), uncited doc updates, unused params, new dead symbols; exit 1 on blocking findings | Run the gate: the primary blocker for diff-specific risk. |
+| `scip-query diff-gate --json` | Gate the current diff: architecture regressions plus echo, migration, coordination, doc-drift, unused-param, and new-dead candidates; exit 1 on blocking findings | Run the gate: the primary blocker for diff-specific risk. |
 | `scip-query health --baseline` | Composite codebase health report with prioritized action list | Check health: compare findings against the committed baseline. |
 | `scip-query doc-drift --json --full` | Stale-doc candidates: code the doc references or co-changed with kept changing after the doc stopped | Check docs: run when docs, AGENTS.md, or command surfaces changed. |
 
@@ -44,6 +44,7 @@ Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only
 3. Run every postcheck that matches the actual edit, not only the check you expected to need.
 4. If `.scipquery.json` or suppressions changed, run `scip-query config-validate`.
 5. Prefer fixing findings. Suppress only intentional design, compatibility shims, framework entry points, or accepted false positives with a specific reason.
+6. A PASS ends scrutiny, so it must survive refutation first: construct the cheapest checks that could still break this diff and run them before claiming PASS. A FAIL needs no refutation — report it with the evidence.
 
 ## Flow
 
@@ -115,12 +116,24 @@ scip-query self-audit
 
 This step is complete only when changed documentation and config surfaces are checked or explicitly out of scope.
 
+### 6. Refute the PASS
+
+A PASS is the verdict nobody re-checks — attack it before making it. Construct at least two refutation attempts and run the cheapest check that would expose each. Prefer executed probes (run the consumer's test, invoke the command, feed the edge input) over argued ones. Pick attacks that fit the diff:
+
+- an unexercised consumer: a caller in `diff-impact` output whose tests did not run — run them, or trace the contract it depends on;
+- an unexercised input: an edge the changed code newly handles or newly rejects — execute it;
+- the intent gap: one case the stated goal implies that the diff does not visibly cover — find where it is handled or show it missing.
+
+Record every attempt; an attempt that breaks the diff converts the verdict to FAIL with a finding, and the attempt stays in the record either way.
+
+This step is complete only when every refutation attempt has an executed result.
+
 ## Report
 
 End with:
 
 ```markdown
-Verification: PASS/FAIL
+Verification: PASS/FAIL — <n> postchecks, <m> refutation attempts, <k> broke
 
 Environment:
 
@@ -144,11 +157,15 @@ Health/docs/config:
 
 - <commands and results>
 
+Refutation attempts:
+
+- R1: <attack> → survived (evidence) | broke (finding)
+
 Remaining risk:
 
 - <accepted findings, unavailable capabilities, or checks not run>
 ```
 
-Do not claim ready-to-ship unless freshness is `fresh` after the final edit and diff-gate is passed or fully explained.
+Do not claim ready-to-ship unless freshness is `fresh` after the final edit, diff-gate is passed or fully explained, and the PASS survived every refutation attempt.
 
 - `dead`/`new-dead` correctly resolve `import type` consumers, tsconfig `paths` aliases, pnpm/npm/yarn workspace cross-package imports, and Vue `<script setup>` composables. The one residual gap is a same-named symbol reached only through a re-exporting barrel file in a workspace package; that shape self-labels `unconfirmed (cross-package ambiguous-name resolution gap)` in the finding — treat only that label as unconfirmed until `refs` agrees. See the Detector Reliability section in `../_shared/SKILL.md`.