scip-query 0.17.1 → 0.18.0

package/skills/scip-concrete-plan/SKILL.md

@@ -1,22 +1,24 @@
 ---
 name: scip-concrete-plan
-description: Plan code changes with scip-query evidence and testable design. Use for non-trivial implementation, refactor, migration, API, or bug-fix plans before editing code; require source citations, reuse audit, test seams, side-effect boundaries, contracts, and verification.
+description: Plan code changes with scip-query evidence and testable design. Use for non-trivial implementation, refactor, migration, API, or bug-fix plans before editing code; require contextual definitions, cited premises, reuse audit, test seams, counterexample attacks, and a derived verdict.
 commands:
   - template: "scip-query status --capabilities"
     when: "Discover: confirm the index is fresh before citing graph facts."
   - template: "scip-query plan-context <target>"
     when: "Discover: anchor the plan with pre-edit context for the target."
   - template: "scip-query refs <symbol>"
-    when: "Reuse audit: find existing consumers before proposing a new unit."
+    when: "Premises: enumerate every writer and reader of a touched state surface; reuse audit: find existing consumers."
+  - template: "scip-query dataflow <symbol-or-variable>"
+    when: "Premises: producers and consumers backing a state-authority premise."
   - template: "scip-query code <symbol>"
-    when: "Reuse audit: read source before citing a behavior claim."
+    when: "Premises: read source before citing a behavior claim."
   - template: "scip-query trace <symbol>"
     when: "Verify the plan: rerun source-producing context for cited targets."
 ---
 
 # Concrete Plan
 
-Use this skill to write an implementation plan that another agent can execute without guessing. A concrete plan is a dated Markdown checklist whose code claims come from scip-query evidence and whose design makes the intended behavior easy to test before it is easy to ship.
+Use this skill to write an implementation plan that another agent can execute without guessing and a reviewer can check without re-deriving. A concrete plan is a certificate: a dated Markdown document whose conclusion — ready to implement — is derived from numbered, source-cited premises, defended against constructed counterexamples, and shaped so the intended behavior is easy to test before it is easy to ship.
 
 Load shared mechanics from [`../_shared/SKILL.md`](../_shared/SKILL.md) when you need lookup tips, command families, postchecks, or subagent rules.
 
@@ -27,8 +29,9 @@ Load shared mechanics from [`../_shared/SKILL.md`](../_shared/SKILL.md) when you
 | --- | --- | --- |
 | `scip-query status --capabilities` | Show index status for this project | Discover: confirm the index is fresh before citing graph facts. |
 | `scip-query plan-context <target>` | Pre-edit planning context for a symbol, file, or module | Discover: anchor the plan with pre-edit context for the target. |
-| `scip-query refs <symbol>` | Find all files referencing a symbol | Reuse audit: find existing consumers before proposing a new unit. |
-| `scip-query code <symbol>` | Read the source code for a symbol (bounded to its definition range) | Reuse audit: read source before citing a behavior claim. |
+| `scip-query refs <symbol>` | Find all files referencing a symbol | Premises: enumerate every writer and reader of a touched state surface; reuse audit: find existing consumers. |
+| `scip-query dataflow <symbol-or-variable>` | Reference-level dataflow: definition sites, usage sites, producers, consumers | Premises: producers and consumers backing a state-authority premise. |
+| `scip-query code <symbol>` | Read the source code for a symbol (bounded to its definition range) | Premises: read source before citing a behavior claim. |
 | `scip-query trace <symbol>` | Trace a symbol: definition + all references | Verify the plan: rerun source-producing context for cited targets. |
 
 Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only when it is insufficient.
@@ -39,9 +42,14 @@ Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only
 1. Start with `scip-query status --capabilities`; reindex only when freshness is `stale`, `missing`, or `unknown`.
 2. Anchor the plan with `scip-query plan-context <target>`. If the target is not indexed, record that fact and use scip-query for every code-adjacent claim it can answer.
 3. Put the plan in `docs/plans/YYYY-MM-DD-<short-name>.md`.
-4. Every code step includes a `Source` field naming the scip-query command that produced the path, line range, and behavior claim.
-5. Every behavior-changing step includes a testability design: test seam, injected dependencies, pure core, side-effect boundary, and validation.
-6. Do not propose a new helper, wrapper, type, parameter, config flag, component, hook, or module until the reuse audit proves reuse or extension is not the better move.
+4. Define every load-bearing concept contextually and state every invariant in `iff` or `must always` form. A definition without referents (a `Source:` line) is a guess.
+5. Evidence lives in numbered premises (`P1`, `P2`, ...), each with a `Source` naming the scip-query command that produced it. Every shared-state surface the plan touches gets a state-authority premise enumerating its complete writer and reader sets.
+6. Steps and defenses cite the premises they depend on. A claim no premise supports is either new evidence to gather or an explicit `ASSUMPTION` — never silent.
+7. Do not propose a new helper, wrapper, type, parameter, config flag, component, hook, or module until the reuse audit proves reuse or extension is not the better move.
+8. Every behavior-changing step includes a testability design: test seam, injected dependencies, pure core, side-effect boundary, and validation.
+9. Attack entries must be constructed scenarios — actor, starting state, sequence — and each ends in a recorded outcome: `HELD` citing the defending step and premises, or `HOLE` with its repair step or accepted reason. An assertion of absence ("no new shared mutable state") is not a defense; it cannot fail, so it cannot catch anything.
+10. Installing an enforcer — trigger, constraint, guard, gate — opens an enforcement window: every existing writer in the relevant state-authority premise must be brought into compliance in the same or an earlier step, or the window recorded as an accepted hole. Every step declares `Deployable`.
+11. The verdict is derived, not asserted: `PLANNED-COMPLETE` only when the coverage matrix has no blank rows and every attack ends in `HELD` with citations or an accepted hole. An attack record where nothing ever broke is a red flag — attacks run against a draft should find holes; if none did, rerun the pass as falsification, preferably in a fresh subagent context.
 
 ## Planning Terms
 
@@ -53,6 +61,16 @@ A side-effect boundary is the edge where deterministic program decisions meet fi
 
 A contract is the stable promise one code unit exposes to another, including accepted inputs, returned outputs, errors, timing expectations, and side effects that callers may rely on.
 
+An invariant is a property of the changed system that must hold at every observable moment; what makes it load-bearing is that attacks are judged against it and the final verdict is derived from whether it survives them all.
+
+A premise is a numbered, source-cited statement of fact about the current code; what makes it a premise rather than a note is that steps and defenses cite it by ID, so a false premise is traceable to everything built on it.
+
+A state-authority premise is a premise that enumerates the complete writer and reader sets of one shared state surface; what makes it powerful is that "complete" is falsifiable with `refs` and `dataflow`, turning a forgotten write path from an unknowable into a checkable omission.
+
+A counterexample attack is a concrete actor, starting state, and action sequence constructed to violate an invariant; what makes it evidence is that its defense cites premises and steps, so "we considered failure" becomes "this specific failure is blocked here."
+
+An enforcement window is the interval between the step that installs an invariant enforcer and the step that brings the last existing writer into compliance; what makes it dangerous is that during it, every unupdated writer fails the new check in production, so the plan that adds safety is itself the outage.
+
 ## Workflow
 
 ### 1. Discover
@@ -64,22 +82,50 @@ scip-query status --capabilities
 scip-query plan-context <target>
 ```
 
-Use the shared reference for follow-up commands. Fill three gates before designing:
+Use the shared reference for follow-up commands. Fill four gates before designing:
 
 ```markdown
 ## Goal
 What the user is trying to accomplish and what done looks like for them.
 
+## Definitions & Invariants
+For each load-bearing concept: its wider class, then the one trait that causally
+explains its other traits in this codebase — with the referents. Then the
+invariants the change must preserve, in iff / must-always form.
+
 ## Current State
-The affected end-to-end flow, with scip-query citations for entry points, callers, data flow, dependencies, downstream impact, and non-obvious invariants.
+A short narrative of the affected end-to-end flow. Every factual sentence
+cites a premise by ID.
 
 ## Reuse Audit
-For every new symbol or file being considered: reuse target, extension target, or evidence-backed reason new code is justified.
+For every new symbol or file being considered: reuse target, extension target,
+or evidence-backed reason new code is justified.
 ```
 
-This step is complete only when the plan can explain the current flow, its consumers, and every proposed new unit's reuse decision with citations.
+Definition discipline: place the concept in its wider class, then name the essential trait — the one that makes the concept's other traits in this codebase possible and explains them. Do not label genus or differentia; write it as prose. Ban circular and synonym definitions ("the refresh coordinator coordinates refreshes" defines nothing). Any new term the plan introduces gets defined the same way. Good definitions condense: they imply the concept's other traits instead of listing them, and derived requirements fall out of them — if restore is defined as the inverse of cancel, then the privilege to restore must not be weaker than the privilege to cancel, and a plan that gates them asymmetrically must defend that asymmetry.
+
+This step is complete only when the concepts are defined with referents, the invariants are stated formally, and every proposed new unit has a reuse decision with citations.
+
+### 2. Establish Premises
 
-### 2. Shape for Tests
+Number every fact the plan depends on:
+
+```markdown
+## Premises
+
+- P1. <current behavior fact> — Source: `scip-query code <symbol>`
+- P2. Writers of `<state surface>`: <complete list>. Readers: <complete list>.
+  — Source: `scip-query refs <symbol>` + `scip-query dataflow <symbol>`
+- P3. ASSUMPTION: <belief the evidence cannot yet confirm, and what would confirm it>
+```
+
+State-authority rule: for every state surface the plan touches — database column, store field, event topic, endpoint, cache entry — write one premise enumerating its complete writer and reader sets. Completeness comes from `refs` and `dataflow`, not memory.
+
+Why this premise class exists: a sprint-restore plan hardened `restore()` and the cancellation path but never enumerated the writers of sprint status. Review found `PATCH /sprints/:id` could set `status: 'active'` around every restore invariant, and transition automations wrote `sprintId` straight past the new membership guard — two of that review's five ship-blockers, both sitting in the writer list one `refs` call would have produced. With a state-authority premise, each writer in the list must be visited by an attack; without it, the side doors are invisible until review.
+
+This step is complete only when every state surface named in any phase has a state-authority premise and every remaining unknown is an explicit `ASSUMPTION`.
+
+### 3. Shape for Tests
 
 Before writing implementation phases, add:
 
@@ -101,7 +147,7 @@ Plan the code so tests can call the pure core directly and exercise the side-eff
 
 This step is complete only when every changed behavior has a named test seam and the plan makes clear which logic can be tested without real external services.
 
-### 3. Design the Checklist
+### 4. Design the Checklist
 
 Write phases in execution order. Keep each phase deployable or explicitly mark why it is not. Use this step format:
 
@@ -109,7 +155,8 @@ Write phases in execution order. Keep each phase deployable or explicitly mark w
 ### N.M - Imperative title
 
 - [ ] **File**: `path/to/file.ts:LINE-LINE`
-- **Source**: `scip-query <command>`
+- **Premises**: P<n>, P<m>
+- **Deployable**: yes | no — <reason> | part of single-deploy group <name>
 - **What**: Current behavior verified from source.
 - **Change**: Exact edit to make.
 - **Testability**:
@@ -119,41 +166,59 @@ Write phases in execution order. Keep each phase deployable or explicitly mark w
   - Side-effect shell:
   - Contract:
 - **Validation**: Targeted test, smoke command, or manual check that proves the behavior.
-- **Why**: Why this step is needed and why this order is safe.
+- **Why**: Why this step is needed and why this order is safe, citing the premises it rests on.
 ```
 
-This step is complete only when no checklist item says "update this file" without exact current behavior, target behavior, and validation.
+If a step installs an enforcer — trigger, constraint, guard, gate — check its enforcement window here: every existing writer in the relevant state-authority premise is brought into compliance in the same or an earlier step, or the window is carried into the attack record as a hole to accept or repair.
+
+This step is complete only when no checklist item says "update this file" without exact current behavior, target behavior, cited premises, a deployability declaration, and validation.
 
-### 4. Stress-Test
+### 5. Attack the Plan
 
-Apply these lenses to every phase. Add or change steps until each answer is concrete:
+Construct counterexamples against every invariant. This pass is falsification, not defense: it succeeds by finding holes, and against a draft it should find some. Prefer delegating it to a fresh subagent when the environment can spawn one — give the adversary only the Definitions & Invariants, Premises, state-authority maps, and the checklist, not your design rationale, and brief it that it wins by producing holes; fold its findings back as HOLE entries and repair steps. Solo fallback: enumerate the full attack list from the coverage-matrix rows below before writing any Outcome line, so attacks cannot be shaped around defenses you already have.
 
-| Lens | Plan must answer |
+Use the lenses as attack prompts — purpose, blast radius, valid intermediate state, reversibility, failure, concurrency, boundaries, data integrity, observability, human experience, efficiency, reuse, testability — and record each attack in this form:
+
+```markdown
+### A<n>. <invariant> via <lens>
+- Attack: <actor> + <starting state> + <action sequence>
+- Outcome: HELD — defended by step <N.M> (P<i>, P<j>)
+  | HOLE — repaired by new step <N.M>
+  | HOLE — accepted: <reason>
+```
+
+A `HELD` that cannot name its defending step and premises is not `HELD`; it is a hole wearing confidence. A repaired hole keeps its `HOLE — repaired by step N.M` label permanently — do not rewrite it to `HELD` after the repair, because the repair history is the evidence that the pass falsified. The verdict's repaired count must equal the number of `HOLE — repaired` entries in the record. Close the record with a coverage matrix — one row per writer in every state-authority premise and per applicable lens (valid intermediate state is always applicable when any step installs an enforcer or migration):
+
+```markdown
+| Surface or lens | Attacks |
 | --- | --- |
-| Purpose | Why does the current code exist, and what invariant must survive? |
-| Blast radius | Which direct and transitive consumers move with this change? |
-| Valid intermediate state | Would the project still work after only this phase? |
-| Reversibility | Is this a one-way or two-way door, and what rollback exists? |
-| Failure | What happens when I/O, external APIs, malformed data, retries, or crashes occur? |
-| Concurrency | What shared state can be touched twice or out of order? |
-| Boundaries | Who can call this entry point, and where is input validated? |
-| Data integrity | What existing data, generated artifacts, or persisted contracts are affected? |
-| Observability | Can a maintainer diagnose failures from logs/errors without rereading the source? |
-| Human experience | What would surprise, confuse, or block a real user? |
-| Reuse | Does existing code already solve this problem or most of it? |
-| Testability | Are dependencies injectable, logic pure where practical, concerns separated, and contracts small? |
-
-This step is complete only when every discovered gap has either a new plan step or a written reason it is accepted.
-
-### 5. Verify the Plan
+| <writer, reader, or lens> | A2, A7 |
+```
+
+A blank row is an unattacked writer. The record is incomplete until every row names an attack or carries an accepted reason. Spread attacks across rows before deepening one: depth on the axis you already anticipated does not protect the axes you did not — the leaks come from blank rows, not from the tenth variation of the race you already modeled.
+
+Invalid entry — this exact shape preceded three post-review remediation rounds on a real plan:
+
+> **Concurrency**: Validation happens before database writes; no new shared mutable state or retry behavior is introduced.
+
+It names no actor, no interleaving, and cites nothing. It is an assertion of absence: it cannot fail, so it caught nothing — review later found exactly the race it waved away. A valid entry for the same phase:
+
+> ### A3. "Every stored value is a member of its field's option set" via concurrency
+> - Attack: admin removes option O in transaction A while a user writes value O in transaction B; interleaving B-validates → A-commits → B-commits persists an orphaned value.
+> - Outcome: HOLE — repaired by new step 2.2: validation reads the option definition outside B's lock (P4), so serialize definition changes with every value writer via FOR UPDATE on the definition row; regression proves both interleavings against PostgreSQL.
+
+This step is complete only when the coverage matrix has no blank rows and every attack entry ends in a cited `HELD` or a recorded `HOLE`.
+
+### 6. Verify the Plan and Derive the Verdict
 
 Run or delegate phase-by-phase reference checks. Each verifier confirms:
 
 - every path exists;
 - every line range is still within about five lines;
+- every premise reproduces when its `Source` command is rerun — a premise that no longer reproduces is false, and everything citing it is suspect until fixed;
 - every behavior claim matches source;
 - every new unit has reuse evidence;
-- every behavior-changing step has a validation command and testability design.
+- every behavior-changing step has cited premises, a validation command, and a testability design.
 
 Then rerun the source-producing context for the cited targets:
 
@@ -161,9 +226,22 @@ Then rerun the source-producing context for the cited targets:
 scip-query plan-context <target>
 ```
 
-Use the shared reference for subagent briefing text when delegating.
+Use the shared reference for subagent briefing text when delegating. Close the plan by applying the definitions to the record — do not summarize feelings:
+
+```markdown
+## Verdict
+
+A plan is PLANNED-COMPLETE iff the coverage matrix has no blank rows, every
+attack ends in HELD with cited steps and premises or an accepted hole with a
+written reason, and no premise failed reverification.
+
+Result: PLANNED-COMPLETE | INCOMPLETE — <n> attacks, <x> holes repaired,
+<y> holes accepted; <unresolved items>
+```
+
+The counts are part of the verdict. "16 attacks, 0 holes repaired" against a fresh draft is not a strong plan; it is an attack pass that defended instead of falsified — rerun it before shipping the plan.
 
-This step is complete only when stale references are fixed and every phase has a validation path.
+This step is complete only when stale references are fixed, every premise reverified, and the verdict line is derived from the attack record.
 
 ## Output Shape
 
@@ -171,11 +249,14 @@ The plan file contains:
 
 1. Title and date.
 2. Goal.
-3. Current State.
-4. Reuse Audit.
-5. Testability Design.
-6. Design Phases.
-7. Stress-Test Findings.
-8. Execution Order and deployable phase notes.
-9. Ship Order with one-way doors flagged.
-10. Summary of files to create, edit, delete, and verify.
+3. Definitions & Invariants.
+4. Premises (including state-authority premises and explicit assumptions).
+5. Current State (narrative citing premise IDs).
+6. Reuse Audit.
+7. Testability Design.
+8. Design Phases (steps citing premises, each with a deployability declaration).
+9. Attack Record (attacks with outcomes, holes repaired or accepted, coverage matrix).
+10. Execution Order and deployable phase notes.
+11. Ship Order with one-way doors flagged.
+12. Verdict with attack and hole counts.
+13. Summary of files to create, edit, delete, and verify.

package/skills/scip-debug/SKILL.md

@@ -43,6 +43,7 @@ Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only
 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 with confidence.
 
 ## Workflow
 
@@ -82,6 +83,8 @@ scip-query slice <symbol-or-variable> --forward
 
 Stop expanding 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.
+
 This step is complete only when the path explains the symptom or the missing evidence is explicit.
 
 ### 4. Compare nearby implementations
@@ -117,9 +120,11 @@ Run the reproduction, narrow test or smoke command, and invoke `scip-verify`.
 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. If no root cause is proven, report the missing evidence.
+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, report the missing evidence.

package/skills/scip-explore/SKILL.md

@@ -44,6 +44,7 @@ Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only
 3. Read source with `scip-query code`; do not describe what a function probably does.
 4. Follow the graph before trusting folder structure.
 5. Start wide, then narrow.
+6. Descriptions need citations; conclusions need discriminators. A conclusion — why something happens, what a unit is for, which intent explains a shape — states one rival explanation and the trace evidence that rules it out.
 
 ## Workflow
 
@@ -117,4 +118,4 @@ This step is complete only when the explanation includes the risky symbols or st
 
 ## Report
 
-Report overview, entry points, call flow, data flow, dependencies, consumers, risk areas, and the command citations that prove each claim. Exploration is complete only when the user can see what was proven and what remains unverified.
+Report overview, entry points, call flow, data flow, dependencies, consumers, risk areas, and the command citations that prove each claim. For each conclusion-bearing claim, name the rival explanation considered and the evidence that ruled it out. Exploration is complete only when the user can see what was proven, what remains unverified, and which conclusions rest on a discriminator rather than a single story.

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

@@ -43,6 +43,12 @@ validates (checkers, gates, verifiers, validators — find producers with
 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: file it 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, 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 only when every checker in scope has been witnessed rejecting a
 constructed should-fail input, or is listed with a reason it cannot be.
 
@@ -121,6 +127,17 @@ 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:
+
+```markdown
+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.
+
 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 skill hunts in

package/skills/scip-maintainability/SKILL.md

@@ -53,6 +53,8 @@ Essential variation is difference that must remain because the real units differ
 
 System compression is replacing several mechanisms that perform the same role, policy, lifecycle, or surface job with fewer named mechanisms that preserve behavior.
 
+A unifying definition is the single essential trait that makes several code sites one concept; what makes it a test is that failing to state it proves the sites are not one concept, and consolidating them anyway would package-deal essential variation into a false abstraction.
+
 ## Rules
 
 1. Ground claims in files, symbols, references, call graphs, dependencies, surfaces, and blast radius.
@@ -61,6 +63,7 @@ System compression is replacing several mechanisms that perform the same role, p
 4. Preserve essential variation.
 5. Add an abstraction only when it removes hidden policy, names a lifecycle, enforces a rule, or reduces concept count.
 6. Prefer deletion, inlining, merging, generation, or enforcement before broad frameworks.
+7. A scattered-concept or consolidation claim ships its unifying definition. If no single essential trait covers every cited site, the variation is essential: record it and do not consolidate.
 
 ## Workflow
 
@@ -100,7 +103,7 @@ This step is complete only when concrete units, consumers, tests, fallbacks, ada
 
 For each cluster, ask:
 
-- What one concept appears in several places?
+- 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.
 - What policy is hidden?
 - What lifecycle is unnamed?
 - Which differences are essential?
@@ -144,6 +147,8 @@ For broad review, write a register under `docs/plans/` unless the user asks not
 
 Use dispositions: `merge`, `delete`, `inline`, `extract`, `generate`, `enforce`, `supersede`, `defer`, `skip`.
 
+Every `merge`, `extract`, or `generate` entry carries its unifying definition and its strongest dissenter — the cited site most likely to differ essentially — with the evidence that it does not. A dissenter that survives moves the entry to `skip` with reason `essential variation`; the dissenter stays in the register either way.
+
 This step is complete only when each opportunity has evidence, disposition, dependency order, touch map, and validation plan.
 
 ### 7. Implement and verify when asked

package/skills/scip-query/SKILL.md

@@ -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