scip-query 0.7.1 → 0.8.0

package/skills/concrete-plan/SKILL.md

@@ -23,9 +23,39 @@ You are writing a production implementation plan as a markdown checklist. Every
 
 ---
 
+## Gather Context Fast
+
+Start every plan with the bundled context command — it replaces a half-dozen
+separate queries and adds evidence no single query has:
+
+```bash
+scip-query plan-context <symbol-or-file>
+```
+
+Use its sections directly in the plan:
+
+- **DEFINITIONS / REFERENCES / CALL GRAPH / DOWNSTREAM IMPACT** — the Source
+  citations for your steps.
+- **HISTORY** — files that usually change together with the target. If the
+  plan edits the target, the plan MUST either cover its co-change partners or
+  state why they're untouched this time. This is how plans stop causing drift.
+- **CHANGE RISK** — high-risk consumers get their own verification steps.
+
+Two pre-plan checks that prevent planning mistakes:
+
+```bash
+scip-query doc-drift <standard.md>    # is the standard this plan follows stale?
+scip-query recent-duplicates          # does the helper you're about to plan already exist?
+```
+
+If `doc-drift` shows the standard's referenced code moved on without it,
+updating that standard becomes step 0 of the plan. If the plan creates a new
+helper, cite the `similar` / `recent-duplicates` evidence that nothing
+established already does the job.
+
 ## Symbol Lookup Tips
 
-scip-query accepts partial symbol names — you don't need the full SCIP symbol path. These all work:
+`scip-query` accepts partial symbol names — you don't need the full SCIP symbol path. These all work:
 
 ```bash
 scip-query code processVegaMention              # just the function name
@@ -52,7 +82,7 @@ scip-query code 'src/modules/chat/chat.service.ts:100-200'
 
 **If "Symbol not found":**
 1. Try a shorter/simpler name — `login` instead of `AuthService:login`
-2. Try `scip-query symbols <file>` to see what symbols exist in the file
+2. Try `scip-query outline <file>` to see what symbols exist in the file
 3. Try `scip-query trace <name>` which uses a different lookup path
 4. Use the `file:line-line` syntax for `code` if you know the location
 
@@ -67,13 +97,13 @@ This skill deliberately excludes `Grep` and `Read` from its allowed tools. This
 - Using `Read` via a subagent to browse files for discovery. Subagents must also use scip-query.
 - Spawning Explore agents that fall back to grep and file reads. If a subagent's output does not cite scip-query commands, reject its findings and re-run.
 
-**Instead, use scip-query (full reference at `/Users/aydansalois/Documents/GitHub/scip-query/README.md`):**
+**Instead, use scip-query (full reference at `/Users/aydansalois/Documents/GitHub/scip-query/docs/COMMAND_REFERENCE.md`):**
 
 | You want to... | Use this |
 |---|---|
 | **Read source code** | `scip-query code <symbol>` (reads file, bounded to definition range) |
 | **Read source with context** | `scip-query code <symbol> -C 5` (5 extra lines above/below) |
-| Find a symbol / list file contents | `scip-query symbols <file>` (all symbols with line ranges + signatures) |
+| Find a symbol / list file contents | `scip-query outline <file>` (all symbols with line ranges + signatures) |
 | Find files by name | `scip-query files <pattern>` |
 | See callers + callees | `scip-query call-graph <symbol>` |
 | Full module map | `scip-query system <module>` |
@@ -107,7 +137,7 @@ If none of these can answer your question, say so explicitly in the plan rather
 
 ### Full Documentation
 
-- **Every command with options and examples:** `/Users/aydansalois/Documents/GitHub/scip-query/README.md`
+- **Every command with options and examples:** `/Users/aydansalois/Documents/GitHub/scip-query/docs/COMMAND_REFERENCE.md`
 - **Goal-oriented agent workflows:** `/Users/aydansalois/Documents/GitHub/scip-query/docs/AGENT_GUIDE.md`
 
 ---
@@ -284,7 +314,7 @@ You have the `scip-query` CLI for compiler-resolved code intelligence. Use it fo
 Navigation:
 - `scip-query code <symbol>` — read source code (bounded to definition range)
 - `scip-query code <symbol> -C 5` — read source with 5 extra context lines
-- `scip-query symbols <file>` — all symbols in a file with line ranges + signatures
+- `scip-query outline <file>` — all symbols in a file with line ranges + signatures
 - `scip-query files <pattern>` — find files by name
 - `scip-query refs <symbol>` — every file referencing a symbol
 - `scip-query trace <symbol>` — definition + signature + all references
@@ -314,7 +344,7 @@ Quality:
 - `scip-query complexity-hotspots` — riskiest symbols
 - `scip-query cycles` — circular dependencies
 
-Full command reference: /Users/aydansalois/Documents/GitHub/scip-query/README.md
+Full command reference: /Users/aydansalois/Documents/GitHub/scip-query/docs/COMMAND_REFERENCE.md
 Agent workflows guide: /Users/aydansalois/Documents/GitHub/scip-query/docs/AGENT_GUIDE.md
 
 ### Rules

package/skills/scip-ai-cleanup/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: scip-ai-cleanup
+description: Clean up AI-generated code rot using scip-query's change-graph and verification tooling. Finds recent re-implementations of established code, drifting standards docs, speculative parameters, hidden coupling, and produces compiler-verified deletion plans. Sets up the CI ratchet so findings never regress.
+allowed-tools: [Bash, Write, Edit, Glob, Agent, TaskCreate, TaskUpdate, TaskGet, TaskList]
+keywords: [ai-slop, ai-generated, cleanup, duplicates, echo, doc-drift, standards, stale-docs, cleanup-plan, verify, co-change, ratchet, baseline, unused-params]
+---
+
+# AI-Generated Code Cleanup with scip-query
+
+AI-assisted development rots a codebase in specific, detectable ways: agents
+re-implement helpers they didn't know existed, leave half-wired parallel
+implementations behind, add parameters "for later" that never come, and the
+standards docs written FOR agents drift away from the code — so the next agent
+implements against a dead spec. None of this is visible in a single file;
+all of it is visible in the reference graph + the git change graph.
+
+This skill runs the full sweep and ends with a compiler-verified deletion
+plan and a CI ratchet.
+
+## When to Use This Skill
+
+- "Clean up the AI slop in this repo"
+- "Did the agents duplicate code?"
+- "Are our standards docs stale?"
+- "What can we safely delete?"
+- "Set up a quality gate for agent-written code"
+
+## Hard Rules
+
+1. **Evidence first.** Run `scip-query status` and `scip-query reindex` before
+   trusting graph facts. All detectors print whether they're heuristic.
+2. **Verify before deleting.** Findings are candidates; only
+   `cleanup-plan --verify` output stamped COMPILER-VERIFIED is proof.
+   A FAILED verification is signal too — its errors name the references the
+   static evidence missed. Never delete on a failed batch.
+3. **Echoes consolidate INTO the established side.** When recent code
+   duplicates older code, extend the original and delete the echo — not the
+   reverse. The established side has the consumers and the bug-fix history.
+4. **Fix the doc or delete the doc — never leave it lying.** A stale standards
+   doc actively misleads every agent that reads it.
+
+## The Sweep
+
+### Step 1: Recent re-implementations (echoes)
+
+```bash
+scip-query recent-duplicates --window 100
+```
+
+- `ECHO` — recent code duplicating established code. Read both sides, then
+  migrate the echo's callers to the established symbol and delete the echo.
+- `TWIN` — both sides landed recently (often one agent session duplicating
+  itself). Pick the better-placed one, consolidate before they diverge.
+- Widen `--window` on slow-moving repos; narrow it right after a big agent
+  session.
+
+### Step 2: Drifting and lying docs
+
+```bash
+scip-query doc-drift
+scip-query doc-drift AGENTS.md     # detail mode for one doc
+```
+
+- `BROKEN REFERENCE` lines are the worst class: the doc cites files that no
+  longer exist. Fix those citations first.
+- `referenced by doc` subjects changed after the doc's last update — re-read
+  the subject files and update the doc's claims (or delete the doc).
+- Re-run after updating: staleness should drop to 0 for the docs you touched.
+
+### Step 3: Speculative generality
+
+```bash
+scip-query unused-params
+```
+
+Trailing parameters no body uses — already scoped to removals that are
+type-safe by construction (TS/JS, trailing-only, no parameter properties).
+Drop the parameters and any arguments at call sites.
+
+### Step 4: Hidden coupling
+
+```bash
+scip-query co-change
+```
+
+File pairs that repeatedly change in the same commits with NO dependency
+edge: hand-synchronized artifacts (schema ↔ inventory doc ↔ generator
+script, backend schema ↔ frontend store, .env.example ↔ env parser).
+For each pair, either name the shared concept in code (one source of truth)
+or add a contract test that fails when one side changes without the other.
+
+### Step 5: Compiler-verified deletion
+
+```bash
+scip-query cleanup-plan --verify
+```
+
+- Batches are ordered: batch 0 is graph-fact dead now; batch n is dead once
+  batch n-1 lands (the cascade). Apply ONE batch at a time.
+- `COMPILER-VERIFIED` means the deletion was applied in a throwaway worktree
+  and your own checker (tsc / cargo check) passed differentially.
+- `FAILED` errors name real references — usually barrel export lines or
+  imports that must be removed together with the symbol, occasionally a
+  detector false positive. Investigate before deleting anything.
+- The `blocked` list explains why candidates can't cascade (e.g. a spec file
+  still references them).
+
+### Step 6: Ratchet it
+
+```bash
+scip-query health --write-baseline   # commit .scipquery-baseline.json
+scip-query health --baseline         # exit 1 on any NEW finding — wire into CI
+scip-query diff-gate                 # per-diff gate: echoes, missing partners, uncited docs
+```
+
+`diff-gate` is the leading indicator: run it on every agent commit / PR
+(`--base origin/main` in CI). Each finding carries a remediation the agent
+can apply directly.
+
+After each cleanup round, re-run `--write-baseline` to ratchet the count
+down. The gate is "don't get worse" — objective and ungameable.
+
+## Before Writing New Code (prevention)
+
+Tell implementing agents to run these BEFORE writing a helper or reading a
+standard:
+
+```bash
+scip-query plan-context <symbol-or-file>   # structure + HISTORY (churn, co-change partners)
+scip-query similar <new-function-name>     # does this already exist?
+scip-query doc-drift <standard.md>         # is the standard I'm about to follow stale?
+```
+
+The HISTORY section of plan-context lists the files that usually change with
+the target — the edit checklist that prevents the drift this skill cleans up.
+
+## Reporting
+
+End with a prioritized summary:
+
+1. Echoes/twins consolidated (LOC removed, callers migrated)
+2. Docs fixed vs deleted (staleness before → after)
+3. Compiler-verified deletions applied (LOC, batches)
+4. Hidden couplings resolved (named mechanism or contract test added)
+5. Baseline ratcheted: N findings → M

package/skills/scip-debloat/SKILL.md

@@ -9,6 +9,8 @@ keywords: [debloat, clean, cleanup, refactor, dead-code, duplication, dry, conso
 
 You are performing a comprehensive codebase audit to find every opportunity to reduce bloat, eliminate duplication, consolidate similar code, remove unnecessary abstractions, and improve structural health. You are thorough — you check from every angle, not just the obvious ones. Every finding must come from `scip-query`.
 
+This is not a score-maxing workflow. Health scores, finding counts, and LOC totals are diagnostic signals. The objective is to make the codebase easier to understand and safer to change by removing unnecessary structure, naming hidden policies, and preserving real behavior.
+
 ---
 
 ## When to Use This Skill
@@ -28,19 +30,47 @@ You are performing a comprehensive codebase audit to find every opportunity to r
 
 1. **Run `scip-query health` first.** It aggregates all analyses and gives you the prioritized starting point. Don't skip it.
 
-2. **Check from every angle.** Dead code is the easy win. Go deeper — similar functions, stale abstractions, wrapper indirection, pattern drift, convergence opportunities, passthrough functions. Each catches a different class of bloat.
+2. **Do not chase the score.** Do not recommend work merely because it raises `health`, reduces a detector count, or deletes LOC. A finding is actionable only when the change removes a real maintenance burden while preserving required behavior.
+
+3. **Check from every angle.** Dead code is the easy win. Go deeper — similar functions, stale abstractions, wrapper indirection, pattern drift, convergence opportunities, passthrough functions. Each catches a different class of bloat.
 
-3. **Verify before recommending deletion.** Before saying "delete X," confirm it's truly unused: check `scip-query refs`, `scip-query affected`, and whether it's an entry point (CLI, worker, test file). Entry points appear dead because nothing imports them.
+4. **Verify before recommending deletion.** Before saying "delete X," confirm it's truly unused: check `scip-query refs`, `scip-query affected`, and whether it's an entry point (CLI, worker, test file). Entry points appear dead because nothing imports them.
 
-4. **Produce concrete actions.** Don't say "there's some duplication." Say "functions A and B have 80% callee overlap — consolidate into a shared helper with the 2 divergent callees as parameters (per `scip-query convergence A B`)."
+5. **Distinguish accidental variation from essential variation.** Accidental variation is difference in code shape that does not reflect a real behavior, domain, runtime, or compatibility difference. Essential variation is difference that must remain because the real units differ. Consolidate the first; preserve the second.
 
-5. **The report goes in `reports/debloat/YYYY-MM-DD-<scope>.md`.** If no reports directory exists, use the project root.
+6. **Produce concrete actions.** Don't say "there's some duplication." Say "functions A and B have 80% callee overlap — consolidate into a shared helper with the 2 divergent callees as parameters (per `scip-query convergence A B`)."
+
+7. **The report goes in `reports/debloat/YYYY-MM-DD-<scope>.md`.** If no reports directory exists, use the project root.
 
 ---
 
+## Start Here: The Verified Pipeline
+
+Before working the angles below one by one, run the high-leverage trio:
+
+```bash
+scip-query cleanup-plan --verify     # cascade dead-code plan, COMPILER-VERIFIED per batch
+scip-query recent-duplicates         # recent code that re-implements established code
+scip-query doc-drift                 # docs whose referenced code moved on without them
+```
+
+`cleanup-plan --verify` subsumes the manual dead-code workflow: it runs dead
+code to a fixpoint (deleting batch 0 makes batch 1 dead), applies each batch
+in a throwaway worktree, and runs the project's own checker (tsc / cargo
+check) differentially. Only act on batches stamped COMPILER-VERIFIED; FAILED
+output names the references the static evidence missed. For AI-generated
+codebases specifically, prefer the dedicated scip-ai-cleanup skill.
+
+After cleanup, ratchet the result so it never regresses:
+
+```bash
+scip-query health --write-baseline   # commit .scipquery-baseline.json
+scip-query health --baseline         # CI gate: exit 1 on any NEW finding
+```
+
 ## Symbol Lookup Tips
 
-scip-query accepts partial symbol names — you don't need the full SCIP symbol path. These all work:
+`scip-query` accepts partial symbol names — you don't need the full SCIP symbol path. These all work:
 
 ```bash
 scip-query code processVegaMention              # just the function name
@@ -67,7 +97,7 @@ scip-query code 'src/modules/chat/chat.service.ts:100-200'
 
 **If "Symbol not found":**
 1. Try a shorter/simpler name — `login` instead of `AuthService:login`
-2. Try `scip-query symbols <file>` to see what symbols exist in the file
+2. Try `scip-query outline <file>` to see what symbols exist in the file
 3. Try `scip-query trace <name>` which uses a different lookup path
 4. Use the `file:line-line` syntax for `code` if you know the location
 
@@ -276,7 +306,7 @@ scip-query reindex                         # Ensure index is fresh
 scip-query health                          # Get the full report
 ```
 
-Read the health score, the findings breakdown, and the prioritized action list. This is your roadmap.
+Read the health score, the findings breakdown, and the prioritized action list as evidence. They are not the goal. Use them to find places where unnecessary structure, hidden policy, accidental variation, or disconnected code creates maintenance cost.
 
 ### Phase 2: Deep Scan (10-15 minutes)
 

package/skills/scip-explore/SKILL.md

@@ -24,19 +24,21 @@ You are exploring a codebase to build a deep, accurate understanding of how a sy
 
 ## Hard Rules
 
-1. **Every claim must come from scip-query.** If you say "function X calls function Y," you must have run `scip-query call-graph X` or `scip-query code X` to verify it. No memory. No assumptions.
+1. **Use a current index.** Before exploration, run `scip-query status` when available and check whether the index is missing, stale, or built for a different project root. If the codebase has changed, the status is uncertain, or the user asks for current facts, run `scip-query reindex` before trusting results. If reindexing fails, report that the index may be stale and mark affected claims as unverified.
 
-2. **Read the code.** Don't describe what a function "probably does" — run `scip-query code <symbol>` and describe what it actually does.
+2. **Every claim must come from scip-query.** If you say "function X calls function Y," you must have run `scip-query call-graph X` or `scip-query code X` to verify it. No memory. No assumptions.
 
-3. **Follow the graph, not the folder structure.** File organization can be misleading. Use `scip-query deps`, `scip-query rdeps`, `scip-query call-graph`, and `scip-query dataflow` to trace actual execution paths.
+3. **Read the code.** Don't describe what a function "probably does" — run `scip-query code <symbol>` and describe what it actually does.
 
-4. **Start wide, then narrow.** Begin with `scip-query system` for the module map, then drill into specific symbols with `scip-query call-graph`, `scip-query code`, and `scip-query dataflow`.
+4. **Follow the graph, not the folder structure.** File organization can be misleading. Use `scip-query deps`, `scip-query rdeps`, `scip-query call-graph`, and `scip-query dataflow` to trace actual execution paths.
+
+5. **Start wide, then narrow.** Begin with `scip-query system` for the module map, then drill into specific symbols with `scip-query call-graph`, `scip-query code`, and `scip-query dataflow`.
 
 ---
 
 ## Symbol Lookup Tips
 
-scip-query accepts partial symbol names — you don't need the full SCIP symbol path. These all work:
+`scip-query` accepts partial symbol names — you don't need the full SCIP symbol path. These all work:
 
 ```bash
 scip-query code processVegaMention              # just the function name
@@ -63,7 +65,7 @@ scip-query code 'src/modules/chat/chat.service.ts:100-200'
 
 **If "Symbol not found":**
 1. Try a shorter/simpler name — `login` instead of `AuthService:login`
-2. Try `scip-query symbols <file>` to see what symbols exist in the file
+2. Try `scip-query outline <file>` to see what symbols exist in the file
 3. Try `scip-query trace <name>` which uses a different lookup path
 4. Use the `file:line-line` syntax for `code` if you know the location
 
@@ -71,6 +73,17 @@ scip-query code 'src/modules/chat/chat.service.ts:100-200'
 
 ## Exploration Workflow
 
+### Step 0: Verify the index
+
+Start by making sure the SCIP facts are current enough to trust:
+
+```bash
+scip-query status                    # Check index location, freshness, and project root
+scip-query reindex                   # Run when missing, stale, uncertain, or after code changes
+```
+
+If `status` is unavailable or inconclusive, run `scip-query stats` and `scip-query reindex` when the repository has changed. Do not explore from an index you know is stale.
+
 ### Step 1: Orient — What are we looking at?
 
 Start with the high-level map. Run these first:
@@ -78,7 +91,7 @@ Start with the high-level map. Run these first:
 ```bash
 scip-query stats                      # How big is this codebase?
 scip-query system <module>            # Full module map: files, symbols, deps
-scip-query symbols <entry-file>       # What's in the entry point?
+scip-query outline <entry-file>       # What's in the entry point?
 ```
 
 **Output:** List all files in the module, the key symbols, what it depends on, and what depends on it. This is your map.
@@ -152,7 +165,7 @@ scip-query complexity X               # How complex is it
 
 ### "What happens when a user does Y?"
 
-1. Find the entry point: `scip-query files <handler-pattern>` or `scip-query symbols <route-file>`
+1. Find the entry point: `scip-query files <handler-pattern>` or `scip-query outline <route-file>`
 2. Read the handler: `scip-query code <handler>`
 3. Follow each call: `scip-query call-graph <callee>` → `scip-query code <callee>` → repeat
 4. Trace the data: `scip-query dataflow <key-variable>` at each step
@@ -207,7 +220,7 @@ Every file path, line number, and behavioral claim includes the scip-query comma
 | Purpose | Command |
 |---|---|
 | Read source code | `scip-query code <symbol> [-C N]` |
-| All symbols in a file | `scip-query symbols <file>` |
+| All symbols in a file | `scip-query outline <file>` |
 | Find files | `scip-query files <pattern>` |
 | Full module map | `scip-query system <module>` |
 | True public API | `scip-query surface <module>` |

package/skills/scip-language-playbook/SKILL.md

@@ -27,7 +27,7 @@ Run these in almost every codebase, regardless of language:
 ```bash
 scip-query stats
 scip-query files <feature-or-module-name>
-scip-query symbols <file>
+scip-query outline <file>
 scip-query trace <symbol>
 scip-query code <symbol>
 ```
@@ -68,7 +68,7 @@ Vue note: `.vue` single-file components are handled by the same path. scip-query
 
 Use first:
 ```bash
-scip-query symbols <file>
+scip-query outline <file>
 scip-query outline <file>
 scip-query system <module-or-file>
 scip-query imports <file>
@@ -209,7 +209,7 @@ Use first:
 scip-query trace <symbol>
 scip-query call-graph <symbol>
 scip-query refs <symbol>
-scip-query symbols <file>
+scip-query outline <file>
 scip-query outline <file>
 ```
 
@@ -347,7 +347,7 @@ scip-query extract-candidates
 
 ```bash
 scip-query files <feature>
-scip-query symbols <file>
+scip-query outline <file>
 scip-query trace <entry-symbol>
 scip-query call-graph <entry-symbol>
 scip-query code <entry-symbol>