| name | scip-api-impact |
| description | Assess API impact with scip-query evidence. Use before changing public exports, module boundaries, schemas, routes, CLI commands, config fields, generated artifacts, signatures, docs-backed behavior, or consumer migrations. |
| commands | [{"template":"scip-query surface <module-or-package>","when":"Identify the surface: what consumers actually use from the module."},{"template":"scip-query refs <symbol>","when":"Find consumers: every direct reference to the surface symbol."},{"template":"scip-query affected <symbol> --json","when":"Find consumers: transitive blast radius of the change."},{"template":"scip-query co-change <file> --json --full","when":"Find hidden partners: historically coupled files without a dependency edge."},{"template":"scip-query doc-drift --json --full","when":"Find hidden partners: docs that describe the surface and may need an update."},{"template":"scip-query unused-params --json --full","when":"Choose migration shape: reject speculative new parameters."}] |
scip-api-impact
Use this skill before changing a public surface. A public surface is a callable, export, route, schema, config field, CLI command, generated artifact, or documented behavior that other code or users can depend on. Its defining trait is that a local edit can require coordinated consumer, docs, tests, or migration changes outside the implementation file.
Load shared mechanics from ../_shared/SKILL.md.
Commands for this skill
| Command | Purpose | When |
|---|
scip-query surface <module-or-package> | What symbols consumers actually use from this module | Identify the surface: what consumers actually use from the module. |
scip-query refs <symbol> | Find all files referencing a symbol | Find consumers: every direct reference to the surface symbol. |
scip-query affected <symbol> --json | Transitive closure of symbols that could break if this symbol changes | Find consumers: transitive blast radius of the change. |
scip-query co-change <file> --json --full | Files that change together in git history without a dependency edge — hidden coupling candidates | Find hidden partners: historically coupled files without a dependency edge. |
scip-query doc-drift --json --full | Stale-doc candidates: code the doc references or co-changed with kept changing after the doc stopped | Find hidden partners: docs that describe the surface and may need an update. |
scip-query unused-params --json --full | Speculative-generality candidates: trailing parameters no body ever uses (TS/JS) | Choose migration shape: reject speculative new parameters. |
Use this shortlist first. Open ../_shared/SKILL.md only when it is insufficient.
Rules
- Identify the actual surface before planning.
- Find direct consumers, reverse dependencies, transitive blast radius, and historical co-change partners.
- Treat docs, generated files, tests, and config as part of the API when they describe or enforce the surface.
- Prefer backward-compatible migrations when consumers are broad or external.
- Run
scip-verify after implementation.
Workflow
1. Identify the surface
scip-query surface <module-or-package>
scip-query outline <file>
scip-query trace <symbol-or-command>
scip-query code <symbol-or-command>
scip-query hierarchy <symbol> --json
This step is complete only when the real surface is named: member, class, module, package, route, schema, command, or config field.
2. Find consumers
scip-query refs <symbol>
scip-query fan-in <symbol>
scip-query rdeps <file>
scip-query affected <symbol> --json
scip-query change-surface <file> --json --full
Record direct consumers separately from transitive consumers.
This step is complete only when direct breakage and regression blast radius are known.
3. Find hidden partners
scip-query co-change <file> --json --full
scip-query doc-drift --json --full
scip-query similar <symbol> --json --full
scip-query similar-files <file> --json --full
This step is complete only when docs, generated files, fixtures, sibling APIs, and hand-synchronized partners are accounted for or ruled out.
4. Choose migration shape
Pick one:
- Compatible extension.
- Two-step migration.
- Breaking coordinated change.
- Adapter shim for external consumers or compatibility windows.
Reject speculative inputs and empty wrappers with:
scip-query unused-params --json --full
scip-query wrapper-candidates --json --full
scip-query passthrough-candidates --json --full
This step is complete only when the migration shape explains deploy order, rollback, and compatibility risk.
5. Build and verify the plan
Surface:
Consumer dispositions:
| Consumer | Kind (direct/transitive/doc/config/test) | Disposition (unchanged-safe/update/shim/defer) |
| --- | --- | --- |
Required co-changes:
Migration:
Verification:
- targeted tests
- `scip-query diff-impact --json`
- invoke `scip-verify`
- `scip-query doc-drift --json --full` when docs changed
- `scip-query config-validate` when config changed
Every consumer from refs/affected appears as a row — a blank disposition is unfinished analysis, and the plan is not complete while one exists. Non-indexed consumers (SQL, fixtures, dynamic strings, external callers) are checked with rg and rowed the same way.
After editing, run routed checks from the shared reference and invoke scip-verify.
The work is complete only when direct consumers, docs/config partners, and scip-verify have been checked.
Report
API impact: low/medium/high
Surface changed:
Consumers:
Migration plan:
Co-changes:
Verification:
Remaining risk:
