scip-query 0.10.11 → 0.11.0

package/skills/scip-explore/SKILL.md

@@ -1,252 +1,120 @@
 ---
 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.
+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.
+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."
+  - 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."
+  - template: "scip-query affected <symbol> --json"
+    when: "Map dependencies and consumers: downstream blast radius."
 ---
 
-# Codebase Exploration with scip-query
+# scip-explore
 
-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.
+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.
 
----
-
-## 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. **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. **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. **Read the code.** Don't describe what a function "probably does" — run `scip-query code <symbol>` and describe what it actually does.
-
-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:
-
-```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 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
-
----
-
-## Exploration Workflow
-
-### Step 0: Verify the index
+Load shared mechanics from [`../_shared/SKILL.md`](../_shared/SKILL.md).
 
-Start by making sure the SCIP facts are current enough to trust:
+<!-- BEGIN GENERATED SKILL COMMANDS -->
+## Commands for this skill
 
-```bash
-scip-query status                    # Check index location, freshness, and project root
-scip-query status --capabilities     # Reindex only when freshness is stale, missing, or unknown
-```
-
-If `status` is unavailable or inconclusive, run `scip-query stats` and then `scip-query reindex` only when the repository has changed or freshness cannot be proven. Do not explore from an index you know is stale.
-
-### Step 1: Orient — What are we looking at?
+| 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. |
 
-Start with the high-level map. Run these first:
+Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only when it is insufficient.
+<!-- END GENERATED SKILL COMMANDS -->
 
-```bash
-scip-query stats                      # How big is this codebase?
-scip-query kind-counts                # What symbol kinds dominate?
-scip-query system <module>            # Full module map: files, symbols, deps
-scip-query outline <entry-file>       # What's in the entry point?
-scip-query by-kind function --scope <module>  # Inventory one kind in scope
-```
+## Rules
 
-**Output:** List all files in the module, the key symbols, what it depends on, and what depends on it. This is your map.
+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.
 
-### Step 2: Trace the entry point
+## Workflow
 
-Find where execution starts and follow it:
+### 1. Orient
 
 ```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?
+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>
 ```
 
-For each callee, repeat: read the code, check the call graph, trace the dataflow. Build a chain from entry to leaf.
+This step is complete only when the module files, key symbols, dependencies, and reverse dependencies are mapped.
 
-### Step 3: Map the dependencies
-
-Understand what the system depends on and who depends on it:
+### 2. Trace entry points
 
 ```bash
-scip-query deps <file>                # Forward: what does this file need?
-scip-query rdeps <file>               # Reverse: who breaks if this changes?
-scip-query fan-out <file>             # External symbols this file reaches for
-scip-query surface <module>           # True public API (what consumers use)
-scip-query affected <symbol>          # Full transitive blast radius
+scip-query trace <entry-symbol>
+scip-query call-graph <entry-symbol>
+scip-query code <entry-symbol>
+scip-query dataflow <entry-symbol>
 ```
 
-### Step 4: Understand data flow
-
-For each key symbol, trace how data moves through the system:
+Repeat for important callees until the path reaches side effects, returned values, or terminal outputs.
 
-```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?
-```
+This step is complete only when the explored path connects entry point to observable effect.
 
-### Step 5: Assess complexity and risk
-
-Identify the riskiest parts of the system:
+### 3. Map dependencies and consumers
 
 ```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: external consumers, blast radius
+scip-query deps <file>
+scip-query rdeps <file>
+scip-query fan-out <file>
+scip-query surface <module>
+scip-query affected <symbol>
 ```
 
-### Step 6: Check structural health
+This step is complete only when direct dependencies, public surface, and downstream blast radius are named.
 
-Look for red flags:
+### 4. Follow data and state
 
 ```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?
+scip-query dataflow <symbol-or-variable>
+scip-query slice <symbol-or-variable>
+scip-query slice <symbol-or-variable> --forward
 ```
 
----
-
-## Answering Specific Questions
+This step is complete only when producers, transformations, storage, and consumers are identified or marked unavailable.
 
-### "How does function X work?"
+### 5. Assess risk
 
 ```bash
-scip-query code X                     # Read the source
-scip-query hierarchy X                # Symbol ancestry: method -> class -> module
-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
+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
 ```
 
-### "What happens when a user does Y?"
-
-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
-5. Map the end state: What gets written to DB? What gets sent to the client?
+This step is complete only when the explanation includes the risky symbols or states that no relevant risks appeared.
 
-### "Is it safe to change X?"
+## Question Recipes
 
-```bash
-scip-query change-surface <file>      # Risk per symbol: consumers, blast radius
-scip-query affected X --max-depth 3   # Full transitive blast radius
-scip-query similar X                  # Is there duplicated logic to consolidate?
-```
+- 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`.
 
-### "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, high-consumer surfaces, or broad blast radius (with `complexity`/`change-surface` citations)
-
-Every file path, line number, and behavioral claim includes the scip-query command that verified it.
-
----
+## Report
 
-## scip-query Quick Reference
-
-| Purpose | Command |
-|---|---|
-| Read source code | `scip-query code <symbol> [-C N]` |
-| All symbols in a file | `scip-query outline <file>` |
-| Find files | `scip-query files <pattern>` |
-| Symbol kind histogram | `scip-query kind-counts` |
-| Symbols by kind | `scip-query by-kind <kind>` |
-| Full module map | `scip-query system <module>` |
-| True public API | `scip-query surface <module>` |
-| Symbol ancestry | `scip-query hierarchy <symbol>` |
-| 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>` |
-| External symbol reach | `scip-query fan-out [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` |
-
-Full documentation: Run `scip-query --help` or read the README at the scip-query repo.
+Report overview, entry points, call flow, data flow, dependencies, consumers, risk areas, and the command citations that prove each claim. Exploration is complete only when the user can see what was proven and what remains unverified.