scip-query 0.10.12 → 0.12.0

package/skills/scip-doc-reconcile/SKILL.md

@@ -1,100 +1,89 @@
 ---
 name: scip-doc-reconcile
-description: Reconcile standards docs and living documentation with the current code using scip-query doc-drift evidence. Updates descriptive claims, repairs broken file references, and escalates normative violations instead of silently blessing them. Ends with staleness driven to zero.
+description: Reconcile living docs with current code using scip-query doc-drift. Use for stale standards, broken file references, docs that cite moved code, agent guidance, or normative contradictions between documentation and implementation.
+commands:
+  - template: "scip-query doc-drift --json --full"
+    when: "Build the worklist: every stale-doc candidate, ranked."
+  - template: "scip-query doc-drift <doc>"
+    when: "Reconcile one doc: staleness detail for a single target."
+  - template: "scip-query outline <subject-file>"
+    when: "Reconcile one doc: current shape of the code the doc describes."
+  - template: "scip-query trace <symbol>"
+    when: "Reconcile one doc: verify a symbol the doc mentions still exists as described."
+  - template: "scip-query code <symbol>"
+    when: "Reconcile one doc: re-derive a snippet from current source."
 ---
 
-# Doc Reconciliation with scip-query
+# scip-doc-reconcile
 
-Standards docs exist so agents implement consistently. When the code moves and
-the doc doesn't, every agent that reads it implements against a dead spec.
-This skill reconciles docs with reality — using evidence, not memory.
+Use this skill to make living documentation true again. A living doc is documentation agents or maintainers use to make present-day changes, such as AGENTS.md, CLAUDE.md, standards, command docs, or workflow docs.
 
-## The One Rule That Matters
+Load shared mechanics from [`../_shared/SKILL.md`](../_shared/SKILL.md).
 
-A doc contains two kinds of statements, and they drift differently:
+<!-- BEGIN GENERATED SKILL COMMANDS -->
+## Commands for this skill
 
-- **Descriptive** ("the horses workflow lives in `workflows/horses.ts` and
-  exposes `listHorses`") — when code moved on, **update the doc**.
-- **Normative** ("all routes MUST validate stable scope before querying") —
-  when code violates it, **do NOT rewrite the standard to bless the
-  violation**. Either fix the code to comply, or record the contradiction in
-  the report for a human decision. Silently weakening a standard to match
-  drifted code is worse than the drift.
+| Command | Purpose | When |
+| --- | --- | --- |
+| `scip-query doc-drift --json --full` | Stale-doc candidates: code the doc references or co-changed with kept changing after the doc stopped | Build the worklist: every stale-doc candidate, ranked. |
+| `scip-query doc-drift <doc>` | Stale-doc candidates: code the doc references or co-changed with kept changing after the doc stopped | Reconcile one doc: staleness detail for a single target. |
+| `scip-query outline <subject-file>` | Tree view of symbols in a file, with line ranges | Reconcile one doc: current shape of the code the doc describes. |
+| `scip-query trace <symbol>` | Trace a symbol: definition + all references | Reconcile one doc: verify a symbol the doc mentions still exists as described. |
+| `scip-query code <symbol>` | Read the source code for a symbol (bounded to its definition range) | Reconcile one doc: re-derive a snippet from current source. |
 
-When unsure which kind a statement is: MUST/SHOULD/NEVER language is
-normative; file paths, symbol names, and behavior descriptions are
-descriptive.
+Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only when it is insufficient.
+<!-- END GENERATED SKILL COMMANDS -->
+
+## Rule
+
+Separate statement types:
+
+- 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 them, fix the code or escalate the contradiction; do not weaken the standard silently.
+
+This distinction is the core of doc reconciliation.
 
 ## Workflow
 
-### 1. Build the evidence-backed worklist
+### 1. Build the worklist
 
 ```bash
-scip-query status --capabilities
-# If freshness is stale, missing, or unknown:
-# scip-query reindex
-scip-query doc-drift                      # all living docs, ranked by staleness
-scip-query doc-drift agent-os/standards   # scoped to a standards tree
+scip-query doc-drift --json --full
+scip-query doc-drift <doc-or-tree>
 ```
 
-Triage order:
-1. Docs with `BROKEN REFERENCE` lines (the spec cites deleted code — actively wrong)
-2. Highest staleness score
-3. Docs agents read most (AGENTS.md, CLAUDE.md, standards indexes)
+Prioritize broken references, highest staleness, then docs agents read most. Do not reconcile archival records such as dated plans, ADRs, or reports — list them in `.scipquery.json` `docs.snapshotPaths` so `doc-drift` excludes them with a labeled exclusion instead of resurfacing them every sweep.
 
-Track each doc as a task. Archival docs (dated plans, ADRs, reports) are
-excluded automatically — do not "reconcile" records of past decisions.
+This step is complete only when each target doc is selected for a current-use reason.
 
-### 2. Reconcile one doc at a time
+### 2. Reconcile one doc
 
-For each doc, gather what actually changed:
+For each doc:
 
 ```bash
-scip-query doc-drift <doc>                            # its subjects + changes since
-git log --oneline -15 -- <subject-file>               # WHY the subject changed
-scip-query outline <subject-file>                     # what it looks like NOW
-scip-query system <module>                            # current module shape
-scip-query trace <symbol-the-doc-mentions>            # does it still exist? who uses it?
+scip-query doc-drift <doc>
+scip-query outline <subject-file>
+scip-query system <module>
+scip-query trace <symbol-the-doc-mentions>
+scip-query code <symbol>
 ```
 
-Then edit the doc:
+Use Git history only to understand why a subject changed, not 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 current source evidence. Re-derive snippets from `scip-query code`. Record normative contradictions instead of changing standards to bless drifted code.
 
-- **Broken references**: find where the code went (`scip-query files <stem>`,
-  `git log --follow`) and update the citation — or delete the claim if the
-  capability is gone.
-- **Stale descriptive claims**: re-read the subject files and rewrite the
-  claims to match current behavior. Every concrete claim you write must be
-  something you verified with a scip-query command this session — no claims
-  from memory.
-- **Examples and snippets**: re-derive them from current code
-  (`scip-query code <symbol>`), don't patch them by eye.
-- **Normative violations found while reading**: add them to the report under
-  "Standard vs code contradictions" with file:line evidence. Do not edit the
-  normative text.
+This step is complete only when every edited claim is supported by evidence from this session.
 
-### 3. Verify, per doc and overall
+### 3. Verify
 
 ```bash
-scip-query doc-drift <doc>     # staleness must drop to 0, broken refs to none
-scip-query diff-gate --json    # your own doc edits gate clean before commit
+scip-query doc-drift <doc>
 ```
 
-A doc still showing staleness after your edit means a subject changed in
-ways you haven't reflected — go back.
+Invoke `scip-verify` when the documentation change is part of a codebase diff. The doc is complete only when staleness drops to zero or the remaining contradiction is explicitly reported.
 
 ### 4. Report
 
-- Per doc: staleness before → after, broken references fixed, claims updated.
-- **Standard vs code contradictions** (normative): each with the standard's
-  requirement, the violating file:line, and a recommendation (fix code /
-  amend standard) — explicitly awaiting a human call.
-- Docs recommended for deletion (describe removed capabilities entirely).
-
-## Hard Rules
+Report staleness before and after, broken references fixed, claims updated, normative contradictions, and docs recommended for deletion.
 
-1. Every updated claim cites the scip-query command that verified it (in the
-   commit message or PR description).
-2. Never weaken normative language to match drifted code.
-3. Never reconcile archival docs (plans, ADRs, reports) — they are records.
-4. One commit per doc (or tight group) so review is per-standard.
-5. Re-run `scip-query doc-drift` at the end; the summary line is the result.
+Do not claim reconciliation is done until `doc-drift` has been rerun.

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.