scip-query 0.19.4 → 0.19.6

package/skills/scip-explore/SKILL.md

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

package/skills/scip-explore/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "SCIP Explore"
-  short_description: "Trace systems with SCIP evidence"
-  default_prompt: "Use $scip-explore to understand this system end to end with SCIP-backed code evidence."
+  short_description: "Understand a system with SCIP evidence"
+  default_prompt: "Use $scip-explore to understand this system end to end with SCIP-backed code evidence before editing it."

package/skills/scip-explore/references/diagrams.md

@@ -0,0 +1,40 @@
+# Diagrams
+
+Use this for code flow diagrams, architecture diagrams, data-flow maps, dependency maps, blast-radius visuals, module maps, or any HTML artifact that explains a system — built from `scip-query` evidence. A code diagram is an HTML artifact that turns source units, calls, dependencies, data flow, or blast radius into a visual map. Every node and edge must trace to `scip-query` evidence — gather it before drawing.
+
+## Workflow
+
+**1. Pick the diagram type.** Map the user's intent to a diagram type:
+
+| Intent | Diagram type |
+|---|---|
+| Feature flow | Call flow |
+| Value origin or mutation | Data flow |
+| Who depends on this | Blast radius |
+| Module architecture | Dependency map |
+| Why this is hard to change | Change surface / bottleneck map |
+| Classes or ownership | Hierarchy and surface map |
+
+Done when: the diagram's node and edge types are chosen.
+
+**2. Collect evidence.** Use only the commands the chosen diagram type needs, from:
+
+- `system <module>` — module map (file paths, exported symbols with line ranges, internal/reverse deps) for a dependency or architecture diagram.
+- `trace <symbol>` — definition sites plus all references, for a call-flow diagram.
+- `call-graph <symbol>` — incoming callers and outgoing callees, for a call-flow diagram.
+- `dataflow <symbol>` — definition sites, usage sites, producer symbols, consumer symbols, for a data-flow diagram.
+- `affected <symbol> --json` — transitive closure of symbols that could break if this symbol changes, for blast-radius nodes and edges.
+- `change-surface <file> --json --full` — exports, external consumer counts, and risk levels, for a change-surface map.
+- Also available as needed: `surface`, `outline`, `code`, `slice`, `slice --forward`, `deps`, `rdeps`, `hierarchy --json`, `fan-out --json`.
+
+Done when: every planned node and edge has a source command behind it.
+
+**3. Build the artifact.** Write it to `docs/scip-query/diagrams/YYYY-MM-DD-<scope>.html`. It must include: title, scope, summary, the visual diagram, a legend, an evidence table (which command produced which nodes/edges — command provenance lives inside the artifact, not just in your chat reply), omitted/collapsed nodes, and unavailable capabilities. Use inline CSS and semantic HTML or inline SVG: stable dimensions, wrapping labels, accessible colors, and distinct edge styles for calls, data, dependencies, and risk. Scope large graphs into clusters instead of rendering a hairball.
+
+Done when: the HTML contains both the visual diagram and the provenance/evidence table.
+
+**4. Verify.** Open the diagram file locally, or use a browser/screenshot tool when available. Confirm: the diagram is nonblank, labels don't overlap badly, and major nodes/edges trace to evidence. If the diagram is part of a docs/code change, invoke `scip-verify`.
+
+End the deliverable with the file path and a statement of what the diagram proves.
+
+Load shared mechanics from `../_shared/SKILL.md` — use this skill's own command shortlist first and open `_shared` only when it's insufficient.

package/skills/scip-explore/references/language-playbook.md

@@ -0,0 +1,49 @@
+# Language playbook
+
+Choose the shortest command path from "what is this system doing?" to a verified, language-specific answer. Start with the active language's row before reaching for broader or noisier commands. Pair relationship commands (`call-graph`, `imports`, `imported-by`, `refs`) with `code` to confirm behavior claims — don't stop at the relationship alone. For de-bloat work, cross-check multiple detector families rather than trusting one. When a command is weaker for a given language, use that language's fallback note instead of forcing it.
+
+## Universal first pass (any language)
+
+Run in order: `stats` (repo-wide size/shape, complete) → `kind-counts` → `files <feature-or-module-name>` (locate the files, complete) → `outline <file>` (symbol tree with line ranges, complete) → `by-kind function --scope <feature-or-module-name>` → `trace <symbol>` (definition + every reference, bounded) → `hierarchy <symbol>` → `code <symbol>` (confirm behavior with source, complete).
+
+## Per-language shortlists
+
+Each row gives the commands to reach for first, a de-bloat set for cleanup passes, and a fallback note for where that language's evidence is weaker or stronger than usual.
+
+**TypeScript** — first: `system`, `surface`, `call-graph`, `dataflow`, `change-surface`. De-bloat: `health`, `dead`, `similar`, `similar --plan`, `wrapper-candidates`, `passthrough-candidates`, `stale-abstractions`, `unused-imports`, `redundant-reexports`. Fallback: strongest verified surface of any language here; Vue script blocks use this same command path.
+
+**Python** — first: `outline`, `kind-counts --scope`, `system`, `imports`, `imported-by`, `call-graph`. De-bloat: `dead`, `unused-imports`, `drift`, `similar-signatures`, `complexity`, `complexity-hotspots`. Fallback: prefer source-backed fallbacks when call/kind metadata is sparse.
+
+**Java** — first: `system`, `surface`, `call-graph`, `deps`, `rdeps`, `slice`. De-bloat: `health`, `dead`, `similar-files`, `similar-chains`, `wrapper-candidates`, `stale-abstractions`, `extract-candidates`. Fallback: use module/package surfaces to avoid class-only tunnel vision.
+
+**Scala** — first: `surface`, `trace`, `call-graph`, `imports`, `imported-by`. De-bloat: `dead`, `similar-files`, `similar-chains`, `extract-candidates`, `stale-abstractions`, `unused-imports`. Fallback: confirm behavior with `code`.
+
+**Kotlin** — first: `surface`, `trace`, `call-graph`, `imports`, `imported-by`. De-bloat: `dead`, `similar-files`, `similar-chains`, `extract-candidates`, `stale-abstractions`, `unused-imports`. Fallback: confirm behavior with `code`.
+
+**Rust** — first: `trace`, `call-graph`, `refs`, `methods`, `surface`. De-bloat: `dead`, `wrapper-candidates`, `passthrough-candidates`, `stale-abstractions`, `similar-signatures`, `redundant-reexports`. Fallback: `methods` and `surface` are usually high signal here.
+
+**Go** — first: `surface`, `trace`, `call-graph`, `refs`, `fan-in`. De-bloat: `dead`, `wrapper-candidates`, `passthrough-candidates`, `similar-files`, `similar-signatures`, `complexity`. Fallback: use package-level surfaces and confirm exported APIs before cleanup.
+
+**C++** — first: `trace`, `refs`, `methods`, `surface`, `code`. De-bloat: `dead`, `wrapper-candidates`, `similar-files`, `similar-chains`, `extract-candidates`, `unused-imports`. Fallback: try `call-graph` after trace/refs/code.
+
+**C** — first: `trace`, `call-graph`, `refs`, `outline`, `fan-out`. De-bloat: `dead`, `wrapper-candidates`, `similar-files`, `similar-chains`, `extract-candidates`, `unused-imports`. Fallback: skip class/member commands — they don't apply.
+
+**Ruby** — first: `trace`, `call-graph`, `refs`, `imports`, `imported-by`. De-bloat: `dead`, `wrapper-candidates`, `passthrough-candidates`, `stale-abstractions`, `similar-files`, `similar-signatures`. Fallback: confirm dynamic-looking paths with source.
+
+**C#** — first: `surface`, `call-graph`, `trace`, `methods`, `refs`. De-bloat: `dead`, `wrapper-candidates`, `passthrough-candidates`, `stale-abstractions`, `similar-files`, `extract-candidates`. Fallback: use surfaces and methods together.
+
+**Visual Basic** — first: `surface`, `call-graph`, `trace`, `methods`, `refs`. De-bloat: `dead`, `wrapper-candidates`, `passthrough-candidates`, `stale-abstractions`, `similar-files`, `extract-candidates`. Fallback: use surfaces and methods together.
+
+**Dart** — first: `surface`, `call-graph`, `trace`, `imports`, `imported-by`. De-bloat: `dead`, `wrapper-candidates`, `stale-abstractions`, `similar-files`, `similar-signatures`, `redundant-reexports`. Fallback: confirm exported API shape with `surface`.
+
+**PHP** — first: `trace`, `refs`, `methods`, `surface`, `code`. De-bloat: `dead`, `wrapper-candidates`, `stale-abstractions`, `similar-files`, `similar-signatures`, `extract-candidates`. Fallback: try `call-graph` after trace/refs/code.
+
+**Clojure / ClojureScript** — first: `files`, `outline`, `trace`, `refs`, `call-graph`. De-bloat: `dead`, `similar-files`, `similar-signatures`, `complexity`, `complexity-hotspots`. Constraint: SCIP indexing comes from scip-clojure — there is no TypeScript-style semantic provider available for it, so don't expect the same depth of type-aware results.
+
+## Minimal workflows
+
+**Understand a feature:** `files <feature>` → `outline <file>` → `kind-counts --scope <feature>` → `fan-out <file>` → `trace <entry-symbol>` → `call-graph <entry-symbol>` → `code <entry-symbol>` → `surface <module>`.
+
+**Find DRY and de-bloat wins:** `health` → `dead` → `wrapper-candidates` → `passthrough-candidates` → `stale-abstractions` → `similar-files` → `similar-chains` → `similar-signatures` → `extract-candidates`.
+
+When recommending a command sequence, name the language and say why these commands are highest-signal for it — don't just list commands.

package/skills/scip-improve/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: scip-improve
+description: Use when edits should actually be made: fix confirmed cleanup findings batch by batch, consolidate a drifted twin into one canonical helper, implement a named maintainability mechanism, extract a React hook or Vue composable, move files to fix locality, or bring AGENTS.md/standards/docs back in sync with code. Requires findings already confirmed — audit first if they are not. For reducing one symbol's cognitive complexity, use `complexity-cleanup`; for deciding where a boundary belongs at design time, use `decomposition`.
+commands:
+  - template: "scip-query cleanup-plan --verify --json"
+    when: "Build compiler-checked deletion batches from confirmed dead-code findings."
+  - template: "scip-query cleanup-apply --verified --batch <n>"
+    when: "Apply one already verified cleanup batch."
+  - template: "scip-query diff-gate --json --compact"
+    when: "Gate each implemented improvement slice before declaring it complete."
+---
+
+## Purpose
+
+This skill edits the working tree. It does not discover findings — it acts on
+findings someone already confirmed: a cleanup-plan batch, a twin-drift group,
+a maintainability register entry, a React/Vue duplicate or extraction
+candidate, a directory move ledger, or a doc-drift worklist. If nothing has
+been confirmed yet, run the matching scenario in `scip-audit` and come back
+with its evidence and disposition.
+
+## Ground rules, every scenario
+
+- Work in small, independently verifiable batches or slices — one verified deletion batch, one migration slice, one twin group, one register entry. Never apply everything unattended.
+- State the plan before editing: what's confirmed, the evidence, the intended change, how you'll verify it.
+- Re-derive evidence from current `scip-query` output, not from memory or the stale text you're replacing.
+- After every applied change, run the routed postchecks in the `scip-verify` skill, in addition to whatever narrow rerun this scenario names.
+- Load command mechanics from `_shared` first; this file only names the commands each scenario needs and what to do with their output.
+
+## Triage
+
+| Situation | Do this | Reference |
+|---|---|---|
+| Fix confirmed cleanup findings, raise health, "keep cleaning" | `health` → `cleanup-plan --verify` → `cleanup-apply --verified --batch <n>` in a loop | `references/cleanup-batches.md` |
+| AGENTS.md/CLAUDE.md/standards/command docs are stale or cite moved code | `doc-drift` → `outline`/`trace`/`code` per doc → rerun `doc-drift` | `references/doc-reconcile.md` |
+| Same-name/near-name functions diverged, one-sided fix, drifted threshold | `twin-drift --json --full` → classify → consolidate → rerun `twin-drift` | `references/twin-drift.md` |
+| Implement a confirmed maintainability register entry (hidden policy, thin wrapper, dead re-export) | `extract-candidates` / `passthrough-candidates` / `wrapper-candidates` / `stale-abstractions` / `redundant-reexports` to confirm, then implement the disposition | `references/maintainability-mechanism.md` |
+| Extract a React hook/component or Vue composable/component | cross-check confirmed candidates, classify reuse/extract/split, extract | `references/frontend-extraction.md` |
+| Move files to fix locality, declare/close an architecture boundary | `locality-candidates --json --full` → migration slice → boundary config → postchecks | `references/directory-moves.md` |
+
+## Owned commands
+
+`cleanup-apply`, `cleanup-plan`, `twin-drift`, `doc-drift`, `locality-candidates`, `extract-candidates`, `passthrough-candidates`, `wrapper-candidates`, `redundant-reexports`, `stale-abstractions` — each has a worked scenario in the references above; none should be run without reading the reference's evidence caveat first (several of these detectors are exploration-only with near-zero precision on codebases with intentional layering).
+
+
+<!-- BEGIN GENERATED SKILL COMMANDS -->
+## Commands for this skill
+
+| Command | Purpose | Returns | Coverage | When |
+| --- | --- | --- | --- | --- |
+| `scip-query cleanup-plan --verify --json` | Ordered, batched deletion plan: graph-fact dead code plus the cascade candidates it unlocks | ordered cleanup batches, evidence, and optional verification outcomes | `bounded` | Build compiler-checked deletion batches from confirmed dead-code findings. |
+| `scip-query cleanup-apply --verified --batch <n>` | Apply a compiler-verified cleanup-plan batch to the working tree | applied files, deletions, verification, and refusal reasons | `bounded` | Apply one already verified cleanup batch. |
+| `scip-query diff-gate --json --compact` | Gate the current diff: architecture regressions plus echo, migration, coordination, doc-drift, unused-param, and new-dead candidates; exit 1 on blocking findings | blocking findings with check id, message, and remediation; advisory findings; root-cause groups; changed file and symbol counts; process exit status (1 when blocking findings exist) | `bounded` | Gate each implemented improvement slice before declaring it complete. |
+
+Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only when it is insufficient.
+<!-- END GENERATED SKILL COMMANDS -->

package/skills/scip-improve/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "SCIP Improve"
+  short_description: "Apply verified fixes to the working tree"
+  default_prompt: "Use $scip-improve to apply confirmed findings as real edits, batch by batch, with verification between batches."

package/skills/scip-improve/references/cleanup-batches.md

@@ -0,0 +1,53 @@
+# Cleanup batches
+
+Use when the user asks to fix cleanup findings, raise health, keep cleaning, continue after setup, or work until no safe confirmed cleanup remains. The target is not a higher health score for its own sake — it's fixing confirmed issues that make the codebase harder to understand, verify, or change.
+
+## Before editing
+
+If cleanup findings have not been swept and confirmed yet, run the cleanup
+scenario in `scip-audit` first. Then report a markdown block before touching
+any code:
+
+- current score from `scip-query health --json`
+- the first confirmed batch: finding, evidence, planned fix, verification plan
+- remaining signals with status
+
+## Priority order
+
+Work top to bottom, one item at a time:
+
+1. Compiler-verified deletion batches (`cleanup-plan --verify`).
+2. Incomplete migrations (`incomplete-migration --json --full`) and recent duplicate echoes (`duplicate-bodies --json --full`, exact small-body echoes).
+3. Unused params/imports, dead symbols, isolated symbols.
+4. Broken or stale docs, config validation issues, missing co-change partners.
+5. Thin wrappers, passthroughs, stale abstractions, speculative generality.
+6. Frontend component/hook/composable duplication and large-view pressure.
+7. Directory architecture and maintainability repairs — only when evidence is strong and blast radius is bounded.
+
+## The loop
+
+Repeat until stopping:
+
+1. Apply one verified deletion batch — `scip-query cleanup-apply --verified --batch <n>` against the plan from `scip-query cleanup-plan --verify --json` — or one small targeted refactor for the next prioritized item.
+2. Run the narrow project check for the touched behavior (tests/typecheck scoped to what changed).
+3. Run `scip-query health --json`.
+4. Invoke the `scip-verify` skill.
+5. If `docs/scip-query/health-dossier.md` exists (or a custom `--dossier-dir` was used), refresh it by rerunning `scip-query setup --json` with the same `--dossier-dir` if one was used.
+6. Pick the next highest-priority confirmed item and repeat.
+
+Only use `scip-query cleanup-apply --all` with explicit user approval — never apply all batches unattended by default.
+
+## Stop when
+
+- Only intentional, false-positive, blocked, or unconfirmed items remain.
+- The next improvement would require a product/API/ownership decision.
+- A missing toolchain prevents trustworthy verification.
+- Further work would amount to broad redesign, not bounded cleanup.
+
+## Between passes
+
+After a cleanup pass, run `scip-query health --write-baseline` to snapshot finding identities. At the start of the next pass, compare against it with `scip-query health --baseline`.
+
+## Closeout report
+
+Starting and final health scores, batches applied, important files changed, verification commands run, remaining accepted or blocked items, and the highest-value follow-up.

package/skills/scip-improve/references/directory-moves.md

@@ -0,0 +1,53 @@
+# Directory moves
+
+Use to move files to fix locality or to close a dependency rule once the
+directory scenario in `scip-audit` has produced a target structure or move
+ledger. If there is no reviewed target structure yet, run that scenario first
+— this reference starts from its output and never invents a target structure
+on its own.
+
+## Find and confirm the move
+
+Run `scip-query locality-candidates --json --full` for directory-locality and ancestry candidates from consumer ownership (symbols, current homes, consumer locality, suggested homes). Cross-check current placement with `scip-query system <scope>` (files, exported symbols with line ranges, internal deps, reverse deps).
+
+Concepts that decide whether a move is safe:
+
+- **Ownership boundary** — a folder, package, module, or convention grouping code around one stable responsibility.
+- **Forbidden edge** — an actual cross-boundary dependency rejected by an explicit project rule. Directory distance or an unusual import alone does not make an edge forbidden.
+- **Reciprocal dependency** — traffic in both directions between two boundaries. It's a review signal that the boundaries exert mutual pressure, not proof that either import is wrong.
+- **Migration slice** — the smallest set of file moves and import updates that can be verified independently.
+
+Rules: separate review from migration — don't move files unless asked. Preserve broad boundaries when evidence shows they're intentional. Don't reward a generic "shared" boundary/directory unless the shared concept has a name, an owner, and cross-boundary consumers. Prefer small verified moves over large speculative reorganizations. Configure descriptive boundaries before closing dependency rules.
+
+Before editing a slice, state: the files to move, the imports/exports/tests/docs to update, the expected verification, and the rollback risk.
+
+## If boundaries themselves are changing
+
+Add mature boundary path patterns to `.scipquery.json` under `architecture.boundaries` **without** `allowedDependencies` rows first, e.g.:
+
+```json
+{ "architecture": { "boundaries": [
+  { "name": "domain", "paths": ["src/domain/**"] },
+  { "name": "runtime", "paths": ["src/runtime/**"] }
+] } }
+```
+
+Then run `scip-query config-validate --json`, then `scip-query architecture --json`.
+
+An `allowedDependencies` row is closed: an outgoing target omitted from a present row is forbidden, but a missing row makes no dependency claim at all. Example: `{ "architecture": { "boundaries": [...], "allowedDependencies": { "domain": [], "runtime": ["domain"] }, "requireAcyclic": true } }`. For each closed row, record the evidence for its intended direction. Never copy the current dependency graph into the allow-list merely to obtain zero findings; leave emerging or disputed rules undeclared rather than closing the row prematurely.
+
+When repairing a boundary cycle, inspect the least-broad edge inside it first, then decide whether the fix is a move, a dependency inversion, a named shared contract, a boundary merge, or a policy correction.
+
+## Ratcheting enforcement on a large repo
+
+Before enabling architecture regression enforcement on an existing codebase, review the direct findings with `scip-query drift --architecture` and record reviewed existing debt with `scip-query health --write-baseline`. The baseline records stable architecture identities by boundary pair, not by whichever example file happens to sort first. Commit `.scipquery-baseline.json` together with `.scipquery.json`.
+
+The default `diff-gate` architecture check compares only architecture identities and does not run every health detector; `diff-gate --baseline` is the opt-in full health ratchet and does not duplicate architecture findings. A missing baseline causes the architecture gate to report that enforcement is not enabled — it does **not** silently treat the current dependency graph as accepted.
+
+## After moving the slice
+
+Run `scip-query incomplete-migration`, `scip-query recent-duplicates`, and `scip-query co-change <moved-file-or-config>`, plus the project's tests or typecheck for the affected workspace.
+
+If `.scipquery.json` locality changed, also run `scip-query config-validate`, `scip-query locality-candidates --json --full`, `scip-query architecture --json`, `scip-query drift --architecture`, and `scip-query diff-gate`.
+
+Then invoke `scip-verify`. The implementation is complete only when imports, tests, locality signals, and verification are all checked.

package/skills/scip-improve/references/doc-reconcile.md

@@ -0,0 +1,30 @@
+# Doc reconciliation
+
+Use for stale standards, broken file references, docs that cite moved code, agent guidance, or normative contradictions between documentation and implementation. Only reconcile living docs — documentation agents or maintainers use to make present-day changes: AGENTS.md, CLAUDE.md, standards, command docs, workflow docs. Do not reconcile archival records (dated plans, ADRs, reports); list them in `.scipquery.json` under `docs.snapshotPaths` so `doc-drift` excludes them with a labeled exclusion instead of resurfacing them every sweep.
+
+The core distinction driving every edit:
+
+- **Descriptive claims** say what the code currently does or where it lives. Update them when code moves.
+- **Normative claims** say what code must or should do. If code violates one, fix the code or escalate the contradiction — never weaken the standard silently to match drifted code.
+
+## Step 1 — Build the worklist
+
+Run `scip-query doc-drift --json --full` for the ranked worklist (document paths, coupled code subjects, history evidence), plus `scip-query doc-drift <doc-or-tree>` for anything scoped. Prioritize broken references first, then highest staleness, then the docs agents read most. Done only when each target doc is selected for a current-use reason.
+
+## Step 2 — Reconcile one doc
+
+For each doc: `scip-query doc-drift <doc>`, `scip-query outline <subject-file>` for its current shape, `scip-query system <module>` for the surrounding module, `scip-query trace <symbol>` for every symbol the doc mentions, `scip-query code <symbol>` to re-derive any snippet from current source (never from memory or the stale text). Use git history only to understand why a subject changed, never as a substitute for current code evidence.
+
+- Fix broken references by finding the current code or deleting the obsolete claim.
+- Rewrite stale descriptive claims from the evidence just gathered.
+- Record normative contradictions instead of changing standards to bless drifted code.
+
+Done only when every edited claim is supported by evidence gathered in this session.
+
+## Step 3 — Verify
+
+Rerun `scip-query doc-drift <doc>`. If the documentation change is part of a codebase diff, invoke `scip-verify`. Don't claim reconciliation is done until `doc-drift` has been rerun. Done only when staleness drops to zero or the remaining contradiction is explicitly reported.
+
+## Step 4 — Report
+
+Staleness before and after, broken references fixed, claims updated, normative contradictions surfaced, and docs recommended for deletion.

package/skills/scip-improve/references/frontend-extraction.md

@@ -0,0 +1,39 @@
+# React/Vue extraction
+
+Use to extract a React hook/component or a Vue composable/component once the
+frontend scenario in `scip-audit` has produced confirmed candidate pairs. If
+nothing is confirmed yet, run that scenario first, then cross-check, then act.
+
+- A **component duplicate candidate** is a pair or group of rendered structures repeating the same user-facing arrangement, controls, states, props/bindings, or data-presentation shape enough that a shared component may reduce drift.
+- A **hook candidate** (React) / **composable candidate** (Vue) is a pair or group of behaviors repeating the same state lifecycle, effects, requests, validation, persistence, or derived-data policy enough that a shared hook/composable may preserve behavior better.
+- **Large component/view pressure** means one component, SFC, or linked view file contains several kinds of knowledge that change for different reasons — a large file or style block is pressure, not proof, by itself.
+
+## Scan (only if not already done)
+
+React: `scip-query react-component-duplicates`, `react-hook-candidates`, `react-large-component-pressure`, `recent-duplicates`, `health` — all `--scope <scope> --full --json`, uncapped.
+
+Vue: same shape, using `vue-component-duplicates`, `vue-composable-candidates`, `vue-large-view-pressure`. Before scanning, when component references, imported composables, script blocks, or linked external scripts matter, run `scip-query augment-vue --project <path-to-tsconfig>` to add compiler-resolved Vue SFC references via Volar — Vue needs this step; React doesn't.
+
+Record scope, counts, and uncapped/full status.
+
+## Cross-check before acting
+
+Use `scip-query outline <file>`, `deps <file>`, `rdeps <file>`, `similar-files --scope <scope>`, and either `scip-query similar <closest-existing-component-or-hook>` (React) or `scip-query recent-duplicates --scope <scope> --full --json` (Vue) to validate each candidate. Classify every top candidate as reuse, extract, split, skip, or blocked:
+
+- Component-duplicate-only → look for a shared presentational component or existing reuse.
+- Hook/composable-candidate-only → look for shared state lifecycle, effects, requests, validation, persistence, or derived-state policy.
+- Both overlap → look for a feature-level concept that needs both a component boundary and a hook/composable boundary.
+- Large-component/view-only → split by reason to change, not by line count.
+
+## Act
+
+Prefer reuse over extraction. Extract a component for repeated UI/template structure, props, slots/children, states, or design-system composition. Extract a hook for repeated state, effects, requests, subscriptions, memoized derivations, callbacks, or persistence; extract a composable for the Vue equivalent — repeated state, lifecycle, requests, validation, persistence, derived data, or event policy. Keep essential domain-specific variation at the call site.
+
+Don't:
+- Create boolean-soup APIs or wrapper components/composables with no policy as a side effect.
+- Treat shared design-system primitives, icons, labels, route names, test IDs, or CSS utilities alone as sufficient evidence for a duplicate/hook/composable claim.
+- Extract a shared hook or composable from templates that merely look similar but carry different domain lifecycles — that similarity may justify a shared presentational component, never a shared hook/composable.
+
+## Verify and report
+
+Invoke `scip-verify` and run its React or Vue postcheck rows, plus the applicable extraction, duplicate, parameter, wrapper, passthrough, and stale-abstraction checks. Work is complete only when the acted-on candidate pairs disappear, weaken materially, or are explicitly accepted as essential variation. Report: executive read, command evidence, candidate groups, recommended action taken, post-change proof, and remaining accepted variation.

package/skills/scip-improve/references/maintainability-mechanism.md

@@ -0,0 +1,43 @@
+# Implementing a maintainability mechanism
+
+Use to implement a confirmed maintainability opportunity: a register or atlas
+entry that names a hidden policy, an unnamed lifecycle, or scattered concepts,
+and proposes a disposition. Maintainability is the degree to which real code
+units let a maintainer understand, verify, and change behavior without
+rediscovering hidden knowledge. If there is no confirmed register entry yet,
+run the maintainability scenario in `scip-audit` first — this reference starts
+from its output.
+
+## Vocabulary you need to act correctly
+
+- **Concept boundary** — the line around code units that exist for one reason to change.
+- **Hidden policy** — a rule for choosing among several plausible behaviors that lives in local branches, comments, conventions, or caller folklore instead of a named mechanism.
+- **Lifecycle** — a repeatable sequence of states or steps that makes a result valid.
+- **Essential variation** — difference that must remain because the real units differ: language grammars, user-visible APIs, runtime environments, compatibility boundaries. **Accidental variation** — difference in code shape that doesn't correspond to any of those. Preserve the former; remove the latter.
+- **System compression** — replacing several mechanisms that perform the same role, policy, lifecycle, or surface job with fewer named mechanisms, preserving behavior.
+- **Unifying definition** — the single essential trait that makes several code sites one concept. A merge, extract, or generate action is only justified when you can state this trait and it covers every cited site; if it doesn't, the variation is essential and those sites must not be consolidated.
+
+Ground every action in files, symbols, references, call graphs, dependencies, surfaces, and blast radius — never opinion. Name concrete referents before naming a smell. Don't chase health scores; detector counts are clues, not objectives. Only add an abstraction when it removes hidden policy, names a lifecycle, enforces a rule, or reduces concept count — never for its own sake. Prefer deletion, inlining, merging, generation, or enforcement of an existing mechanism before introducing a broad new framework.
+
+## Priority when several confirmed entries compete
+
+Rank by severity tier, most severe first: (1) hidden correctness or evidence policy spread across modules, (2) a repeated lifecycle/pipeline with no owner, (3) public surface exposing accidental internals, (4) a large module with unrelated reasons to change, (5) tests that encode incident history without contract vocabulary, (6) adapter families with repeated capability/fallback shapes, (7) suppression comments documenting architecture decisions instead of exceptions, (8) thin wrappers/passthroughs that don't buy clarity. Reject and don't act on smells that are aesthetic, unverifiable, or false compression.
+
+## Confirming a candidate before you touch code
+
+- `scip-query extract-candidates` finds heuristic extraction candidates from isolated callee clusters. When the register calls for extracting a shared helper, run this to confirm the callee cluster, then read every cited site to check the unifying definition actually holds.
+- `scip-query passthrough-candidates` finds heuristic passthrough candidates that forward to one callee. When the disposition is inline or delete, run this to confirm the passthrough is real before removing it.
+- `scip-query wrapper-candidates` and `scip-query stale-abstractions` find, respectively, single-consumer wrappers and 0–1-consumer abstractions — both have near-zero precision on codebases with intentional layering or ambient types. Treat every hit as exploration, never a finding; run them only after the main sweep is exhausted; never act on a hit without reading the cited code first, and confirm real consumer counts with `refs`/`surface` before deciding a disposition.
+- `scip-query redundant-reexports` finds barrel re-exports that nobody imports through. When the disposition is delete, confirm no import path actually uses the barrel, then remove the re-export and update any doc or index that referenced it.
+
+## Dispositions
+
+merge, delete, inline, extract, generate, enforce, supersede, defer, skip. Every merge/extract/generate action must carry its unifying definition and its strongest dissenter — the cited site most likely to differ essentially — plus evidence that the dissenter doesn't actually differ essentially. If a dissenter survives review (it really does differ essentially), the entry's disposition becomes skip with reason "essential variation," but the dissenter stays recorded either way.
+
+## Implement
+
+Implement the smallest named mechanism that matches the real concept. Keep essential variation near the adapter or domain code that knows it, not buried inside the new mechanism.
+
+## Verify and report
+
+Run focused tests, then the routed postchecks from `scip-verify`. The final report states the smell addressed, the mechanism introduced or removed, what was deliberately not compressed, and the verification results.