scip-query 0.23.0 → 0.26.0

package/skills/scip-integrity-audit/SKILL.md

@@ -1,185 +1,57 @@
 ---
 name: scip-integrity-audit
-description: Audit whether implementations are real with scip-query. Use for suspected faked or half-implemented features, decorative checkers or verifiers that never fail, dead code paths hidden behind graceful fallbacks, metrics that may be lying, or a "does any of this actually work" interrogation of a system.
-metadata:
-  commands:
-    - template: 'scip-query search <text>'
-      when: 'Locate a status word, checker name, adapter, fallback, or metric producer.'
-    - template: 'scip-query outline <file>'
-      when: 'Inventory the callables in a known file before choosing a drill target.'
-    - template: 'scip-query evidence --symbol <symbol> --edge <family> --direction <direction> --depth <n> --max-edges <n>'
-      when: 'Project callers, callees, or dataflow around a checker, adapter, fallback, or metric.'
-    - template: 'scip-query inspect --at <file:line> --view behavior'
-      when: 'Read connected behavior for a named remaining gap after graph evidence.'
-    - template: 'scip-query code <selector>'
-      when: 'Read exact implementation syntax only when the body itself can change the verdict.'
-    - template: 'scip-query decorative-checkers -s <scope> --json'
-      when: 'Shortlist validate/verify/check/assert/is/has callables with no reachable failure exit.'
-    - template: 'scip-query not-implemented -s <scope> --json'
-      when: 'Shortlist reachable placeholder stubs that a real caller can actually reach.'
-    - template: 'scip-query test-quality -s <scope> --json'
-      when: 'Check regression artifacts and tests for assertion-free bodies, skip rot, and mock-echo.'
-    - template: 'scip-query twin-drift -s <scope> --json'
-      when: 'Find same-name or near-name twins whose bodies have silently diverged.'
-    - template: 'scip-query twin-ab <symbolA> <symbolB>'
-      when: 'Scaffold a table-driven comparison of two same-concept twins on a shared input.'
+description: Investigate whether a feature fulfills its promised behavior through live consumers. Find partial implementations, decorative checks, ineffective parser migrations, competing implementations, misleading results, and tests validating their own assumptions.
 ---
 
-# scip-integrity-audit
-
-<!-- BEGIN GENERATED SKILL COMMANDS -->
-## Command and question manual
-
-| Command syntax | Question it answers |
-| --- | --- |
-| `scip-query search <text>` | Locate a status word, checker name, adapter, fallback, or metric producer. |
-| `scip-query outline <file>` | Inventory the callables in a known file before choosing a drill target. |
-| `scip-query evidence --symbol <symbol> --edge <family> --direction <direction> --depth <n> --max-edges <n>` | Project callers, callees, or dataflow around a checker, adapter, fallback, or metric. |
-| `scip-query inspect --at <file:line> --view behavior` | Read connected behavior for a named remaining gap after graph evidence. |
-| `scip-query code <selector>` | Read exact implementation syntax only when the body itself can change the verdict. |
-| `scip-query decorative-checkers -s <scope> --json` | Shortlist validate/verify/check/assert/is/has callables with no reachable failure exit. |
-| `scip-query not-implemented -s <scope> --json` | Shortlist reachable placeholder stubs that a real caller can actually reach. |
-| `scip-query test-quality -s <scope> --json` | Check regression artifacts and tests for assertion-free bodies, skip rot, and mock-echo. |
-| `scip-query twin-drift -s <scope> --json` | Find same-name or near-name twins whose bodies have silently diverged. |
-| `scip-query twin-ab <symbolA> <symbolB>` | Scaffold a table-driven comparison of two same-concept twins on a shared input. |
-
-These commands are controls, not a checklist. Use every capability needed by the task, but make each query answer a distinct question. There is no required sequence or query limit. Run a command's `--help` when you need a flag not shown in its template.
-<!-- END GENERATED SKILL COMMANDS -->
-
-Use this skill to interrogate whether a system's claims are backed by real
-implementations. Structural review asks "is this well organized?"; this skill
-asks **"is this real?"** — it hunts decorative checkers, adapters written
-against imagined data, features that have silently never run, and numbers
-nobody ever recomputed.
-
-Use `$scip-query` locators and evidence projections to inventory producers.
-`health --full` does not run the integrity detectors; call
-`decorative-checkers`, `not-implemented`, `test-quality`, and `twin-drift`
-directly.
-
-## The Stance
-
-A green result you have never seen fail is unverified. Every status word,
-banner, and metric is testimony from the code, not evidence about the code —
-cross-examine the producer before believing it. The most dangerous code is
-not broken code; it is code that reports success without doing the work.
-
-## Drills
-
-Run all five over the chosen scope. Each has a checkable exit.
-
-### 1. Falsify every checker
-
-Inventory everything in scope that accepts/rejects, passes/fails, or
-validates (checkers, gates, verifiers, validators — find producers with
-`search` on the status words in output, then `evidence` execution incoming
-and outgoing). For each one, construct an input that MUST fail — a wrong
-binding, a corrupt file, an impossible value — and run it. A checker that
-passes its should-fail input is decorative: file it as a defect, not a note.
-Before filing, attempt the defense: an accusation triggers a rewrite, so
-search for the failure exit the drill may have missed — a config-gated
-branch, an async rejection, one-hop delegation (the calibration's known
-noise archetypes). File the defect with the executed should-fail input
-attached and the defense attempt noted; a defense that succeeds clears the
-checker and stays in the record as its witness.
-Complete only when every checker in scope has been witnessed rejecting a
-constructed should-fail input, or is listed with a reason it cannot be.
-
-Mechanized by: `scip-query decorative-checkers` finds `validate*`/`verify*`/
-`check*`/`assert*`/`is*`/`has*` callables with no reachable failure exit
-anywhere in their body (calibrated 2026-07-03 against two external repos —
-standalone-only; noise archetypes past one-hop delegation in
-`docs/validation/2026-07-03-integrity-detector-calibration.md`). Run it first
-to shortlist candidates before hand-constructing should-fail inputs.
-
-### 2. Diff every adapter against captured reality
-
-For each parser/adapter of an external format (tool output, XML/JSON
-schemas, protocol messages): obtain ONE real sample from the actual source
-and diff it against the code's assumptions and the tests' fixtures. Ask of
-every fixture: was this generated from reality, or imagined? A parser and a
-hand-written fixture can validate each other's shared hallucination
-indefinitely.
-Complete only when every adapter has been checked against at least one
-captured-real sample.
-
-### 3. Autopsy every fallback
-
-Graceful degradation is where dead features hide: a primary path that has
-never worked looks identical to a healthy fallback. For every catch block,
-`?? fallback`, and degraded mode in scope: produce an execution witness that
-the PRIMARY path runs (a test, a probe, a log). Use `evidence` execution and
-`inspect --view behavior` for branch reachability. A fallback that always
-fires means the feature above it is dead — date of death: birth.
-Complete only when every fallback's primary path has a witness or a filed
-defect.
-
-Mechanized by: `scip-query not-implemented` finds reachable placeholder
-stubs (`throw new Error('not implemented')`, TODO-comment + return-default,
-empty bodies) that a real caller, entry surface, or package-surface export
-can actually reach — the graph fact that separates "primary path never
-built" from `dead`'s "primary path built but unreferenced." Standalone-only
-(calibrated 2026-07-03; 0 live findings on two external repos post-fix, see
-the calibration report) — treat a clean run as "nothing this shape found,"
-not as "every fallback's primary path is proven live."
-
-### 4. Hand-compute every metric twice
-
-For each number the system reports (scores, counts, estimates): pick two
-concrete instances, compute the expected value by hand from first
-principles, and compare. Off-by-a-factor errors (double counting, inflated
-estimates) survive for years because nobody ever recomputes one sample.
-Complete only when every reported metric has two hand-verified samples.
-
-### 5. Cross-examine same-concept twins
-
-Where one concept is computed in more than one place, feed both the same
-input and require the same answer. `twin-drift` finds the same-name cases
-mechanically; for same-concept-different-name pairs, project consumers with
-`evidence` execution incoming and compare implementations with `code`. Once
-a pair is identified, `scip-query twin-ab <symbolA> <symbolB>` scaffolds a
-table-driven vitest file that imports both and asserts equal output —
-fill in the input table and run it. Disagreement between twins means at
-least one is wrong — determine which before consolidating.
-Complete only when every discovered twin pair has been compared on a shared
-input.
-
-## Severity
-
-Rank findings by what the failure does to a user who trusted the output:
-a decorative checker or false "verified" banner outranks everything; a
-dead-but-fallbacked feature outranks a wrong metric; a wrong metric outranks
-structural mess. Structural findings are real, but they are not lies — do
-not fold them into the integrity verdict.
-
-## Reporting
-
-File each finding with: the claim as displayed, the producer (file:line),
-the drill that exposed it, the should-fail input or real sample used, and
-the fix. The audit is complete only when every drill's exit criterion is
-met for the scope, and every defect found has a regression artifact — a
-test, fixture, or model that fails on the pre-fix behavior.
-
-End with a derived verdict, not an impression:
-
-```markdown
-Integrity: <scope> — <c> checkers witnessed failing, <a> adapters diffed
-against reality, <f> fallback primaries witnessed live, <m> metrics
-recomputed, <t> twins compared; <d> defects filed, <u> unverifiable (reasons)
-```
-
-A suspect scope that produces zero defects is itself a claim: state what
-made the suspicion wrong, or rerun the drill that should have caught it.
-
-A regression artifact that doesn't actually assert anything, or asserts the
-same literal it stubbed into its own mock, is a fake witness — the same
-"reports success without doing the work" failure mode this skill hunts in
-production code, just relocated to the test suite. Run `scip-query
-test-quality -s <scope>` over the audit's own regression artifacts (and,
-periodically, over the suite at large) to catch this: assertion-free test
-bodies, a skipped-test ledger with git-blame age (a skip with no fix date
-attached is a claim nobody is checking), and mock-echo (a test that only
-proves its own stub). Standalone-only, mixed precision by sub-check
-(calibrated 2026-07-03): assertion-free and skipped are high-precision;
-mock-echo is intentionally low-precision (syntactic same-literal matching,
-not dataflow) — treat its output as a reviewed candidate list, not a verdict.
+# SCIP Integrity Audit
+
+Load `$scip-query` for mechanics and `$scip-explore` when the live path is unknown. Ask “is this real?”: does the implementation produce the outcome its user or consumer relies on?
+
+Use the [implementation-integrity command guide](../scip-query/references/command-guide.md#implementation-integrity) to select a detector for a named concern. Its rows describe what each pattern can miss or misclassify; no detector replaces the live-path investigation below.
+
+An integrity defect is a mismatch between promised behavior and the behavior the live implementation provides. Establish the promise from the task, public contract, consumers, and relevant tests—not a function name alone. A fallback is an alternative selected when another implementation fails or is unavailable; its use cannot support a stronger guarantee than it provides.
+
+Do not attribute intentions such as cheating to an agent or author. Report the concrete shortcut, missing operation, unsupported claim, and consequence.
+
+## Establish promise and live path
+
+State which input should produce which result, rejection, or durable effect. Record uncertainty when requirements are unclear; do not invent a stronger feature and call its absence a defect.
+
+Trace the actual command/API/worker through selected implementations, configuration, effects, fallbacks, and consumers. Inventory plausible parallel implementations even with different names. An installed parser, new class, or unit test calling a helper does not prove production consumers use it.
+
+Choose investigations below for actual evidence gaps. There is no mandatory all-detector battery or requirement to manufacture a finding.
+
+## Investigate the mechanism
+
+| Concern                              | Investigation                                                                                                                                                                     |
+| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Success without checking             | Run valid and deliberately invalid cases through the public path with independent expected results. Inspect delegated/asynchronous failure before declaring a decorative checker. |
+| Feature works only through fallback  | Observe primary success and induced failure. Establish the selected path, result/effects, and whether degraded behavior is disclosed.                                             |
+| Parser assumes an imagined format    | Feed the actual parser/version representative captured input or valid language examples. Verify the consuming traversal and output, not a node merely appearing somewhere.        |
+| Replacement beside old mechanisms    | Trace relevant ingress/configuration variants. Compare cases distinguishing their guarantees; account for consumers and retirement.                                               |
+| Status or metric overstates evidence | Trace inputs and coverage to the supporting operation. Independently calculate distinguishing examples; test omissions, errors, and partial results.                              |
+| Tests share implementation mistakes  | Exercise a real consumer with independent expected results. Checking only a mocked value does not verify the feature.                                                             |
+
+A literal “pass” in a correctly checked branch can be justified; a computed status can be wrong. A failed branch probe is not proof of unreachability. A clean detector result establishes only that supported patterns were not found within coverage.
+
+`decorative-checkers`, `not-implemented`, `test-quality`, `incomplete-migration`, and `twin-drift` shortlist candidates. Check help and limits; run only for a relevant gap. `health` does not run every integrity detector.
+
+## Parser migration example
+
+A syntax tree represents grammatical structure; name resolution connects references to declarations; executing a test observes exercised behavior. Parsing alone cannot fulfill a promise of compiler-backed identity.
+
+For a regex-to-parser migration, exercise the live route with relevant multiline constructs, comments/strings containing code-like text, nested expressions, aliases, or shadowed names. Establish expected output independently.
+
+Look for parser wrappers still delegating to regex, copied extraction rules, unsupported syntax silently returning success, and tests bypassing the live consumer. Regex is appropriate for literal search or a deliberately bounded text format. The defect is claiming guarantees the mechanism cannot establish.
+
+Read [integrity probes](references/integrity-probes.md) when parser, fallback, or comparison details matter.
+
+## Record a justified verdict
+
+For each promise record expected behavior and its source, live producer/consumer, executed input/path, expected versus actual results/effects, verdict, limits, and regression check.
+
+Test the strongest explanation that would make suspected behavior correct: distinct contract, delegated check, compatibility path, or explicitly weaker guarantee. Preserve counterevidence. Names or different outputs alone do not establish a defect.
+
+For authorized substantial fixes use `$scip-plan`. Add a regression check distinguishing old from required behavior, fix the live owner, migrate consumers, and retire obsolete mechanisms where justified. Run behavioral tests, review actual changes, and fresh impact.
+
+Report inventory coverage separately from executed behavior. List unexercised paths and consequences. One favorable example does not verify a whole feature, and a candidate scan does not audit a whole repository.

package/skills/scip-integrity-audit/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
-  display_name: 'scip integrity audit'
-  short_description: 'Interrogate whether implementations are real: falsify checkers, diff adapters against reality, autopsy fallbacks.'
-  default_prompt: 'Run the scip-integrity-audit drills over this codebase and report every decorative checker, dead-behind-fallback feature, and lying metric.'
+  display_name: "SCIP Integrity Audit"
+  short_description: "Check whether features fulfill their promises."
+  default_prompt: "Use $scip-integrity-audit to trace promised behavior through live consumers and test for partial implementations or misleading results."

package/skills/scip-integrity-audit/references/integrity-probes.md

@@ -0,0 +1,27 @@
+# Integrity probes
+
+Use isolated fixtures, temporary repositories, or local test seams without changing user data. An execution witness records input, actual entry path, and observed results/effects. Establish expected outcomes independently.
+
+## Parsers and identities
+
+Run the parser version selected by production and pass its output through the real traversal/adapter. Assert the public result. Finding an expected node somewhere does not prove the consuming branch is reachable under its parent and guards.
+
+When identity matters, test identical spellings with different lexical owners. Exercise relevant comments, whitespace, aliases, nesting, and alternate supported forms. Disclose unsupported forms; a text approximation cannot justify a compiler-backed claim.
+
+If a probe misses a branch, question the probe, enclosing conditions, configuration, and grammar version. Establish a counterexample or grammar contradiction before declaring dead code. Capture representative real external inputs when possible; minimal grammar examples serve a distinct purpose.
+
+## Primary and fallback paths
+
+Exercise primary success, expected unavailability, meaningful failure, and consumer response. Use observable results/calls or a narrow test seam to distinguish paths. Check swallowed failures, partial state, and weakened guarantees. An intentional fallback is valid if it meets the contract or accurately reports limits; relabeling cannot fix a required missing capability.
+
+## Parallel implementations
+
+Locate ingresses and configuration variants before choosing a canonical owner. Compare contracts including errors, order, state, and compatibility. For paths intended to agree, run distinguishing inputs against both, including adverse cases. Differences can be intentional, and agreement on samples is not universal equivalence.
+
+After migration, verify routing. Importing a replacement directly in a test does not establish that the command/worker/API stopped using the old implementation.
+
+## Checks and metrics
+
+Exercise a valid case so an always-failing checker cannot look correct, and an invalid case so an always-passing checker cannot look correct. When practical, remove the relevant operation and confirm the regression check fails. Do not require destructive production execution.
+
+Recompute metric examples that distinguish plausible defects, such as double counting or missing coverage. A fixed sample count does not establish the whole calculation. Classify status by supporting evidence: constants can describe static support accurately, while computed values can overstate readiness. Follow errors, partial output, and stale inputs to consumers.

package/skills/scip-plan/SKILL.md

@@ -1,86 +1,60 @@
 ---
 name: scip-plan
-description: Write a concise, code-grounded implementation plan for a non-trivial feature, fix, refactor, migration, or retirement. Use scip-query as the primary repository exploration surface and cite exact owners, relationships, behavior, and consumers.
-metadata:
-  commands:
-    - template: 'scip-query search <text>'
-      when: 'Locate exact repository text, a runtime key, or a compiler symbol; use `scip-query search -- <text>` when the literal starts with a dash.'
-    - template: 'scip-query outline <file>'
-      when: 'Locate compiler-owned constructs in a known file.'
-    - template: 'scip-query entrypoints <text>'
-      when: 'Locate an external callable root when its entry surface is known.'
-    - template: 'scip-query evidence --symbol <symbol> --edge <family> --direction <direction> --depth <n> --max-edges <n>'
-      when: 'Project explicitly selected typed relationships from one exact root.'
-    - template: 'scip-query inspect --at <file:line> --view behavior'
-      when: 'Read connected behavior for a named implementation gap.'
-    - template: 'scip-query code <selector>'
-      when: 'Read exact source only when syntax itself can change the decision.'
-    - template: 'scip-query diff-impact'
-      when: 'Map changed symbols and downstream consumers after an edit.'
-    - template: 'scip-query architecture'
-      when: 'Validate declared structural boundaries.'
-    - template: 'scip-query health --full'
-      when: 'Run configured cleanup and quality detectors.'
+description: Plan changes by mapping the existing system end to end, finding comparable features and conventions, and documenting how to reuse or extend current owners instead of creating parallel implementations.
 ---
 
 # SCIP Plan
 
-Write a plan that another coding agent can execute without rediscovering the relevant system.
+Load `$scip-query` for mechanics and use `$scip-explore` to establish the existing behavior the change will touch. Reuse facts already established by current evidence. A plan is an ordered set of concrete changes and checks another agent can execute without rediscovering the system.
 
-<!-- BEGIN GENERATED SKILL COMMANDS -->
-## Command and question manual
+The [planning and change-review commands](../scip-query/references/command-guide.md#orientation-and-change-review) distinguish a pre-change briefing, proposed symbol impact, actual diff metrics and downstream consumers. Choose the one that settles the current planning question; do not run them all for the same fact.
 
-| Command syntax | Question it answers |
-| --- | --- |
-| `scip-query search <text>` | Locate exact repository text, a runtime key, or a compiler symbol; use \`scip-query search -- <text>\` when the literal starts with a dash. |
-| `scip-query outline <file>` | Locate compiler-owned constructs in a known file. |
-| `scip-query entrypoints <text>` | Locate an external callable root when its entry surface is known. |
-| `scip-query evidence --symbol <symbol> --edge <family> --direction <direction> --depth <n> --max-edges <n>` | Project explicitly selected typed relationships from one exact root. |
-| `scip-query inspect --at <file:line> --view behavior` | Read connected behavior for a named implementation gap. |
-| `scip-query code <selector>` | Read exact source only when syntax itself can change the decision. |
-| `scip-query diff-impact` | Map changed symbols and downstream consumers after an edit. |
-| `scip-query architecture` | Validate declared structural boundaries. |
-| `scip-query health --full` | Run configured cleanup and quality detectors. |
+Plan changes spanning owners, consumers, dependencies, migrations, or several implementation steps. Skip a document for one obvious edit. Persist substantial plans in the project's normal location, usually `docs/plans/YYYY-MM-DD-<change>.md`, when they must survive a context reset.
 
-These commands are controls, not a checklist. Use every capability needed by the task, but make each query answer a distinct question. There is no required sequence or query limit. Run a command's `--help` when you need a flag not shown in its template.
-<!-- END GENERATED SKILL COMMANDS -->
+## Map the existing system before designing the change
 
-<!-- BEGIN GENERATED EXPLORATION MANUAL -->
-### Choose a relationship deliberately
+State the requested observable outcome. Then establish how the affected operation works today, from its actual initiating surface to the result its consumer observes. Cover the relevant authorization and validation, dispatch or registration, transformations, shared services, durable state changes, runtime handoffs, notifications, returned values, and failure/recovery paths. Follow queued work through its consumer when completion depends on that consumer. Bound this investigation to facts that can change the plan; an end-to-end map does not require reading the entire repository.
 
-| Question | Evidence family | Direction |
-|---|---|---|
-| Who can call or reach this? | `execution` | `incoming` |
-| What can this call or reach? | `execution` | `outgoing` |
-| Where can this value come from? | `dataflow` | `incoming` |
-| Where can this value go? | `dataflow` | `outgoing` |
-| Which producer and consumer rendezvous? | `runtime` | `both` |
-| What resource is observed or changed? | `state` | `both` |
-| What occurs before or after this? | `temporal` | `both` |
-| What interface constrains this? | `contract` | `both` |
-| Are these observations the same entity? | `identity` | `both` |
-| What contains or owns this? | `ownership` | `both` |
-| What does this statically rely on? | `dependencies` | `outgoing` |
+Locate the entry surface with ordinary repository search; use `entrypoints` when external roots are unclear. Use `context` for reuse candidates and `evidence` for the execution, runtime or dependency relationships needed to connect the existing path and consumers. Read implementation details with ordinary file tools; symbol-aware reads are optional. Choose commands to settle facts, not to complete a fixed query checklist. A module inventory, a matching type, a helper's implementation or the first search result does not establish the operation's live path.
 
-Use exact evidence as an observed fact only within its coverage. Derived evidence is deterministically computed; candidate evidence is a lead; mixed evidence must retain its constituent strengths; unknown evidence cannot support a stronger claim. Missing output is not evidence of absence.
+Find existing features that perform the same operation or a closely related one, including features with different names that use the same resource, service, registration mechanism or state transition. Trace a relevant working example through its real consumer and shared owner. Compare its contracts with the requested change: inputs, policies, state, effects and completion behavior. If several implementations exist, establish which serves the affected entry surface, which others remain live, and whether one is a compatibility path or an incomplete migration.
 
-The controls above are complete for ordinary exploration. Run `scip-query capabilities --matrix` only when a named claim depends on uncertain provider support; do not run it for routine orientation.
-<!-- END GENERATED EXPLORATION MANUAL -->
+A shared implementation path is the connected code several features use to enforce the same rules or update the same state, such as a dispatcher, policy service and persistence operation. Identify that path before proposing a new handler, service, registry, store or copy of its rules. Find its supported extension points and the consumers they serve. Prefer extending that path and reusing its existing code when its contracts fit the request.
 
-scip-query is a repository exploration surface: an indexed code reader that joins exact current text to compiler-owned identities and typed relationships. Use it as the primary exploration surface for tracked repository text. Treat its commands as controls, not a checklist. Use every capability needed by the change, but make each query answer a distinct repository question. There is no mandatory sequence, required anchor phase, or query-count limit.
+Code conventions are recurring implementation choices in working features that coordinate how those features integrate, such as registration, dependency injection, error handling and test setup. Record the conventions demonstrated by the comparable features, with exact references. Follow them unless a verified defect or a requirement makes them unsuitable; in that case, explain the constraint and plan the coherent change and any consumer migration. Do not create a second implementation merely because a new file is easier to write, or copy an existing defect to match its style.
 
-Before planning, understand the relevant initiating surfaces, behavior owners, decisions, data transformations, effects, consumers, existing reuse opportunities, and structural constraints. Use one discriminating locator and reuse its results as graph roots; do not repeat generic synonym searches after usable candidates exist. When several implementations match, compare their entry surfaces, incoming execution, ownership, callers, or runtime connections before selecting one. Locator results are graph roots, not relevance rankings. Read coverage and recovery before making complete-set or absence claims. Use native tools only for edits, checks, binary content, or a specific unsupported gap reported by scip-query.
+Before deciding that no reusable implementation exists, resolve relevant search and graph coverage gaps and examine the nearest related owners and features. Record the searched scope and remaining uncertainty. Missing, bounded or unsupported evidence does not establish absence. If an unresolved fact could change placement or reuse, keep that design decision unresolved and continue independent work; do not fill the gap with a speculative parallel implementation.
 
-Do not write a plan for one obvious local edit. Write one when correctness depends on several owners or files, downstream consumers, a migration or retirement, reuse of existing behavior, architecture rules, or several coherent implementation slices. Put it in `docs/plans/YYYY-MM-DD-<name>.md` only when it must survive a context reset.
+Use `$scip-architecture-review` for design assessment and `$scip-integrity-audit` when multiple paths, advertised behavior or an apparent replacement may conceal an incomplete implementation.
 
-## Plan shape
+## Record the evidence in the plan
 
-State the observable outcome in one or two sentences. Explain the current behavior with exact symbol and file/line references. Then use this table:
+Before the proposed implementation steps, include these sections in every substantial plan:
 
-| Step | Code reference | Change | Preserve or retire | Verify |
-| --- | --- | --- | --- | --- |
-| Coherent implementation slice | Exact symbol and file/line | Concrete edit and why it belongs here | Existing behavior to keep or residue to remove | Check that fails when the outcome is absent |
+- **Existing flow:** an ordered account or compact diagram from the initiating surface through the current owners and effects to observable completion, with exact symbol or file/line references. Include the relevant alternative outcomes and recovery behavior. Name the component that owns each rule and resource and any lifetime or sharing scope that affects the change.
+- **Comparable features and conventions:** the working examples inspected, the shared path they use, their relevant contracts, and the conventions the change should follow. Separate observed facts from proposed choices. When no analogue was found, record the actual search scope and limits instead of asserting that none exists throughout the codebase.
+- **Reuse and ownership decisions:** the existing symbols or modules to call, extend or adapt, where the new behavior enters the established flow, and the consumers affected. For a proposed new owner or parallel path, state why extending the existing owner cannot meet the requirement and how responsibility stays clear. A deliberate replacement must name the consumers to migrate and the old path to retire.
 
-Order the rows so each leaves the repository in a valid state. Include the relevant entry point, behavior owner, downstream consumers, reuse candidates, architecture constraints, migration or cleanup, and validation. Label design choices as choices. Include an open-uncertainty section only when an unresolved repository fact can change the implementation, and name the exact scip-query command that would answer it.
+Another agent must be able to identify the existing central path and implement the extension from this record. Statements such as “follow existing patterns,” “reuse the service,” or “the system was explored” are insufficient without the actual path, references and decisions. Resolve contradictions between the proposed design and the observed implementation before marking the plan ready for dependent implementation. Planning does not add a user approval requirement.
 
-The plan is ready when another agent can implement it without a broad repository rediscovery pass.
+## Write executable steps
+
+| Step                             | Code reference                     | Change                    | Preserve or retire                                  | Verify                                           |
+| -------------------------------- | ---------------------------------- | ------------------------- | --------------------------------------------------- | ------------------------------------------------ |
+| One coherent implementation step | Exact owner and relevant consumers | Concrete edit and purpose | Behavior, interfaces, state, or obsolete mechanisms | Check detecting the missing or incorrect outcome |
+
+Order steps so earlier changes enable later ones and intermediate states are valid or have an explicit migration/rollback strategy. Give each rule/resource an identified owner. Name consumers that must migrate and legacy entry points, fallbacks, registrations, copies, and documentation to retire.
+
+Preserve authorization, errors, bounds, defaults, operation/record identity, lock scope, order, retries, interruption, and cleanup where applicable. Do not hide unresolved decisions behind “wire it up,” “use the parser,” or “add tests.”
+
+Validation must exercise promised behavior through a real consumer. Include a check that would fail if the new feature bypassed the shared registration, policy, state-management or persistence path it is meant to extend. Verify the relevant decisions and observable effects; a test of an isolated new helper or a mock replacing the shared path does not establish integration. Record independent expected outputs/failures when they distinguish a real fix from a shortcut. For a parser migration, include syntax that defeats the old method and evidence that the live consumer uses the replacement. Do not require arbitrary counts of tests, examples, alternatives, or unrelated performance targets.
+
+## Execute and update
+
+Continue already-authorized implementation; planning does not create another approval gate. Before dependent edits, use the recorded existing flow and reuse decisions. If implementation reveals a missed owner, convention or existing feature, update the plan and affected steps before proceeding with a conflicting design. Update completed work and verified facts. Record material findings as fixed, retained with reason, or unresolved with missing evidence. Retire superseded steps so later agents do not repeat them.
+
+Run focused behavioral tests and required repository checks. Run `scip-query review --base <commit>`, fresh `diff-impact`, and architecture checks when dependencies changed. Investigate findings without changing thresholds or policy to conceal them. Repeat checks after relevant changes, not the entire suite after every small step.
+
+During diff review, compare the implemented entry-to-result flow with the plan. Confirm that the real consumer reaches the intended shared owner, existing callers retain their required behavior, and new code has not duplicated registration, policy checks, data access or state ownership elsewhere. For a replacement, verify the named consumers migrated and the obsolete path was retired. Clean complexity metrics alone do not establish reuse or correct integration.
+
+Report outcomes, actual validation, remaining limits, and migration status. Checking off implementation steps does not establish that the promised outcome works.

package/skills/scip-plan/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: 'SCIP Plan'
-  short_description: 'Write concise repository-grounded implementation plans'
-  default_prompt: 'Use $scip-plan to explore the relevant system with scip-query and write a concise implementation plan grounded in exact symbol and file/line references.'
+  short_description: 'Map existing flows and plan around shared owners.'
+  default_prompt: 'Use $scip-plan to map the existing system end to end, inspect comparable features and conventions, and document the shared path, exact code to reuse or extend, and integration checks before proposing implementation steps.'