scip-query 0.10.3 → 0.10.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +9 -8
- package/dist/{chunk-YVLHL6KQ.js → chunk-237YUOPK.js} +2 -2
- package/dist/chunk-56UN3DMK.js +2 -0
- package/dist/chunk-5UDFZC4D.js +2 -0
- package/dist/{chunk-X474LKJX.js → chunk-6UFMPECA.js} +2 -2
- package/dist/chunk-7JOTOWZO.js +4 -0
- package/dist/chunk-A7RNHUJH.js +20 -0
- package/dist/chunk-AYYIZ4BA.js +4 -0
- package/dist/chunk-BNKE4TT5.js +2 -0
- package/dist/chunk-MA7OVFHI.js +2 -0
- package/dist/chunk-QUJBXLBY.js +2 -0
- package/dist/chunk-WBJZNPUT.js +2 -0
- package/dist/{chunk-4HOMAEDD.js → chunk-YUTRW57I.js} +2 -2
- package/dist/cli.js +209 -197
- package/dist/frontend-behavior-evidence-BxKpKWUu.d.ts +4 -0
- package/dist/postinstall.js +3 -3
- package/dist/queries/diff-gate.d.ts +4 -2
- package/dist/queries/diff-gate.js +1 -1
- package/dist/queries/diff-impact.js +1 -1
- package/dist/queries/doc-drift.js +1 -1
- package/dist/queries/health.js +1 -1
- package/dist/queries/incomplete-migration.js +1 -1
- package/dist/queries/index.d.ts +1 -0
- package/dist/queries/index.js +1 -1
- package/dist/queries/plan-context.js +1 -1
- package/dist/queries/react-component-duplicates.js +1 -1
- package/dist/queries/react-hook-candidates.d.ts +3 -2
- package/dist/queries/react-hook-candidates.js +1 -1
- package/dist/queries/recent-duplicates.js +1 -1
- package/dist/queries/vue-component-duplicates.js +1 -1
- package/dist/queries/vue-composable-candidates.d.ts +3 -2
- package/dist/queries/vue-composable-candidates.js +1 -1
- package/dist/runtime.js +1 -1
- package/docs/AGENT_GUIDE.md +42 -5
- package/docs/AI_FAILURE_MODES.md +28 -21
- package/docs/COMMAND_REFERENCE.md +4 -2
- package/docs/analyzer-inventory.md +5 -1
- package/docs/analyzer-validation-ledger.md +8 -0
- package/package.json +3 -2
- package/skills/concrete-plan/SKILL.md +3 -5
- package/skills/concrete-plan/agents/openai.yaml +4 -0
- package/skills/scip-adoption/SKILL.md +120 -0
- package/skills/scip-adoption/agents/openai.yaml +4 -0
- package/skills/scip-ai-cleanup/SKILL.md +12 -4
- package/skills/scip-ai-cleanup/agents/openai.yaml +4 -0
- package/skills/scip-api-impact/SKILL.md +147 -0
- package/skills/scip-api-impact/agents/openai.yaml +4 -0
- package/skills/scip-debloat/SKILL.md +15 -13
- package/skills/scip-debloat/agents/openai.yaml +4 -0
- package/skills/scip-debug/SKILL.md +119 -0
- package/skills/scip-debug/agents/openai.yaml +4 -0
- package/skills/scip-diagram/SKILL.md +138 -0
- package/skills/scip-diagram/agents/openai.yaml +4 -0
- package/skills/scip-directory-architecture/SKILL.md +2 -2
- package/skills/scip-directory-architecture/agents/openai.yaml +4 -0
- package/skills/scip-doc-reconcile/SKILL.md +1 -3
- package/skills/scip-doc-reconcile/agents/openai.yaml +4 -0
- package/skills/scip-explore/SKILL.md +8 -2
- package/skills/scip-explore/agents/openai.yaml +4 -0
- package/skills/scip-health-audit/SKILL.md +158 -0
- package/skills/scip-health-audit/agents/openai.yaml +4 -0
- package/skills/scip-health-improve/SKILL.md +151 -0
- package/skills/scip-health-improve/agents/openai.yaml +4 -0
- package/skills/scip-language-playbook/SKILL.md +7 -4
- package/skills/scip-language-playbook/agents/openai.yaml +4 -0
- package/skills/scip-maintainability/SKILL.md +7 -3
- package/skills/scip-maintainability/agents/openai.yaml +4 -0
- package/skills/scip-query/SKILL.md +74 -33
- package/skills/scip-query/agents/openai.yaml +4 -0
- package/skills/scip-query-setup/SKILL.md +65 -18
- package/skills/scip-query-setup/agents/openai.yaml +3 -0
- package/skills/scip-react-maintainability/SKILL.md +2 -2
- package/skills/scip-react-maintainability/agents/openai.yaml +4 -0
- package/skills/scip-triage-issue/SKILL.md +112 -0
- package/skills/scip-triage-issue/agents/openai.yaml +4 -0
- package/skills/scip-verify/SKILL.md +83 -232
- package/skills/scip-verify/agents/openai.yaml +4 -0
- package/skills/scip-vue-maintainability/SKILL.md +2 -3
- package/skills/scip-vue-maintainability/agents/openai.yaml +4 -0
- package/dist/chunk-7ADUXFRZ.js +0 -2
- package/dist/chunk-GLJAAKDW.js +0 -4
- package/dist/chunk-GS33KGAY.js +0 -2
- package/dist/chunk-I7TSQZ3J.js +0 -4
- package/dist/chunk-NP5HYVLX.js +0 -20
- package/dist/chunk-O4L4AB3T.js +0 -2
- package/dist/chunk-TO54DY4O.js +0 -2
- package/dist/chunk-UMNENNTX.js +0 -2
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: scip-adoption
|
|
3
|
+
description: Adopt scip-query in a repository from first run through verified local readiness. Use when the user wants to install, bootstrap, onboard, set up, refresh, or roll out scip-query in a project, including skills, indexers, local capabilities, health dossier, and post-setup cleanup handoff.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# SCIP Adoption
|
|
7
|
+
|
|
8
|
+
Use this skill when a repository needs to become a reliable scip-query workspace. A scip-query workspace is a source repository with a current SCIP index, runnable language indexers, installed agent skills, project guidance, and health evidence that agents can use before editing.
|
|
9
|
+
|
|
10
|
+
## Rules
|
|
11
|
+
|
|
12
|
+
1. Make local setup reliable before recommending cleanup.
|
|
13
|
+
2. Do not run `scip-query setup-ci` in the default adoption path. CI is a separate explicit workflow.
|
|
14
|
+
3. Treat missing capabilities as unavailable evidence, not as clean results.
|
|
15
|
+
4. After setup, tell the user the health score and confirmed issue list before application-code cleanup begins.
|
|
16
|
+
|
|
17
|
+
## Adoption Workflow
|
|
18
|
+
|
|
19
|
+
### 1. Establish the project
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
pwd
|
|
23
|
+
git rev-parse --show-toplevel
|
|
24
|
+
scip-query --version
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
If `scip-query` is not available, install or link the package through the repo's package manager, then rerun the checks.
|
|
28
|
+
|
|
29
|
+
### 2. Install skills and run setup
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
scip-query install-skills
|
|
33
|
+
scip-query setup-hooks --json
|
|
34
|
+
scip-query setup --json
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
Use `scip-query setup --git-hook --json` only when the user wants the local Git pre-commit diff-gate hook. Do not treat that hook as a replacement for final verification.
|
|
38
|
+
Use `scip-query setup-hooks --json` when hook config needs to be repaired for the current repository without rerunning the full setup pass.
|
|
39
|
+
|
|
40
|
+
### 3. Resolve blockers
|
|
41
|
+
|
|
42
|
+
If setup reports `blocked` or `partial`, inspect dependencies and capabilities:
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
scip-query check-deps
|
|
46
|
+
scip-query doctor
|
|
47
|
+
scip-query capability-matrix --json
|
|
48
|
+
scip-query status --capabilities
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
Fix missing indexers, toolchain dependencies, invalid config, or stale indexes. If a toolchain cannot be installed safely, record exact manual commands and keep the adoption state blocked.
|
|
52
|
+
|
|
53
|
+
### 4. Initialize or validate config
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
scip-query init
|
|
57
|
+
scip-query config-validate
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
Run `init` only when `.scipquery.json` is absent and the project needs config. Keep config minimal and evidence-backed. Use suppressions only for accepted findings with specific reasons:
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
scip-query suppress <id> --reason "<specific reason>"
|
|
64
|
+
scip-query config-validate
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
### 5. Prove ongoing local usefulness
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
scip-query reindex
|
|
71
|
+
scip-query stats
|
|
72
|
+
scip-query files <known-source-term>
|
|
73
|
+
scip-query outline <known-source-file>
|
|
74
|
+
scip-query health --json --full
|
|
75
|
+
scip-query diff-gate --json
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
Use `scip-query watch` only for an active local work session where automatic reindexing is useful. Do not leave it running as a hidden setup side effect.
|
|
79
|
+
|
|
80
|
+
### 6. Hand off to health audit
|
|
81
|
+
|
|
82
|
+
Invoke `scip-health-audit` after setup if the user wants cleanup or a perfect-code pass. The first user-facing message after the audit must include:
|
|
83
|
+
|
|
84
|
+
- health score;
|
|
85
|
+
- confirmed items that need attention;
|
|
86
|
+
- unconfirmed signals;
|
|
87
|
+
- unavailable or blocked checks;
|
|
88
|
+
- recommended first cleanup batch.
|
|
89
|
+
|
|
90
|
+
Then start cleanup only if the current request already asks for cleanup or the user approves the batch.
|
|
91
|
+
|
|
92
|
+
## Adoption Report
|
|
93
|
+
|
|
94
|
+
End with:
|
|
95
|
+
|
|
96
|
+
```markdown
|
|
97
|
+
Adoption: ready/partial/blocked
|
|
98
|
+
|
|
99
|
+
Installed:
|
|
100
|
+
- skills, hooks, indexers, config files, guidance files
|
|
101
|
+
|
|
102
|
+
Capabilities:
|
|
103
|
+
- available checks
|
|
104
|
+
- unavailable checks and why
|
|
105
|
+
|
|
106
|
+
Health:
|
|
107
|
+
- score
|
|
108
|
+
- dossier path
|
|
109
|
+
- confirmed cleanup queue or audit handoff
|
|
110
|
+
|
|
111
|
+
Verification:
|
|
112
|
+
- `scip-query reindex`
|
|
113
|
+
- `scip-query diff-gate --json`
|
|
114
|
+
- targeted smoke commands
|
|
115
|
+
|
|
116
|
+
Deferred:
|
|
117
|
+
- CI setup, external toolchains, product decisions, or blocked checks
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
Do not claim adoption is ready until the index is current, core commands smoke-test, and `scip-query diff-gate --json` passes.
|
|
@@ -1,8 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: scip-ai-cleanup
|
|
3
3
|
description: Clean up AI-generated code rot using scip-query's change-graph and verification tooling. Finds recent re-implementations of established code, drifting standards docs, speculative parameters, hidden coupling, and produces compiler-verified deletion plans. Sets up the CI ratchet so findings never regress.
|
|
4
|
-
allowed-tools: [Bash, Write, Edit, Glob, Agent, TaskCreate, TaskUpdate, TaskGet, TaskList]
|
|
5
|
-
keywords: [ai-slop, ai-generated, cleanup, duplicates, echo, doc-drift, standards, stale-docs, cleanup-plan, verify, co-change, ratchet, baseline, unused-params]
|
|
6
4
|
---
|
|
7
5
|
|
|
8
6
|
# AI-Generated Code Cleanup with scip-query
|
|
@@ -92,7 +90,7 @@ or add a contract test that fails when one side changes without the other.
|
|
|
92
90
|
### Step 5: Compiler-verified deletion
|
|
93
91
|
|
|
94
92
|
```bash
|
|
95
|
-
scip-query cleanup-plan --verify
|
|
93
|
+
scip-query cleanup-plan --verify --json
|
|
96
94
|
```
|
|
97
95
|
|
|
98
96
|
- Batches are ordered: batch 0 is graph-fact dead now; batch n is dead once
|
|
@@ -105,12 +103,22 @@ scip-query cleanup-plan --verify
|
|
|
105
103
|
- The `blocked` list explains why candidates can't cascade (e.g. a spec file
|
|
106
104
|
still references them).
|
|
107
105
|
|
|
106
|
+
Apply only compiler-verified batches:
|
|
107
|
+
|
|
108
|
+
```bash
|
|
109
|
+
scip-query cleanup-apply --verified --batch 0
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
Use `--all` only after explicit human approval. Use `--force-dirty` only when
|
|
113
|
+
you have inspected the touched files and know the existing edits are unrelated
|
|
114
|
+
to the cleanup batch.
|
|
115
|
+
|
|
108
116
|
### Step 6: Ratchet it
|
|
109
117
|
|
|
110
118
|
```bash
|
|
111
119
|
scip-query health --write-baseline # commit .scipquery-baseline.json
|
|
112
120
|
scip-query health --baseline # exit 1 on any NEW finding — wire into CI
|
|
113
|
-
scip-query diff-gate
|
|
121
|
+
scip-query diff-gate --json # per-diff gate: echoes, missing partners, uncited docs
|
|
114
122
|
```
|
|
115
123
|
|
|
116
124
|
`diff-gate` is the leading indicator: run it on every agent commit / PR
|
|
@@ -0,0 +1,147 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: scip-api-impact
|
|
3
|
+
description: Assess and plan public API, module boundary, schema, route, CLI, config, or exported-surface changes with scip-query evidence. Use when the user asks what will break, who consumes an API, how to migrate a boundary, whether a signature change is safe, or how to coordinate docs/tests/generated artifacts.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# SCIP API Impact
|
|
7
|
+
|
|
8
|
+
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, test, or migration changes outside the implementation file.
|
|
9
|
+
|
|
10
|
+
## Rules
|
|
11
|
+
|
|
12
|
+
1. Identify the actual surface before planning the change.
|
|
13
|
+
2. Use scip-query to find direct consumers, reverse dependencies, transitive blast radius, and historical co-change partners.
|
|
14
|
+
3. Treat docs, generated files, tests, and config as part of the API when they describe or enforce the surface.
|
|
15
|
+
4. Prefer backward-compatible migration plans when consumers are broad or external.
|
|
16
|
+
5. Run `scip-verify` after implementation.
|
|
17
|
+
|
|
18
|
+
## Workflow
|
|
19
|
+
|
|
20
|
+
### 1. Identify the surface
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
scip-query status --capabilities
|
|
24
|
+
scip-query reindex
|
|
25
|
+
scip-query surface <module-or-package>
|
|
26
|
+
scip-query outline <file>
|
|
27
|
+
scip-query trace <symbol-or-command>
|
|
28
|
+
scip-query code <symbol-or-command>
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
Use `scip-query hierarchy <symbol> --json` for class members or nested methods so you know whether the real surface is the member, class, module, or package.
|
|
32
|
+
|
|
33
|
+
### 2. Find consumers and ownership
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
scip-query refs <symbol>
|
|
37
|
+
scip-query fan-in <symbol>
|
|
38
|
+
scip-query rdeps <file>
|
|
39
|
+
scip-query affected <symbol> --json
|
|
40
|
+
scip-query change-surface <file> --json --full
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
Record direct consumers separately from transitive consumers. Direct consumers must compile or adapt immediately; transitive consumers define blast radius and regression risk.
|
|
44
|
+
|
|
45
|
+
### 3. Find hidden partners
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
scip-query co-change <file> --json --full
|
|
49
|
+
scip-query doc-drift --json --full
|
|
50
|
+
scip-query similar <symbol> --json --full
|
|
51
|
+
scip-query similar-files <file> --json --full
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
Use co-change for schema/docs/generator/test partners that do not import each other. Use doc drift when docs mention the surface. Use similarity to find sibling APIs that should remain consistent.
|
|
55
|
+
|
|
56
|
+
### 4. Choose the migration shape
|
|
57
|
+
|
|
58
|
+
Pick one:
|
|
59
|
+
|
|
60
|
+
- Compatible extension: add optional behavior without breaking existing callers.
|
|
61
|
+
- Two-step migration: add the new surface, migrate callers, then remove the old surface.
|
|
62
|
+
- Breaking change: update all consumers and docs in one coordinated change.
|
|
63
|
+
- Adapter shim: keep a wrapper only when external consumers or compatibility windows require it.
|
|
64
|
+
|
|
65
|
+
Reject speculative parameters or wrappers by running:
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
scip-query unused-params --json --full
|
|
69
|
+
scip-query wrapper-candidates --json --full
|
|
70
|
+
scip-query passthrough-candidates --json --full
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
### 5. Build the impact plan
|
|
74
|
+
|
|
75
|
+
Before editing, write:
|
|
76
|
+
|
|
77
|
+
```markdown
|
|
78
|
+
Surface:
|
|
79
|
+
- <symbol/file/command/schema>
|
|
80
|
+
|
|
81
|
+
Consumers:
|
|
82
|
+
- direct: <count and important files>
|
|
83
|
+
- transitive: <count or affected clusters>
|
|
84
|
+
|
|
85
|
+
Required co-changes:
|
|
86
|
+
- code
|
|
87
|
+
- tests
|
|
88
|
+
- docs
|
|
89
|
+
- generated files
|
|
90
|
+
- config or schema partners
|
|
91
|
+
|
|
92
|
+
Migration:
|
|
93
|
+
- compatible extension / two-step / breaking / shim
|
|
94
|
+
|
|
95
|
+
Verification:
|
|
96
|
+
- targeted tests
|
|
97
|
+
- `scip-query diff-impact --json`
|
|
98
|
+
- `scip-query diff-gate --json`
|
|
99
|
+
- `scip-query doc-drift --json --full` when docs changed
|
|
100
|
+
- `scip-query config-validate` when config changed
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
### 6. Verify after editing
|
|
104
|
+
|
|
105
|
+
```bash
|
|
106
|
+
scip-query reindex
|
|
107
|
+
scip-query diff-impact --json
|
|
108
|
+
scip-query diff-gate --json
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
Then run routed checks:
|
|
112
|
+
|
|
113
|
+
```bash
|
|
114
|
+
scip-query unused-params --json --full
|
|
115
|
+
scip-query incomplete-migration --json --full
|
|
116
|
+
scip-query co-change <changed-file> --json --full
|
|
117
|
+
scip-query doc-drift --json --full
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
Invoke `scip-verify` before declaring the API change ready.
|
|
121
|
+
|
|
122
|
+
## Report Format
|
|
123
|
+
|
|
124
|
+
```markdown
|
|
125
|
+
API impact: low/medium/high
|
|
126
|
+
|
|
127
|
+
Surface changed:
|
|
128
|
+
- <surface>
|
|
129
|
+
|
|
130
|
+
Consumers:
|
|
131
|
+
- <direct consumers>
|
|
132
|
+
- <transitive blast radius>
|
|
133
|
+
|
|
134
|
+
Migration plan:
|
|
135
|
+
- <chosen shape and why>
|
|
136
|
+
|
|
137
|
+
Co-changes:
|
|
138
|
+
- <docs/tests/generated/config partners>
|
|
139
|
+
|
|
140
|
+
Verification:
|
|
141
|
+
- <commands run and results>
|
|
142
|
+
|
|
143
|
+
Remaining risk:
|
|
144
|
+
- <external consumers, unavailable capabilities, or accepted compatibility shims>
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
Do not call a public-surface change safe until direct consumers, docs/config partners, and `scip-query diff-gate --json` have been checked.
|
|
@@ -1,8 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: scip-debloat
|
|
3
|
-
description: Comprehensive codebase de-bloating using scip-query. Finds dead code, duplication, unnecessary abstractions,
|
|
4
|
-
allowed-tools: [Bash, Write, Edit, Glob, Agent, TaskCreate, TaskUpdate, TaskGet, TaskList]
|
|
5
|
-
keywords: [debloat, clean, cleanup, refactor, dead-code, duplication, dry, consolidate, simplify, reduce, bloat, unused, stale, drift, health]
|
|
3
|
+
description: Comprehensive codebase de-bloating using scip-query. Use when the user asks to clean up a codebase, find dead code, delete bloat, remove duplication, consolidate variants, shrink a module, or audit structural waste. Finds dead code, duplication, unnecessary abstractions, pattern drift, and consolidation opportunities, then produces a prioritized action list. Use scip-health-improve instead when the user wants an autonomous health-score campaign.
|
|
6
4
|
---
|
|
7
5
|
|
|
8
6
|
# Codebase De-Bloating with scip-query
|
|
@@ -13,16 +11,11 @@ This is not a score-maxing workflow. Health scores, finding counts, and LOC tota
|
|
|
13
11
|
|
|
14
12
|
---
|
|
15
13
|
|
|
16
|
-
##
|
|
14
|
+
## Scope Boundary
|
|
17
15
|
|
|
18
|
-
-
|
|
19
|
-
-
|
|
20
|
-
|
|
21
|
-
- "Find duplication"
|
|
22
|
-
- "Make this codebase smaller"
|
|
23
|
-
- "Are there things we can consolidate?"
|
|
24
|
-
- "Run a health check"
|
|
25
|
-
- "De-bloat this module"
|
|
16
|
+
Use `scip-debloat` for bloat-specific discovery and action planning. Use
|
|
17
|
+
`scip-health-improve` when the user wants the agent to keep applying confirmed
|
|
18
|
+
fixes until the health score is as high as reasonably possible.
|
|
26
19
|
|
|
27
20
|
---
|
|
28
21
|
|
|
@@ -49,7 +42,7 @@ This is not a score-maxing workflow. Health scores, finding counts, and LOC tota
|
|
|
49
42
|
Before working the angles below one by one, run the high-leverage trio:
|
|
50
43
|
|
|
51
44
|
```bash
|
|
52
|
-
scip-query cleanup-plan --verify
|
|
45
|
+
scip-query cleanup-plan --verify --json # cascade dead-code plan, COMPILER-VERIFIED per batch
|
|
53
46
|
scip-query recent-duplicates # recent code that re-implements established code
|
|
54
47
|
scip-query doc-drift # docs whose referenced code moved on without them
|
|
55
48
|
```
|
|
@@ -61,6 +54,15 @@ check) differentially. Only act on batches stamped COMPILER-VERIFIED; FAILED
|
|
|
61
54
|
output names the references the static evidence missed. For AI-generated
|
|
62
55
|
codebases specifically, prefer the dedicated scip-ai-cleanup skill.
|
|
63
56
|
|
|
57
|
+
Apply one verified batch at a time:
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
scip-query cleanup-apply --verified --batch 0
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
Use `--all` only after explicit human approval. Use `--force-dirty` only after
|
|
64
|
+
inspecting the touched files and confirming existing edits are unrelated.
|
|
65
|
+
|
|
64
66
|
After cleanup, ratchet the result so it never regresses:
|
|
65
67
|
|
|
66
68
|
```bash
|
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: scip-debug
|
|
3
|
+
description: Root-cause bugs and regressions with scip-query evidence. Use when the user reports a bug, failing behavior, regression, confusing runtime path, broken data flow, or asks to debug, diagnose, reproduce, trace, or explain why code behaves incorrectly before fixing it.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# SCIP Debug
|
|
7
|
+
|
|
8
|
+
Use this skill to move from a reported failure to a minimal verified fix. A bug is a mismatch between expected behavior and observed behavior in a concrete execution path. A root cause is the earliest code fact in that path that explains the mismatch and makes the later symptoms possible.
|
|
9
|
+
|
|
10
|
+
## Rules
|
|
11
|
+
|
|
12
|
+
1. Reproduce or restate the failure before changing code.
|
|
13
|
+
2. Use scip-query to identify entry points, call paths, data flow, and blast radius. Do not debug from filename guesses alone.
|
|
14
|
+
3. Prefer one narrow fix over broad cleanup. If cleanup is also needed, record it after the bug fix unless it is required for correctness.
|
|
15
|
+
4. Verify the fix with the repo's test or smoke command, then run `scip-verify`.
|
|
16
|
+
|
|
17
|
+
## Workflow
|
|
18
|
+
|
|
19
|
+
### 1. Pin the failure
|
|
20
|
+
|
|
21
|
+
Record:
|
|
22
|
+
|
|
23
|
+
- observed behavior;
|
|
24
|
+
- expected behavior;
|
|
25
|
+
- command, route, UI action, test, job, or file that exposes it;
|
|
26
|
+
- error text or wrong output;
|
|
27
|
+
- suspected time window if it is a regression.
|
|
28
|
+
|
|
29
|
+
If the user provides no reproduction, make the smallest runnable reproduction you can from the repo's existing tests, scripts, CLI, or app entry points.
|
|
30
|
+
|
|
31
|
+
### 2. Find the entry point
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
scip-query status --capabilities
|
|
35
|
+
scip-query reindex
|
|
36
|
+
scip-query files <feature-or-error-term>
|
|
37
|
+
scip-query outline <candidate-file>
|
|
38
|
+
scip-query trace <candidate-symbol>
|
|
39
|
+
scip-query code <candidate-symbol>
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
Use `scip-query by-kind function --scope <scope>` or `scip-query kind-counts --scope <scope>` when the codebase is unfamiliar and you need an inventory before selecting an entry point.
|
|
43
|
+
|
|
44
|
+
### 3. Follow execution
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
scip-query call-graph <entry-symbol>
|
|
48
|
+
scip-query code <callee-symbol>
|
|
49
|
+
scip-query refs <state-or-api-symbol>
|
|
50
|
+
scip-query fan-in <suspect-symbol>
|
|
51
|
+
scip-query fan-out <suspect-file>
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
Build the smallest path that explains the observed behavior. Stop expanding once the path reaches the first code fact that can cause the symptom.
|
|
55
|
+
|
|
56
|
+
### 4. Follow data and state
|
|
57
|
+
|
|
58
|
+
```bash
|
|
59
|
+
scip-query dataflow <symbol-or-variable>
|
|
60
|
+
scip-query slice <symbol-or-variable>
|
|
61
|
+
scip-query slice <symbol-or-variable> --forward
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
Use dataflow when the bug looks like wrong state, wrong input normalization, missing validation, stale cache, dropped field, wrong async order, or an unexpected output value.
|
|
65
|
+
|
|
66
|
+
### 5. Compare nearby implementations
|
|
67
|
+
|
|
68
|
+
```bash
|
|
69
|
+
scip-query similar <suspect-symbol> --json --full
|
|
70
|
+
scip-query convergence <suspect-symbol> <similar-symbol>
|
|
71
|
+
scip-query similar-files <suspect-file> --json --full
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
A similar implementation can reveal the missing branch, guard, conversion, lifecycle step, or error handling path. Preserve essential differences; do not copy behavior blindly.
|
|
75
|
+
|
|
76
|
+
### 6. Bound the fix
|
|
77
|
+
|
|
78
|
+
```bash
|
|
79
|
+
scip-query change-surface <suspect-file> --json --full
|
|
80
|
+
scip-query affected <suspect-symbol> --json
|
|
81
|
+
scip-query diff-impact --json
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
Name the smallest symbol or file that should change. If the blast radius is larger than the bug's scope, explain why before editing.
|
|
85
|
+
|
|
86
|
+
### 7. Fix and verify
|
|
87
|
+
|
|
88
|
+
Apply the minimal code change, then run:
|
|
89
|
+
|
|
90
|
+
```bash
|
|
91
|
+
scip-query reindex
|
|
92
|
+
scip-query diff-gate --json
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
Also run the narrowest repo test, app smoke test, or command that reproduces the failure. Invoke `scip-verify` before calling the bug fixed.
|
|
96
|
+
|
|
97
|
+
## Report Format
|
|
98
|
+
|
|
99
|
+
```markdown
|
|
100
|
+
Bug: <observed mismatch>
|
|
101
|
+
|
|
102
|
+
Entry point:
|
|
103
|
+
- <file/symbol> from <command>
|
|
104
|
+
|
|
105
|
+
Root cause:
|
|
106
|
+
- <code fact> from <command>
|
|
107
|
+
|
|
108
|
+
Fix:
|
|
109
|
+
- <minimal change>
|
|
110
|
+
|
|
111
|
+
Verification:
|
|
112
|
+
- <repo test or smoke command>
|
|
113
|
+
- `scip-query diff-gate --json`
|
|
114
|
+
|
|
115
|
+
Remaining risk:
|
|
116
|
+
- <blast radius, unavailable capability, or follow-up cleanup>
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
If no root cause is proven, say what evidence is missing and what command or reproduction would unblock it. Do not present a guess as a fix.
|
|
@@ -0,0 +1,138 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: scip-diagram
|
|
3
|
+
description: Create evidence-backed HTML diagrams of how code works using scip-query. Use when the user asks for a code flow diagram, architecture diagram, data-flow diagram, dependency map, blast-radius visualization, module map, or an HTML artifact that explains a system.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# SCIP Diagram
|
|
7
|
+
|
|
8
|
+
Use this skill to build a visual explanation from compiler-resolved code facts. A code diagram is an HTML artifact that turns source units, calls, dependencies, data flow, or blast radius into a visual map. Its defining trait is that every node and edge comes from scip-query evidence, not from guessed folder structure.
|
|
9
|
+
|
|
10
|
+
## Rules
|
|
11
|
+
|
|
12
|
+
1. Run scip-query evidence first, then draw. Do not invent nodes or arrows.
|
|
13
|
+
2. Make a self-contained HTML file unless the user asks for another format.
|
|
14
|
+
3. Include command provenance in the HTML so readers can see which scip-query commands produced the diagram.
|
|
15
|
+
4. Keep diagrams scoped. If the graph is huge, summarize clusters and link to detailed evidence rather than rendering a hairball.
|
|
16
|
+
5. Verify the HTML opens cleanly and contains the expected diagram content.
|
|
17
|
+
|
|
18
|
+
## Pick the Diagram Type
|
|
19
|
+
|
|
20
|
+
| User wants | Use |
|
|
21
|
+
|---|---|
|
|
22
|
+
| "How does this feature work?" | Call-flow diagram |
|
|
23
|
+
| "Where does this value come from?" | Data-flow diagram |
|
|
24
|
+
| "What depends on this?" | Blast-radius diagram |
|
|
25
|
+
| "What is this module's architecture?" | Module/dependency diagram |
|
|
26
|
+
| "Why is this hard to change?" | Change-surface or bottleneck diagram |
|
|
27
|
+
| "Show classes or ownership" | Hierarchy and surface diagram |
|
|
28
|
+
|
|
29
|
+
## Evidence Commands
|
|
30
|
+
|
|
31
|
+
Start with current graph facts:
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
scip-query status --capabilities
|
|
35
|
+
scip-query reindex
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
Collect only the commands needed for the diagram:
|
|
39
|
+
|
|
40
|
+
```bash
|
|
41
|
+
scip-query system <module>
|
|
42
|
+
scip-query surface <module>
|
|
43
|
+
scip-query outline <file>
|
|
44
|
+
scip-query trace <symbol>
|
|
45
|
+
scip-query code <symbol>
|
|
46
|
+
scip-query call-graph <symbol>
|
|
47
|
+
scip-query dataflow <symbol>
|
|
48
|
+
scip-query slice <symbol>
|
|
49
|
+
scip-query slice <symbol> --forward
|
|
50
|
+
scip-query deps <file>
|
|
51
|
+
scip-query rdeps <file>
|
|
52
|
+
scip-query affected <symbol> --json
|
|
53
|
+
scip-query change-surface <file> --json --full
|
|
54
|
+
scip-query hierarchy <symbol> --json
|
|
55
|
+
scip-query fan-out <file> --json
|
|
56
|
+
scip-query bottlenecks
|
|
57
|
+
scip-query cycles
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
Use `scip-query kind-counts --scope <scope>` and `scip-query by-kind <kind> --scope <scope>` when the diagram needs an inventory of symbols.
|
|
61
|
+
|
|
62
|
+
## Build the HTML
|
|
63
|
+
|
|
64
|
+
Write the artifact under:
|
|
65
|
+
|
|
66
|
+
```text
|
|
67
|
+
docs/scip-query/diagrams/YYYY-MM-DD-<scope>.html
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
If the repo has a different reports convention, follow it. The file should include:
|
|
71
|
+
|
|
72
|
+
- title and scope;
|
|
73
|
+
- short textual summary;
|
|
74
|
+
- the visual diagram;
|
|
75
|
+
- legend for node colors, edge styles, and risk labels;
|
|
76
|
+
- evidence table listing every scip-query command used;
|
|
77
|
+
- notes for omitted nodes, collapsed clusters, or unavailable capabilities.
|
|
78
|
+
|
|
79
|
+
Implementation guidance:
|
|
80
|
+
|
|
81
|
+
- Use inline CSS and either semantic HTML layout or inline SVG.
|
|
82
|
+
- Use stable dimensions and labels that wrap cleanly.
|
|
83
|
+
- Use one visual encoding per meaning: call edges, data edges, dependency edges, and risk edges should look different.
|
|
84
|
+
- Keep colors accessible and avoid relying on color alone; include labels or edge styles.
|
|
85
|
+
- For large graphs, group by module, ownership, lifecycle phase, or public surface.
|
|
86
|
+
|
|
87
|
+
## Diagram Recipes
|
|
88
|
+
|
|
89
|
+
### Call Flow
|
|
90
|
+
|
|
91
|
+
```bash
|
|
92
|
+
scip-query trace <entry-symbol>
|
|
93
|
+
scip-query call-graph <entry-symbol>
|
|
94
|
+
scip-query code <entry-symbol>
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
Render entry point -> major callees -> side effects or terminal outputs. Label each edge with the call or branch reason when `code` proves it.
|
|
98
|
+
|
|
99
|
+
### Data Flow
|
|
100
|
+
|
|
101
|
+
```bash
|
|
102
|
+
scip-query dataflow <value-symbol>
|
|
103
|
+
scip-query slice <value-symbol>
|
|
104
|
+
scip-query slice <value-symbol> --forward
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
Render producers, transformations, validators, storage, and consumers. Mark inferred or unavailable parts explicitly.
|
|
108
|
+
|
|
109
|
+
### Dependency or Module Map
|
|
110
|
+
|
|
111
|
+
```bash
|
|
112
|
+
scip-query system <module>
|
|
113
|
+
scip-query deps <file>
|
|
114
|
+
scip-query rdeps <file>
|
|
115
|
+
scip-query surface <module>
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
Render internal files, imported modules, reverse consumers, and public surfaces. Distinguish internal dependencies from external consumers.
|
|
119
|
+
|
|
120
|
+
### Blast Radius
|
|
121
|
+
|
|
122
|
+
```bash
|
|
123
|
+
scip-query affected <symbol> --json
|
|
124
|
+
scip-query change-surface <file> --json --full
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
Render the changed symbol, direct consumers, transitive consumers, and high-risk surfaces. Show depth so the user can see how far the change travels.
|
|
128
|
+
|
|
129
|
+
## Verification
|
|
130
|
+
|
|
131
|
+
After writing the HTML:
|
|
132
|
+
|
|
133
|
+
1. Open it locally or use a browser/screenshot tool when available.
|
|
134
|
+
2. Confirm the diagram is nonblank and labels do not overlap badly.
|
|
135
|
+
3. Confirm every major node and edge is traceable to the evidence table.
|
|
136
|
+
4. Run `scip-query diff-gate --json` if the diagram is part of a code or docs change.
|
|
137
|
+
|
|
138
|
+
End by giving the file path and a short summary of what the diagram proves.
|
|
@@ -24,7 +24,7 @@ A migration slice is the smallest set of file moves and import updates that can
|
|
|
24
24
|
3. Preserve working conventions. Existing boundaries are not wrong just because they are broad; central folders such as `errors`, `routes`, `workflows`, `schemas`, `contracts`, or `features` may be doing real work.
|
|
25
25
|
4. Do not reward generic `shared`. A shared folder is justified only when the shared concept has a name, owner, and consumers across real boundaries.
|
|
26
26
|
5. Treat messy repos honestly. If ownership concepts are not stable, produce a discovery map and decision list instead of pretending the repo has a clean target structure.
|
|
27
|
-
6. Prefer small verified moves. Broad reorganizations need staged migration slices with import updates, tests, `scip-query reindex`, and `scip-query diff-gate`.
|
|
27
|
+
6. Prefer small verified moves. Broad reorganizations need staged migration slices with import updates, tests, `scip-query reindex`, and `scip-query diff-gate --json`.
|
|
28
28
|
|
|
29
29
|
## Workflow
|
|
30
30
|
|
|
@@ -159,7 +159,7 @@ scip-query reindex
|
|
|
159
159
|
scip-query incomplete-migration
|
|
160
160
|
scip-query recent-duplicates
|
|
161
161
|
scip-query co-change <moved-file-or-config>
|
|
162
|
-
scip-query diff-gate
|
|
162
|
+
scip-query diff-gate --json
|
|
163
163
|
```
|
|
164
164
|
|
|
165
165
|
Also run the repo's normal tests or typecheck for the affected workspace. If the migration adds or changes `.scipquery.json` locality settings, run:
|