scip-query 0.1.0

package/skills/scip-debloat/SKILL.md

@@ -0,0 +1,413 @@
+---
+name: scip-debloat
+description: Comprehensive codebase de-bloating using scip-query. Finds dead code, duplication, unnecessary abstractions, consolidation opportunities, pattern drift, and structural bloat from every possible angle. Produces a prioritized action list.
+allowed-tools: [Bash, Write, Edit, Glob, Agent, TaskCreate, TaskUpdate, TaskGet, TaskList]
+keywords: [debloat, clean, cleanup, refactor, dead-code, duplication, dry, consolidate, simplify, reduce, bloat, unused, stale, drift, health]
+---
+
+# Codebase De-Bloating with scip-query
+
+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`.
+
+---
+
+## When to Use This Skill
+
+- "Clean up this codebase"
+- "Find dead code"
+- "What can we delete?"
+- "Find duplication"
+- "Make this codebase smaller"
+- "Are there things we can consolidate?"
+- "Run a health check"
+- "De-bloat this module"
+
+---
+
+## Hard Rules
+
+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.
+
+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. **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. **The report goes in `reports/debloat/YYYY-MM-DD-<scope>.md`.** If no reports directory exists, use the project root.
+
+---
+
+## Symbol Lookup Tips
+
+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
+scip-query call-graph ChatService               # just the class name
+scip-query trace getActiveInferenceConfig       # any unique substring
+```
+
+**Avoid parentheses** — `()` causes shell parse errors in zsh/bash:
+```bash
+# BAD — shell tries to execute a subshell
+scip-query code processVegaMention()
+
+# GOOD — no parens needed, scip-query strips them internally
+scip-query code processVegaMention
+
+# ALSO GOOD — single quotes protect special characters
+scip-query code 'processVegaMention'
+```
+
+**Read source by file + line range** when the symbol name is ambiguous:
+```bash
+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
+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
+
+---
+
+## The 10 Angles of Bloat
+
+Run every one of these. Each catches a different class of problem. Skip none.
+
+### Angle 1: Dead Code (zero references)
+
+```bash
+scip-query dead --min-loc 5 --skip-barrels
+```
+
+Symbols with zero cross-file references. The `--skip-barrels` flag excludes references through barrel re-exports (index.ts) which can hide truly dead code.
+
+**What to look for:**
+- "dead code" = not referenced anywhere, not even in same file → safe to delete
+- "dead export" = used locally but never imported → make private or delete the export
+- Ignore entry points: `cli.ts`, worker files, `index.ts` barrels appear dead because they're consumed by the runtime, not by other source files
+
+**Action:** Delete dead code. Remove `export` from dead exports.
+
+### Angle 2: Isolated Symbols (completely disconnected)
+
+```bash
+scip-query isolated --min-loc 3
+```
+
+Stricter than dead code — these symbols reference nothing AND are referenced by nothing. Completely disconnected from the codebase graph.
+
+**Action:** Delete. These are the safest deletions possible.
+
+### Angle 3: Similar Functions (callee overlap)
+
+```bash
+scip-query similar --min-similarity 0.5 --min-callees 3
+```
+
+Functions that call the same set of symbols. High Jaccard similarity = doing the same work.
+
+For each high-similarity pair, get the consolidation prescription:
+
+```bash
+scip-query convergence <symbolA> <symbolB>
+```
+
+This shows: shared callees (common body), unique callees (parameterization points), and a recommended strategy.
+
+**What to look for:**
+- Pairs above 70% = strong consolidation candidates
+- Pairs above 50% = worth investigating, may share a common helper
+- Same file = less interesting. Cross-file = more valuable to consolidate.
+
+**Action:** Extract shared logic into a common helper. Pass divergent callees as parameters or strategy callbacks.
+
+### Angle 4: Similar Files (dependency profile overlap)
+
+```bash
+scip-query similar-files --min-similarity 0.6 --min-deps 3
+```
+
+Files that import the same set of modules. These are structurally doing the same job.
+
+**What to look for:**
+- 90%+ similarity with different unique deps = copy-paste variants
+- 100% similarity = likely redundant modules that should be merged or share a base
+
+**Action:** Merge or extract a shared base module.
+
+### Angle 5: Similar Chains (parallel end-to-end flows)
+
+```bash
+scip-query similar-chains --min-similarity 0.5
+```
+
+End-to-end dependency flows that are structurally similar but diverge at a few points. These represent "two parallel mechanisms doing the same thing."
+
+**What to look for:**
+- Chains with 1-2 divergence points = strongest consolidation signal
+- Common prefix = shared entry path
+- Common suffix = shared exit path
+- Divergence points = where to extract a shared abstraction
+
+**Action:** Extract the common chain into a shared pipeline. The divergence points become pluggable strategies.
+
+### Angle 6: Extraction Candidates (large functions with callee clusters)
+
+```bash
+scip-query extract-candidates --min-loc 15 --min-callees 5
+```
+
+Large functions where the callees form distinct, isolated clusters. Each cluster is a natural "Extract Method" seam.
+
+**What to look for:**
+- Clusters with high isolation (>80%) = clean extraction
+- Multiple clusters in one function = the function is doing too many things
+
+**Action:** Extract each isolated cluster into its own function.
+
+### Angle 7: Wrapper Functions (single-consumer indirection)
+
+```bash
+scip-query wrapper-candidates --max-loc 15
+```
+
+Small functions called by exactly one consumer. If the consumer is widely used but the wrapper has only one caller, the wrapper may be unnecessary indirection.
+
+**What to look for:**
+- LOC < 10 + single caller = strong inline candidate
+- The caller's fan-in tells you how "public" the wrapper's consumer is
+
+**Action:** Inline the wrapper into its single consumer, unless it serves a testing/dependency-inversion purpose.
+
+### Angle 8: Passthrough Functions (pure forwarding)
+
+```bash
+scip-query passthrough-candidates --max-loc 15
+```
+
+Functions with exactly one callee and small LOC. They just forward to another function without adding logic.
+
+**Action:** Inline or verify they exist for a structural reason (DI, testing boundary).
+
+### Angle 9: Stale Abstractions (over-engineering)
+
+```bash
+scip-query stale-abstractions --min-loc 3
+```
+
+Types, interfaces, and classes with 0-1 cross-file consumers. An interface with one implementation isn't an abstraction — it's indirection. A type used by one file isn't reusable — it's premature.
+
+**What to look for:**
+- 0 consumers = completely unused type → delete
+- 1 consumer = single-use abstraction → inline into the consumer or merge
+
+**Action:** Delete unused types. Inline single-consumer types.
+
+### Angle 10: Pattern Drift (convention violations)
+
+```bash
+scip-query drift --min-deviation 30
+```
+
+Files that deviate from their directory's typical dependency pattern. If 8 of 10 services import a validator and 2 don't, those 2 are flagged.
+
+**What to look for:**
+- Missing expected deps = the file isn't following conventions (may be missing validation, logging, etc.)
+- Unexpected deps = the file depends on things its siblings don't (may be reaching into the wrong layer)
+- Barrel files (index.ts) and orchestrators naturally deviate — ignore those
+
+**Action:** Bring drifted files into line with their neighbors, or document why the deviation is intentional.
+
+### Angle 11: Redundant Re-exports (dead barrel entries)
+
+```bash
+scip-query redundant-reexports
+```
+
+Barrel files (index.ts) that re-export symbols nobody actually imports through the barrel. If every consumer imports directly from the source file, the re-export is dead weight.
+
+**What to look for:**
+- Symbols with 0 barrel consumers = completely redundant re-export
+- Symbols where barrel consumers < direct consumers = barrel mostly bypassed
+
+**Action:** Remove unused re-exports from barrel files to reduce indirection.
+
+### Angle 12: Similar Signatures (same-shape functions)
+
+```bash
+scip-query similar-signatures --min-loc 5
+```
+
+Functions with the same parameter types and return type but different names. "Same shape" is a different signal from "same callees" — catches cases where two functions accept and return the same things even if they do different work internally.
+
+**What to look for:**
+- Groups of 3+ functions with identical signatures = strong consolidation signal
+- Groups of 2 with identical signatures + similar callees = very strong signal
+- Cross-reference with `scip-query convergence` for the consolidation prescription
+
+**Action:** Investigate whether same-shape functions can share an implementation or a common interface.
+
+---
+
+## Structural Assessment (run alongside the 12 angles)
+
+These provide context for the cleanup, not direct actions:
+
+```bash
+scip-query cycles                          # Circular dependencies (must fix)
+scip-query deep-chains --min-depth 5       # Excessively deep dependency chains
+scip-query bottlenecks -n 10               # Coupling pressure points
+scip-query complexity-hotspots -n 10       # Riskiest symbols
+scip-query hotspots -n 10                  # Most-referenced symbols
+scip-query test-coverage                   # Test coverage percentage
+scip-query doc-coverage --min-loc 5        # Documentation coverage
+```
+
+---
+
+## Workflow
+
+### Phase 1: Health Check (5 minutes)
+
+```bash
+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.
+
+### Phase 2: Deep Scan (10-15 minutes)
+
+Run all 10 angles plus the structural assessment. For each:
+1. Run the command
+2. Record the count and top findings
+3. For actionable findings, drill deeper (e.g., `convergence` for similar pairs)
+
+Use parallel subagents for speed — each angle is independent.
+
+### Phase 3: Synthesize (5 minutes)
+
+Produce the de-bloat report. Group findings by priority:
+
+1. **Safe deletions** (dead code, isolated symbols) — zero risk, immediate LOC reduction
+2. **Structural fixes** (cycles, stale abstractions) — fix architecture issues
+3. **Consolidation** (similar functions, similar files, similar chains) — reduce duplication
+4. **Extraction** (extract candidates, large functions) — reduce complexity
+5. **Indirection removal** (wrappers, passthroughs) — simplify call chains
+6. **Convention alignment** (drift) — improve consistency
+
+### Phase 4: Estimate Impact
+
+For each group, calculate:
+- Number of symbols affected
+- Lines of code recoverable
+- Risk level (low/medium/high)
+- Effort level (low/medium/high)
+
+---
+
+## Output Format
+
+The report is a markdown file with:
+
+```markdown
+# De-Bloat Report: [project/module]
+**Date:** YYYY-MM-DD
+**Health Score:** N/100
+**Scope:** [files analyzed]
+
+## Summary
+- Total findings: N
+- Estimated recoverable LOC: N
+- Safe deletions: N symbols
+- Consolidation candidates: N pairs
+- Structural issues: N
+
+## Priority 1: Safe Deletions
+[List of dead code and isolated symbols with file:line references]
+
+## Priority 2: Structural Fixes
+[Cycles, stale abstractions with fix recommendations]
+
+## Priority 3: Consolidation Opportunities
+[Similar pairs with convergence prescriptions]
+
+## Priority 4: Extraction Opportunities
+[Large functions with cluster analysis]
+
+## Priority 5: Indirection Removal
+[Wrappers and passthroughs with inline recommendations]
+
+## Priority 6: Convention Alignment
+[Drifted files with expected vs actual deps]
+
+## Structural Metrics
+- Circular dependencies: N
+- Max dependency chain depth: N
+- Coupling bottlenecks: [top 5]
+- Complexity hotspots: [top 5]
+- Test coverage: N%
+- Doc coverage: N%
+```
+
+Every finding includes the scip-query command that produced it.
+
+---
+
+## Subagent Briefing Template
+
+When using parallel subagents to scan different angles simultaneously:
+
+```
+## Task: Run de-bloat angle [N]
+
+You are scanning a codebase for cleanup opportunities using scip-query.
+
+Run the following command and analyze the results:
+[specific scip-query command]
+
+For each finding:
+1. Record the symbol, file, line range, and LOC
+2. Verify it's a true positive (not an entry point, not a test helper)
+3. Classify: safe deletion / consolidation candidate / extraction candidate / indirection
+4. Estimate effort: low (delete/inline) / medium (extract/refactor) / high (restructure)
+
+Report format: one finding per line with file:line, symbol name, classification, and the scip-query command that found it.
+
+Do NOT use grep, rg, or Read. Use only scip-query commands.
+```
+
+---
+
+## scip-query Quick Reference
+
+| Angle | Command |
+|---|---|
+| Full health report | `scip-query health` |
+| Dead code | `scip-query dead --min-loc 5 --skip-barrels` |
+| Isolated symbols | `scip-query isolated --min-loc 3` |
+| Similar functions | `scip-query similar --min-similarity 0.5` |
+| Consolidation prescription | `scip-query convergence <a> <b>` |
+| Similar files | `scip-query similar-files --min-similarity 0.6` |
+| Similar chains | `scip-query similar-chains --min-similarity 0.5` |
+| Extraction candidates | `scip-query extract-candidates --min-loc 15` |
+| Wrappers | `scip-query wrapper-candidates --max-loc 15` |
+| Passthroughs | `scip-query passthrough-candidates` |
+| Stale abstractions | `scip-query stale-abstractions --min-loc 3` |
+| Pattern drift | `scip-query drift --min-deviation 30` |
+| Circular dependencies | `scip-query cycles` |
+| Dependency depth | `scip-query deep-chains --min-depth 5` |
+| Coupling pressure | `scip-query bottlenecks -n 10` |
+| Complexity hotspots | `scip-query complexity-hotspots -n 10` |
+| Most-referenced | `scip-query hotspots -n 10` |
+| Test coverage | `scip-query test-coverage` |
+| Doc coverage | `scip-query doc-coverage` |
+| Redundant re-exports | `scip-query redundant-reexports` |
+| Similar signatures | `scip-query similar-signatures --min-loc 5` |
+| Read source | `scip-query code <symbol>` |
+| Verify references | `scip-query refs <symbol>` |
+| Check blast radius | `scip-query affected <symbol>` |

package/skills/scip-explore/SKILL.md

@@ -0,0 +1,235 @@
+---
+name: scip-explore
+description: Deep codebase exploration using scip-query. Trace how any system works end-to-end — call graphs, data flow, dependencies, blast radius — using compiler-resolved analysis. Use when you need to understand how something works before answering questions or making changes.
+allowed-tools: [Bash, Write, Edit, Glob, Agent, TaskCreate, TaskUpdate, TaskGet, TaskList]
+keywords: [explore, understand, trace, investigate, how-does, explain, architecture, flow, debug, navigate, codebase]
+---
+
+# Codebase Exploration with scip-query
+
+You are exploring a codebase to build a deep, accurate understanding of how a system works. Every claim must come from `scip-query` — not from memory, not from grep, not from file reads. You are producing verified knowledge about how code actually behaves, not guesses about how it might behave.
+
+---
+
+## When to Use This Skill
+
+- "How does X work?"
+- "What happens when a user does Y?"
+- "Walk me through the flow from A to B"
+- "What depends on this module?"
+- "Is it safe to change this?"
+- "Help me understand this codebase"
+
+---
+
+## 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.
+
+2. **Read the code.** Don't describe what a function "probably does" — run `scip-query code <symbol>` and describe what it actually does.
+
+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.
+
+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`.
+
+---
+
+## Symbol Lookup Tips
+
+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
+scip-query call-graph ChatService               # just the class name
+scip-query trace getActiveInferenceConfig       # any unique substring
+```
+
+**Avoid parentheses** — `()` causes shell parse errors in zsh/bash:
+```bash
+# BAD — shell tries to execute a subshell
+scip-query code processVegaMention()
+
+# GOOD — no parens needed, scip-query strips them internally
+scip-query code processVegaMention
+
+# ALSO GOOD — single quotes protect special characters
+scip-query code 'processVegaMention'
+```
+
+**Read source by file + line range** when the symbol name is ambiguous:
+```bash
+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
+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
+
+---
+
+## Exploration Workflow
+
+### Step 1: Orient — What are we looking at?
+
+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?
+```
+
+**Output:** List all files in the module, the key symbols, what it depends on, and what depends on it. This is your map.
+
+### Step 2: Trace the entry point
+
+Find where execution starts and follow it:
+
+```bash
+scip-query call-graph <entry-symbol>  # What does it call? Who calls it?
+scip-query code <entry-symbol>        # Read the actual source
+scip-query dataflow <entry-symbol>    # What data flows through it?
+```
+
+For each callee, repeat: read the code, check the call graph, trace the dataflow. Build a chain from entry to leaf.
+
+### Step 3: Map the dependencies
+
+Understand what the system depends on and who depends on it:
+
+```bash
+scip-query deps <file>                # Forward: what does this file need?
+scip-query rdeps <file>               # Reverse: who breaks if this changes?
+scip-query surface <module>           # True public API (what consumers use)
+scip-query affected <symbol>          # Full transitive blast radius
+```
+
+### Step 4: Understand data flow
+
+For each key symbol, trace how data moves through the system:
+
+```bash
+scip-query dataflow <symbol>          # Definition sites, usage sites, producers, consumers
+scip-query slice <symbol>             # Backward: what feeds into this?
+scip-query slice <symbol> --forward   # Forward: what does this feed into?
+```
+
+### Step 5: Assess complexity and risk
+
+Identify the riskiest parts of the system:
+
+```bash
+scip-query complexity <symbol>        # Per-symbol: branches, cyclomatic, fan-in/out
+scip-query complexity-hotspots        # Top N most complex symbols
+scip-query bottlenecks                # Coupling pressure points
+scip-query change-surface <file>      # Per-file risk: consumers, test coverage
+```
+
+### Step 6: Check structural health
+
+Look for red flags:
+
+```bash
+scip-query cycles                     # Circular dependencies
+scip-query deep-chains --min-depth 5  # How deep do dependency chains go?
+scip-query coupling <file1> <file2>   # How tightly coupled are two files?
+```
+
+---
+
+## Answering Specific Questions
+
+### "How does function X work?"
+
+```bash
+scip-query code X                     # Read the source
+scip-query call-graph X               # What it calls, who calls it
+scip-query dataflow X                 # What data flows through it
+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>`
+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
+5. Map the end state: What gets written to DB? What gets sent to the client?
+
+### "Is it safe to change X?"
+
+```bash
+scip-query change-surface <file>      # Risk per symbol: consumers, tests
+scip-query affected X --max-depth 3   # Full transitive blast radius
+scip-query test-coverage X            # Do tests reference this?
+scip-query similar X                  # Is there duplicated logic to consolidate?
+```
+
+### "What's the architecture of module X?"
+
+```bash
+scip-query system X                   # Files, symbols, deps in/out
+scip-query deep-chains --scope X      # Dependency depth within the module
+scip-query bottlenecks --scope X      # Coupling hotspots
+scip-query cycles --scope X           # Any circular deps?
+scip-query hotspots --scope X         # Most-referenced symbols
+```
+
+### "How are these two things related?"
+
+```bash
+scip-query coupling <file1> <file2>   # Shared symbols between files
+scip-query convergence <sym1> <sym2>  # How similar are two functions?
+scip-query similar-chains             # Do they share dependency paths?
+```
+
+---
+
+## Output Format
+
+When reporting exploration results, structure them as:
+
+1. **Overview** — What the system is and what it does (1-3 sentences)
+2. **Entry points** — Where execution begins (files + symbols + line numbers)
+3. **Call flow** — Step-by-step trace from entry to leaf, with source citations
+4. **Data flow** — What data enters, how it transforms, where it ends up
+5. **Dependencies** — What the system depends on (with `deps` citations)
+6. **Consumers** — What depends on this system (with `rdeps`/`surface` citations)
+7. **Risk areas** — Complex symbols, high fan-in, missing tests (with `complexity`/`change-surface` citations)
+
+Every file path, line number, and behavioral claim includes the scip-query command that verified it.
+
+---
+
+## scip-query Quick Reference
+
+| Purpose | Command |
+|---|---|
+| Read source code | `scip-query code <symbol> [-C N]` |
+| All symbols in a file | `scip-query symbols <file>` |
+| Find files | `scip-query files <pattern>` |
+| Full module map | `scip-query system <module>` |
+| True public API | `scip-query surface <module>` |
+| Callers + callees | `scip-query call-graph <symbol>` |
+| Every reference | `scip-query refs <symbol>` |
+| Definition + references | `scip-query trace <symbol>` |
+| Forward dependencies | `scip-query deps <file>` |
+| Reverse dependencies | `scip-query rdeps <file>` |
+| Transitive blast radius | `scip-query affected <symbol>` |
+| Pre-change risk briefing | `scip-query change-surface <file>` |
+| Dataflow analysis | `scip-query dataflow <symbol>` |
+| Backward slice | `scip-query slice <symbol>` |
+| Forward slice | `scip-query slice <symbol> --forward` |
+| Complexity per symbol | `scip-query complexity <symbol>` |
+| Top complexity | `scip-query complexity-hotspots` |
+| Coupling pressure | `scip-query bottlenecks` |
+| Coupling between files | `scip-query coupling <file1> <file2>` |
+| Circular dependencies | `scip-query cycles` |
+| Dependency depth | `scip-query deep-chains` |
+| Similar functions | `scip-query similar <symbol>` |
+| Same-shape functions | `scip-query similar-signatures` |
+| Test coverage | `scip-query test-coverage <symbol>` |
+
+Full documentation: Run `scip-query --help` or read the README at the scip-query repo.