scip-query 0.19.4 → 0.19.5

package/skills/scip-concrete-plan/SKILL.md

@@ -1,262 +1,105 @@
 ---
 name: scip-concrete-plan
-description: Plan code changes with scip-query evidence and testable design. Use for non-trivial implementation, refactor, migration, API, or bug-fix plans before editing code; require contextual definitions, cited premises, reuse audit, test seams, counterexample attacks, and a derived verdict.
+description: Make an implementation plan or checklist before a non-trivial code change, refactor, migration, API edit, or bug fix. Uses scip-query to establish the end-to-end flow, affected consumers, and reuse options, then orders validated slices. Escalates for security, money, data migration, concurrency, and irreversible changes.
 commands:
-  - template: "scip-query status --capabilities"
-    when: "Discover: confirm the index is fresh before citing graph facts."
-  - template: "scip-query plan-context <target>"
-    when: "Discover: anchor the plan with pre-edit context for the target."
-  - template: "scip-query refs <symbol>"
-    when: "Premises: enumerate every writer and reader of a touched state surface; reuse audit: find existing consumers."
-  - template: "scip-query dataflow <symbol-or-variable>"
-    when: "Premises: producers and consumers backing a state-authority premise."
-  - template: "scip-query code <symbol>"
-    when: "Premises: read source before citing a behavior claim."
-  - template: "scip-query trace <symbol>"
-    when: "Verify the plan: rerun source-producing context for cited targets."
+  - template: 'scip-query status --capabilities'
+    when: 'Discover: confirm the index is fresh before citing graph facts.'
+  - template: 'scip-query plan-context <target>'
+    when: 'Discover: the one call that anchors the plan — flow, consumers, impact, reuse, history.'
+  - template: 'scip-query refs <symbol>'
+    when: 'Scope: enumerate consumers when plan-context bounds a section you need in full.'
+  - template: 'scip-query affected <symbol>'
+    when: 'Scope: transitive blast radius when the change is not consumer-local.'
+  - template: 'scip-query code <symbol>'
+    when: 'Flow: read source behind a behavior claim you are about to write down.'
 ---
 
 # Concrete Plan
 
-Use this skill to write an implementation plan that another agent can execute without guessing and a reviewer can check without re-deriving. A concrete plan is a certificate: a dated Markdown document whose conclusion — ready to implement — is derived from numbered, source-cited premises, defended against constructed counterexamples, and shaped so the intended behavior is easy to test before it is easy to ship.
+Write an implementation plan another agent can execute without guessing and a reviewer can check
+without re-deriving. Two modes: **ordinary** by default, **high-assurance** when the change earns
+it. Pick the mode first — running the certificate on routine work is how planning becomes a tax
+people route around.
 
-Load shared mechanics from [`../_shared/SKILL.md`](../_shared/SKILL.md) when you need lookup tips, command families, postchecks, or subagent rules.
+Load shared mechanics from [`../_shared/SKILL.md`](../_shared/SKILL.md) when you need lookup tips,
+command families, postchecks, or subagent rules.
 
 <!-- BEGIN GENERATED SKILL COMMANDS -->
 ## Commands for this skill
 
-| Command | Purpose | When |
-| --- | --- | --- |
-| `scip-query status --capabilities` | Show index status for this project | Discover: confirm the index is fresh before citing graph facts. |
-| `scip-query plan-context <target>` | Pre-edit planning context for a symbol, file, or module | Discover: anchor the plan with pre-edit context for the target. |
-| `scip-query refs <symbol>` | Find all files referencing a symbol | Premises: enumerate every writer and reader of a touched state surface; reuse audit: find existing consumers. |
-| `scip-query dataflow <symbol-or-variable>` | Reference-level dataflow: definition sites, usage sites, producers, consumers | Premises: producers and consumers backing a state-authority premise. |
-| `scip-query code <symbol>` | Read the source code for a symbol (bounded to its definition range) | Premises: read source before citing a behavior claim. |
-| `scip-query trace <symbol>` | Trace a symbol: definition + all references | Verify the plan: rerun source-producing context for cited targets. |
+| Command | Purpose | Returns | Coverage | When |
+| --- | --- | --- | --- | --- |
+| `scip-query status --capabilities` | Show index status for this project | freshness, generation, language shards, watcher, and optional capabilities | `complete` | Discover: confirm the index is fresh before citing graph facts. |
+| `scip-query plan-context <target>` | Pre-edit planning context for a symbol, file, or module | definitions and references; callers and callees; dataflow producers and consumers; backward and forward slices; affected symbols; change-surface risk; dependencies and reverse dependencies; module files and exports; external surface use; complexity; churn; co-change partners; active suppressions | `bounded` | Discover: the one call that anchors the plan — flow, consumers, impact, reuse, history. |
+| `scip-query refs <symbol>` | Find all files referencing a symbol | referencing file paths; reference line numbers grouped by file | `bounded` | Scope: enumerate consumers when plan-context bounds a section you need in full. |
+| `scip-query affected <symbol>` | Transitive closure of symbols that could break if this symbol changes | affected symbol identities, files, and traversal depths | `bounded` | Scope: transitive blast radius when the change is not consumer-local. |
+| `scip-query code <symbol>` | Read the source code for a symbol (bounded to its definition range) | definition identity, source, and line range | `complete` | Flow: read source behind a behavior claim you are about to write down. |
 
 Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only when it is insufficient.
 <!-- END GENERATED SKILL COMMANDS -->
 
-## Rules
+## Pick the mode
 
-1. Start with `scip-query status --capabilities`; reindex only when freshness is `stale`, `missing`, or `unknown`.
-2. Anchor the plan with `scip-query plan-context <target>`. If the target is not indexed, record that fact and use scip-query for every code-adjacent claim it can answer.
-3. Put the plan in `docs/plans/YYYY-MM-DD-<short-name>.md`.
-4. Define every load-bearing concept contextually and state every invariant in `iff` or `must always` form. A definition without referents (a `Source:` line) is a guess.
-5. Evidence lives in numbered premises (`P1`, `P2`, ...), each with a `Source` naming the scip-query command that produced it. Every shared-state surface the plan touches gets a state-authority premise enumerating its complete writer and reader sets.
-6. Steps and defenses cite the premises they depend on. A claim no premise supports is either new evidence to gather or an explicit `ASSUMPTION` — never silent.
-7. Do not propose a new helper, wrapper, type, parameter, config flag, component, hook, or module until the reuse audit proves reuse or extension is not the better move.
-8. Every behavior-changing step includes a testability design: test seam, injected dependencies, pure core, side-effect boundary, and validation.
-9. Attack entries must be constructed scenarios — actor, starting state, sequence — and each ends in a recorded outcome: `HELD` citing the defending step and premises, or `HOLE` with its repair step or accepted reason. An assertion of absence ("no new shared mutable state") is not a defense; it cannot fail, so it cannot catch anything.
-10. Installing an enforcer — trigger, constraint, guard, gate — opens an enforcement window: every existing writer in the relevant state-authority premise must be brought into compliance in the same or an earlier step, or the window recorded as an accepted hole. Every step declares `Deployable`.
-11. The verdict is derived, not asserted: `PLANNED-COMPLETE` only when the coverage matrix has no blank rows and every attack ends in `HELD` with citations or an accepted hole. An attack record where nothing ever broke is a red flag — attacks run against a draft should find holes; if none did, rerun the pass as falsification, preferably in a fresh subagent context.
+Load [`HIGH_ASSURANCE.md`](HIGH_ASSURANCE.md) — numbered premises, state-authority inventories,
+counterexample attacks, enforcement windows, a derived verdict — when the change touches any of:
 
-## Planning Terms
+- a security boundary or authorization decision;
+- money, billing, or anything with an external financial effect;
+- a destructive or irreversible operation;
+- a persistent-data migration;
+- shared-state concurrency;
+- a broad public API change;
+- a rollout that cannot be rolled back;
+- or the user explicitly asks for the rigorous version.
 
-A reuse audit is the part of a plan that proves a proposed new symbol, file, option, wrapper, or contract is needed; what makes it useful is that it ties the new shape to existing definitions, consumers, and rejected extension points.
+Otherwise use ordinary mode below. When genuinely unsure, ask rather than defaulting up: the
+certificate is expensive, and the cost lands on every future change through the same skill.
 
-A test seam is the entry point a test can call to prove a behavior without replaying the whole product path; what makes it valuable in a plan is that it names the exact unit or boundary where correctness will be observed.
+## Ordinary mode
 
-A side-effect boundary is the edge where deterministic program decisions meet files, processes, clocks, networks, databases, or other external capabilities; what makes it important is that failures and fakes can be isolated there while core decisions stay easy to test.
-
-A contract is the stable promise one code unit exposes to another, including accepted inputs, returned outputs, errors, timing expectations, and side effects that callers may rely on.
-
-An invariant is a property of the changed system that must hold at every observable moment; what makes it load-bearing is that attacks are judged against it and the final verdict is derived from whether it survives them all.
-
-A premise is a numbered, source-cited statement of fact about the current code; what makes it a premise rather than a note is that steps and defenses cite it by ID, so a false premise is traceable to everything built on it.
-
-A state-authority premise is a premise that enumerates the complete writer and reader sets of one shared state surface; what makes it powerful is that "complete" is falsifiable with `refs` and `dataflow`, turning a forgotten write path from an unknowable into a checkable omission.
-
-A counterexample attack is a concrete actor, starting state, and action sequence constructed to violate an invariant; what makes it evidence is that its defense cites premises and steps, so "we considered failure" becomes "this specific failure is blocked here."
-
-An enforcement window is the interval between the step that installs an invariant enforcer and the step that brings the last existing writer into compliance; what makes it dangerous is that during it, every unupdated writer fails the new check in production, so the plan that adds safety is itself the outage.
-
-## Workflow
-
-### 1. Discover
-
-Run:
+Start here:
 
 ```bash
-scip-query status --capabilities
-scip-query plan-context <target>
-```
-
-Use the shared reference for follow-up commands. Fill four gates before designing:
-
-```markdown
-## Goal
-What the user is trying to accomplish and what done looks like for them.
-
-## Definitions & Invariants
-For each load-bearing concept: its wider class, then the one trait that causally
-explains its other traits in this codebase — with the referents. Then the
-invariants the change must preserve, in iff / must-always form.
-
-## Current State
-A short narrative of the affected end-to-end flow. Every factual sentence
-cites a premise by ID.
-
-## Reuse Audit
-For every new symbol or file being considered: reuse target, extension target,
-or evidence-backed reason new code is justified.
-```
-
-Definition discipline: place the concept in its wider class, then name the essential trait — the one that makes the concept's other traits in this codebase possible and explains them. Do not label genus or differentia; write it as prose. Ban circular and synonym definitions ("the refresh coordinator coordinates refreshes" defines nothing). Any new term the plan introduces gets defined the same way. Good definitions condense: they imply the concept's other traits instead of listing them, and derived requirements fall out of them — if restore is defined as the inverse of cancel, then the privilege to restore must not be weaker than the privilege to cancel, and a plan that gates them asymmetrically must defend that asymmetry.
-
-This step is complete only when the concepts are defined with referents, the invariants are stated formally, and every proposed new unit has a reuse decision with citations.
-
-### 2. Establish Premises
-
-Number every fact the plan depends on:
-
-```markdown
-## Premises
-
-- P1. <current behavior fact> — Source: `scip-query code <symbol>`
-- P2. Writers of `<state surface>`: <complete list>. Readers: <complete list>.
-  — Source: `scip-query refs <symbol>` + `scip-query dataflow <symbol>`
-- P3. ASSUMPTION: <belief the evidence cannot yet confirm, and what would confirm it>
-```
-
-State-authority rule: for every state surface the plan touches — database column, store field, event topic, endpoint, cache entry — write one premise enumerating its complete writer and reader sets. Completeness comes from `refs` and `dataflow`, not memory.
-
-Why this premise class exists: a sprint-restore plan hardened `restore()` and the cancellation path but never enumerated the writers of sprint status. Review found `PATCH /sprints/:id` could set `status: 'active'` around every restore invariant, and transition automations wrote `sprintId` straight past the new membership guard — two of that review's five ship-blockers, both sitting in the writer list one `refs` call would have produced. With a state-authority premise, each writer in the list must be visited by an attack; without it, the side doors are invisible until review.
-
-This step is complete only when every state surface named in any phase has a state-authority premise and every remaining unknown is an explicit `ASSUMPTION`.
-
-### 3. Shape for Tests
-
-Before writing implementation phases, add:
-
-```markdown
-## Testability Design
-
-| Behavior | Test seam | Dependencies to inject | Pure core | Side-effect shell | Contract |
-| --- | --- | --- | --- | --- | --- |
-| <behavior> | <test entry point> | <clock/db/http/logger/etc.> | <calculation/decision function> | <I/O wrapper> | <small interface or call shape> |
+scip-query status --capabilities     # reindex only if stale, missing, or unknown
+scip-query plan-context <target>     # flow, consumers, impact, reuse signals, history
 ```
 
-Plan the code so tests can call the pure core directly and exercise the side-effect shell with injected replacements. Prefer this shape:
+`plan-context` already returns definitions, references, callers, callees, dataflow, forward and
+backward slices, affected symbols, change-surface risk, dependencies, module exports, external
+surface use, complexity, churn, co-change partners, and suppressions. Your job is to interpret
+that composite — not to rebuild a proof system on top of it. Reach for a second command only when
+a section you need came back bounded, or the target was not indexed.
 
-1. Parse and validate at the boundary.
-2. Pass domain data and injected dependencies into a small orchestrator.
-3. Put calculations, filtering, selection, formatting decisions, and state transitions in pure functions.
-4. Keep database, network, filesystem, clock, randomness, logging, email, and payment calls in thin side-effect shells.
-5. Depend on small contracts at boundaries; avoid broad option objects, booleans that hide behavior, and wrappers that merely forward.
+Put the plan in `docs/plans/YYYY-MM-DD-<short-name>.md` with these sections:
 
-This step is complete only when every changed behavior has a named test seam and the plan makes clear which logic can be tested without real external services.
+**Goal** — what the user is trying to accomplish, and what done looks like for them.
 
-### 4. Design the Checklist
+**Current flow** — the affected path from entry point to observable effect, in prose, with the
+evidence behind each claim. If you cannot describe the current behavior end to end, you are not
+ready to change it.
 
-Write phases in execution order. Keep each phase deployable or explicitly mark why it is not. Use this step format:
+**Affected consumers** — who calls, imports, or reads what you are about to change, and what
+breaks if the contract shifts. Say whether the list is complete or bounded; a capped list you
+present as complete is worse than one you flag.
 
-```markdown
-### N.M - Imperative title
-
-- [ ] **File**: `path/to/file.ts:LINE-LINE`
-- **Premises**: P<n>, P<m>
-- **Deployable**: yes | no — <reason> | part of single-deploy group <name>
-- **What**: Current behavior verified from source.
-- **Change**: Exact edit to make.
-- **Testability**:
-  - Test seam:
-  - Injected dependencies:
-  - Pure core:
-  - Side-effect shell:
-  - Contract:
-- **Validation**: Targeted test, smoke command, or manual check that proves the behavior.
-- **Why**: Why this step is needed and why this order is safe, citing the premises it rests on.
-```
-
-If a step installs an enforcer — trigger, constraint, guard, gate — check its enforcement window here: every existing writer in the relevant state-authority premise is brought into compliance in the same or an earlier step, or the window is carried into the attack record as a hole to accept or repair.
-
-This step is complete only when no checklist item says "update this file" without exact current behavior, target behavior, cited premises, a deployability declaration, and validation.
-
-### 5. Attack the Plan
-
-Construct counterexamples against every invariant. This pass is falsification, not defense: it succeeds by finding holes, and against a draft it should find some. Prefer delegating it to a fresh subagent when the environment can spawn one — give the adversary only the Definitions & Invariants, Premises, state-authority maps, and the checklist, not your design rationale, and brief it that it wins by producing holes; fold its findings back as HOLE entries and repair steps. Solo fallback: enumerate the full attack list from the coverage-matrix rows below before writing any Outcome line, so attacks cannot be shaped around defenses you already have.
-
-Use the lenses as attack prompts — purpose, blast radius, valid intermediate state, reversibility, failure, concurrency, boundaries, data integrity, observability, human experience, efficiency, reuse, testability — and record each attack in this form:
-
-```markdown
-### A<n>. <invariant> via <lens>
-- Attack: <actor> + <starting state> + <action sequence>
-- Outcome: HELD — defended by step <N.M> (P<i>, P<j>)
-  | HOLE — repaired by new step <N.M>
-  | HOLE — accepted: <reason>
-```
-
-A `HELD` that cannot name its defending step and premises is not `HELD`; it is a hole wearing confidence. A repaired hole keeps its `HOLE — repaired by step N.M` label permanently — do not rewrite it to `HELD` after the repair, because the repair history is the evidence that the pass falsified. The verdict's repaired count must equal the number of `HOLE — repaired` entries in the record. Close the record with a coverage matrix — one row per writer in every state-authority premise and per applicable lens (valid intermediate state is always applicable when any step installs an enforcer or migration):
-
-```markdown
-| Surface or lens | Attacks |
-| --- | --- |
-| <writer, reader, or lens> | A2, A7 |
-```
-
-A blank row is an unattacked writer. The record is incomplete until every row names an attack or carries an accepted reason. Spread attacks across rows before deepening one: depth on the axis you already anticipated does not protect the axes you did not — the leaks come from blank rows, not from the tenth variation of the race you already modeled.
-
-Invalid entry — this exact shape preceded three post-review remediation rounds on a real plan:
-
-> **Concurrency**: Validation happens before database writes; no new shared mutable state or retry behavior is introduced.
-
-It names no actor, no interleaving, and cites nothing. It is an assertion of absence: it cannot fail, so it caught nothing — review later found exactly the race it waved away. A valid entry for the same phase:
-
-> ### A3. "Every stored value is a member of its field's option set" via concurrency
-> - Attack: admin removes option O in transaction A while a user writes value O in transaction B; interleaving B-validates → A-commits → B-commits persists an orphaned value.
-> - Outcome: HOLE — repaired by new step 2.2: validation reads the option definition outside B's lock (P4), so serialize definition changes with every value writer via FOR UPDATE on the definition row; regression proves both interleavings against PostgreSQL.
-
-This step is complete only when the coverage matrix has no blank rows and every attack entry ends in a cited `HELD` or a recorded `HOLE`.
-
-### 6. Verify the Plan and Derive the Verdict
-
-Run or delegate phase-by-phase reference checks. Each verifier confirms:
-
-- every path exists;
-- every line range is still within about five lines;
-- every premise reproduces when its `Source` command is rerun — a premise that no longer reproduces is false, and everything citing it is suspect until fixed;
-- every behavior claim matches source;
-- every new unit has reuse evidence;
-- every behavior-changing step has cited premises, a validation command, and a testability design.
-
-Then rerun the source-producing context for the cited targets:
-
-```bash
-scip-query plan-context <target>
-```
-
-Use the shared reference for subagent briefing text when delegating. Close the plan by applying the definitions to the record — do not summarize feelings:
-
-```markdown
-## Verdict
-
-A plan is PLANNED-COMPLETE iff the coverage matrix has no blank rows, every
-attack ends in HELD with cited steps and premises or an accepted hole with a
-written reason, and no premise failed reverification.
-
-Result: PLANNED-COMPLETE | INCOMPLETE — <n> attacks, <x> holes repaired,
-<y> holes accepted; <unresolved items>
-```
+**Reuse decision** — for every new helper, wrapper, type, parameter, flag, component, hook, or
+module: the thing it could have extended instead, and why extension loses. New parallel code with
+no reuse decision is the single most common defect this skill exists to prevent.
 
-The counts are part of the verdict. "16 attacks, 0 holes repaired" against a fresh draft is not a strong plan; it is an attack pass that defended instead of falsified — rerun it before shipping the plan.
+**Slices** — ordered implementation steps. Each names its files and symbols, the behavior change,
+and the validation that proves it: a test, a command, or a specific manual check. A slice with no
+validation is a wish.
 
-This step is complete only when stale references are fixed, every premise reverified, and the verdict line is derived from the attack record.
+**Risks and unknowns** — what could go wrong, what you could not establish, and any rollout
+constraint. Unknowns stay explicit; do not round them to assumptions.
 
-## Output Shape
+## Done when
 
-The plan file contains:
+- the entry-to-effect path is described and evidenced;
+- every affected consumer is assigned to a slice or explicitly out of scope;
+- every new unit has a reuse decision;
+- every slice has validation;
+- unknowns are written down rather than resolved by guessing.
 
-1. Title and date.
-2. Goal.
-3. Definitions & Invariants.
-4. Premises (including state-authority premises and explicit assumptions).
-5. Current State (narrative citing premise IDs).
-6. Reuse Audit.
-7. Testability Design.
-8. Design Phases (steps citing premises, each with a deployability declaration).
-9. Attack Record (attacks with outcomes, holes repaired or accepted, coverage matrix).
-10. Execution Order and deployable phase notes.
-11. Ship Order with one-way doors flagged.
-12. Verdict with attack and hole counts.
-13. Summary of files to create, edit, delete, and verify.
+Then implement the plan in the smallest coherent slice, and run `scip-verify` when the change
+lands.

package/skills/scip-conductor/SKILL.md

@@ -2,17 +2,17 @@
 name: scip-conductor
 description: Plan and conduct multi-step engineering programs like a skeptical principal engineer. Use for writing executable multi-phase plans, delegating implementation, reviewing another agent's work, or carrying a large change end to end with verification at every handoff.
 commands:
-  - template: "scip-query plan-context <target>"
+  - template: 'scip-query plan-context <target>'
     when: "Anchor each phase's step before delegating it."
-  - template: "scip-query diff-gate --json"
-    when: "Verify a handoff before accepting it and before closing the program."
-  - template: "scip-query health --json"
-    when: "Pre-register or check a program-level health benchmark."
+  - template: 'scip-query diff-gate --json'
+    when: 'Verify a handoff before accepting it and before closing the program.'
+  - template: 'scip-query health --json'
+    when: 'Pre-register or check a program-level health benchmark.'
 ---
 
 # scip-conductor
 
-This skill is how to run a *program* of work — planning, delegation, review,
+This skill is how to run a _program_ of work — planning, delegation, review,
 and closure — not how to write one change plan (use a dedicated planning
 skill such as `scip-concrete-plan` for individual changes when one is available).
 
@@ -21,11 +21,11 @@ Load shared mechanics from [`../_shared/SKILL.md`](../_shared/SKILL.md).
 <!-- BEGIN GENERATED SKILL COMMANDS -->
 ## Commands for this skill
 
-| Command | Purpose | When |
-| --- | --- | --- |
-| `scip-query plan-context <target>` | Pre-edit planning context for a symbol, file, or module | Anchor each phase's step before delegating it. |
-| `scip-query diff-gate --json` | Gate the current diff: architecture regressions plus echo, migration, coordination, doc-drift, unused-param, and new-dead candidates; exit 1 on blocking findings | Verify a handoff before accepting it and before closing the program. |
-| `scip-query health --json` | Composite codebase health report with prioritized action list | Pre-register or check a program-level health benchmark. |
+| Command | Purpose | Returns | Coverage | When |
+| --- | --- | --- | --- | --- |
+| `scip-query plan-context <target>` | Pre-edit planning context for a symbol, file, or module | definitions and references; callers and callees; dataflow producers and consumers; backward and forward slices; affected symbols; change-surface risk; dependencies and reverse dependencies; module files and exports; external surface use; complexity; churn; co-change partners; active suppressions | `bounded` | Anchor each phase's step before delegating it. |
+| `scip-query diff-gate --json` | 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` | Verify a handoff before accepting it and before closing the program. |
+| `scip-query health --json` | Composite codebase health report with prioritized action list | health score, findings, priorities, baselines, and coverage notes | `bounded` | Pre-register or check a program-level health benchmark. |
 
 Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only when it is insufficient.
 <!-- END GENERATED SKILL COMMANDS -->
@@ -53,7 +53,7 @@ Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only
 - **Every step carries five fields**: file anchor with verified current
   behavior (cite how you know); the exact change; the validation command
   with expected output; testability design (pure core, injected effects);
-  why this step is safe *in this order*. "Update X" with no current/target
+  why this step is safe _in this order_. "Update X" with no current/target
   behavior is a wish, not a step.
 - **Order phases by information gain and risk**: blockers and
   evidence-integrity first; cheap discriminating probes before expensive
@@ -82,7 +82,7 @@ Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only
   If a collision happens anyway: stop racing, apply-verify-commit
   atomically in one action, and re-sequence to a single writer.
 - **Never accept a report — reproduce its evidence.** On every handoff,
-  choose the *minimal discriminating probe*: the one command most likely to
+  choose the _minimal discriminating probe_: the one command most likely to
   expose the report being wrong (a mutation input, a hand count, the
   benchmark number), and run it yourself. A report verified by reading it
   is not verified.
@@ -123,7 +123,7 @@ the pre-registered benchmarks and their before/after values; each handoff's
 discriminating probe and its OBSERVED result (a probe listed but not run
 counts as not run); the deviation ledger; the DEFER list;
 which learnings were folded back and where. A reviewer must be able to
-audit the *conduct*, not just the artifact.
+audit the _conduct_, not just the artifact.
 
 ## Completion
 

package/skills/scip-debug/SKILL.md

@@ -1,19 +1,19 @@
 ---
 name: scip-debug
-description: Debug bugs and regressions with scip-query evidence. Use for failing behavior, wrong data flow, confusing runtime paths, broken tests, root-cause analysis, reproduction, tracing, or minimal fixes.
+description: Debug why something is broken, does not work, crashes, fails a test, returns wrong data, or regressed. Uses scip-query to trace the runtime path and data flow, separate rival causes, and make the smallest verified fix.
 commands:
-  - template: "scip-query files <feature-or-error-term>"
-    when: "Find the entry point from a feature name or error term."
-  - template: "scip-query trace <candidate-symbol>"
-    when: "Find the entry point: definition plus every reference."
-  - template: "scip-query call-graph <entry-symbol>"
-    when: "Follow execution: callers and callees along the failing path."
-  - template: "scip-query dataflow <symbol-or-variable>"
-    when: "Follow data: producers, consumers, and usage sites."
-  - template: "scip-query similar <suspect-symbol> --json --full"
-    when: "Compare nearby implementations for missing guards or handling."
-  - template: "scip-query change-surface <suspect-file> --json --full"
-    when: "Bound the fix: exports, consumers, and blast-radius risk."
+  - template: 'scip-query files <feature-or-error-term>'
+    when: 'Find the entry point from a feature name or error term.'
+  - template: 'scip-query trace <candidate-symbol>'
+    when: 'Find the entry point: definition plus every reference.'
+  - template: 'scip-query call-graph <entry-symbol>'
+    when: 'Follow execution: callers and callees along the failing path.'
+  - template: 'scip-query dataflow <symbol-or-variable>'
+    when: 'Follow data: producers, consumers, and usage sites.'
+  - template: 'scip-query similar <suspect-symbol> --json --full'
+    when: 'Compare nearby implementations for missing guards or handling.'
+  - template: 'scip-query change-surface <suspect-file> --json --full'
+    when: 'Bound the fix: exports, consumers, and blast-radius risk.'
 ---
 
 # scip-debug
@@ -25,14 +25,14 @@ Load shared mechanics from [`../_shared/SKILL.md`](../_shared/SKILL.md).
 <!-- BEGIN GENERATED SKILL COMMANDS -->
 ## Commands for this skill
 
-| Command | Purpose | When |
-| --- | --- | --- |
-| `scip-query files <feature-or-error-term>` | Find files matching a pattern | Find the entry point from a feature name or error term. |
-| `scip-query trace <candidate-symbol>` | Trace a symbol: definition + all references | Find the entry point: definition plus every reference. |
-| `scip-query call-graph <entry-symbol>` | Show incoming callers and outgoing callees for a symbol | Follow execution: callers and callees along the failing path. |
-| `scip-query dataflow <symbol-or-variable>` | Reference-level dataflow: definition sites, usage sites, producers, consumers | Follow data: producers, consumers, and usage sites. |
-| `scip-query similar <suspect-symbol> --json --full` | Find heuristic function similarity candidates from callee fingerprints | Compare nearby implementations for missing guards or handling. |
-| `scip-query change-surface <suspect-file> --json --full` | Pre-change briefing: exports, consumers, and blast-radius risk | Bound the fix: exports, consumers, and blast-radius risk. |
+| Command | Purpose | Returns | Coverage | When |
+| --- | --- | --- | --- | --- |
+| `scip-query files <feature-or-error-term>` | Find files matching a pattern | matching file paths | `complete` | Find the entry point from a feature name or error term. |
+| `scip-query trace <candidate-symbol>` | Trace a symbol: definition + all references | definition sites with source and signature; referencing files with line numbers | `bounded` | Find the entry point: definition plus every reference. |
+| `scip-query call-graph <entry-symbol>` | Show incoming callers and outgoing callees for a symbol | caller and callee symbol identities with files | `bounded` | Follow execution: callers and callees along the failing path. |
+| `scip-query dataflow <symbol-or-variable>` | Reference-level dataflow: definition sites, usage sites, producers, consumers | definition sites, usage sites, producer symbols, and consumer symbols | `bounded` | Follow data: producers, consumers, and usage sites. |
+| `scip-query similar <suspect-symbol> --json --full` | Find heuristic function similarity candidates from callee fingerprints | symbol pairs, similarity scores, and shared evidence | `bounded` | Compare nearby implementations for missing guards or handling. |
+| `scip-query change-surface <suspect-file> --json --full` | Pre-change briefing: exports, consumers, and blast-radius risk | defined symbols, external consumer counts, and risk levels | `bounded` | Bound the fix: exports, consumers, and blast-radius risk. |
 
 Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only when it is insufficient.
 <!-- END GENERATED SKILL COMMANDS -->

package/skills/scip-diagram/SKILL.md

@@ -2,18 +2,18 @@
 name: scip-diagram
 description: Diagram code with scip-query evidence. Use for code flow diagrams, architecture diagrams, data-flow maps, dependency maps, blast-radius visuals, module maps, or HTML artifacts explaining a system.
 commands:
-  - template: "scip-query system <module>"
-    when: "Collect evidence: module map for a dependency or architecture diagram."
-  - template: "scip-query trace <symbol>"
-    when: "Collect evidence: definition plus references for a call-flow diagram."
-  - template: "scip-query call-graph <symbol>"
-    when: "Collect evidence: callers/callees for a call-flow diagram."
-  - template: "scip-query dataflow <symbol>"
-    when: "Collect evidence: producers/consumers for a data-flow diagram."
-  - template: "scip-query affected <symbol> --json"
-    when: "Collect evidence: blast-radius nodes and edges."
-  - template: "scip-query change-surface <file> --json --full"
-    when: "Collect evidence: exports and consumers for a change-surface map."
+  - template: 'scip-query system <module>'
+    when: 'Collect evidence: module map for a dependency or architecture diagram.'
+  - template: 'scip-query trace <symbol>'
+    when: 'Collect evidence: definition plus references for a call-flow diagram.'
+  - template: 'scip-query call-graph <symbol>'
+    when: 'Collect evidence: callers/callees for a call-flow diagram.'
+  - template: 'scip-query dataflow <symbol>'
+    when: 'Collect evidence: producers/consumers for a data-flow diagram.'
+  - template: 'scip-query affected <symbol> --json'
+    when: 'Collect evidence: blast-radius nodes and edges.'
+  - template: 'scip-query change-surface <file> --json --full'
+    when: 'Collect evidence: exports and consumers for a change-surface map.'
 ---
 
 # scip-diagram
@@ -25,14 +25,14 @@ Load shared mechanics from [`../_shared/SKILL.md`](../_shared/SKILL.md).
 <!-- BEGIN GENERATED SKILL COMMANDS -->
 ## Commands for this skill
 
-| Command | Purpose | When |
-| --- | --- | --- |
-| `scip-query system <module>` | Full module map: files, symbols, deps in/out | Collect evidence: module map for a dependency or architecture diagram. |
-| `scip-query trace <symbol>` | Trace a symbol: definition + all references | Collect evidence: definition plus references for a call-flow diagram. |
-| `scip-query call-graph <symbol>` | Show incoming callers and outgoing callees for a symbol | Collect evidence: callers/callees for a call-flow diagram. |
-| `scip-query dataflow <symbol>` | Reference-level dataflow: definition sites, usage sites, producers, consumers | Collect evidence: producers/consumers for a data-flow diagram. |
-| `scip-query affected <symbol> --json` | Transitive closure of symbols that could break if this symbol changes | Collect evidence: blast-radius nodes and edges. |
-| `scip-query change-surface <file> --json --full` | Pre-change briefing: exports, consumers, and blast-radius risk | Collect evidence: exports and consumers for a change-surface map. |
+| Command | Purpose | Returns | Coverage | When |
+| --- | --- | --- | --- | --- |
+| `scip-query system <module>` | Full module map: files, symbols, deps in/out | module file paths; exported symbols with line ranges; internal dependencies; reverse dependencies | `complete` | Collect evidence: module map for a dependency or architecture diagram. |
+| `scip-query trace <symbol>` | Trace a symbol: definition + all references | definition sites with source and signature; referencing files with line numbers | `bounded` | Collect evidence: definition plus references for a call-flow diagram. |
+| `scip-query call-graph <symbol>` | Show incoming callers and outgoing callees for a symbol | caller and callee symbol identities with files | `bounded` | Collect evidence: callers/callees for a call-flow diagram. |
+| `scip-query dataflow <symbol>` | Reference-level dataflow: definition sites, usage sites, producers, consumers | definition sites, usage sites, producer symbols, and consumer symbols | `bounded` | Collect evidence: producers/consumers for a data-flow diagram. |
+| `scip-query affected <symbol> --json` | Transitive closure of symbols that could break if this symbol changes | affected symbol identities, files, and traversal depths | `bounded` | Collect evidence: blast-radius nodes and edges. |
+| `scip-query change-surface <file> --json --full` | Pre-change briefing: exports, consumers, and blast-radius risk | defined symbols, external consumer counts, and risk levels | `bounded` | Collect evidence: exports and consumers for a change-surface map. |
 
 Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only when it is insufficient.
 <!-- END GENERATED SKILL COMMANDS -->
@@ -49,14 +49,14 @@ Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only
 
 ### 1. Pick diagram type
 
-| User wants | Diagram |
-| --- | --- |
-| Feature flow | Call flow |
-| Value origin or mutation | Data flow |
-| Dependents | Blast radius |
-| Module architecture | Dependency map |
+| User wants                 | Diagram                          |
+| -------------------------- | -------------------------------- |
+| Feature flow               | Call flow                        |
+| Value origin or mutation   | Data flow                        |
+| Dependents                 | Blast radius                     |
+| Module architecture        | Dependency map                   |
 | Hard-to-change explanation | Change surface or bottleneck map |
-| Classes or ownership | Hierarchy and surface map |
+| Classes or ownership       | Hierarchy and surface map        |
 
 This step is complete only when the diagram's node and edge types are chosen.