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.
Files changed (87) hide show
  1. package/README.md +9 -8
  2. package/dist/{chunk-YVLHL6KQ.js → chunk-237YUOPK.js} +2 -2
  3. package/dist/chunk-56UN3DMK.js +2 -0
  4. package/dist/chunk-5UDFZC4D.js +2 -0
  5. package/dist/{chunk-X474LKJX.js → chunk-6UFMPECA.js} +2 -2
  6. package/dist/chunk-7JOTOWZO.js +4 -0
  7. package/dist/chunk-A7RNHUJH.js +20 -0
  8. package/dist/chunk-AYYIZ4BA.js +4 -0
  9. package/dist/chunk-BNKE4TT5.js +2 -0
  10. package/dist/chunk-MA7OVFHI.js +2 -0
  11. package/dist/chunk-QUJBXLBY.js +2 -0
  12. package/dist/chunk-WBJZNPUT.js +2 -0
  13. package/dist/{chunk-4HOMAEDD.js → chunk-YUTRW57I.js} +2 -2
  14. package/dist/cli.js +209 -197
  15. package/dist/frontend-behavior-evidence-BxKpKWUu.d.ts +4 -0
  16. package/dist/postinstall.js +3 -3
  17. package/dist/queries/diff-gate.d.ts +4 -2
  18. package/dist/queries/diff-gate.js +1 -1
  19. package/dist/queries/diff-impact.js +1 -1
  20. package/dist/queries/doc-drift.js +1 -1
  21. package/dist/queries/health.js +1 -1
  22. package/dist/queries/incomplete-migration.js +1 -1
  23. package/dist/queries/index.d.ts +1 -0
  24. package/dist/queries/index.js +1 -1
  25. package/dist/queries/plan-context.js +1 -1
  26. package/dist/queries/react-component-duplicates.js +1 -1
  27. package/dist/queries/react-hook-candidates.d.ts +3 -2
  28. package/dist/queries/react-hook-candidates.js +1 -1
  29. package/dist/queries/recent-duplicates.js +1 -1
  30. package/dist/queries/vue-component-duplicates.js +1 -1
  31. package/dist/queries/vue-composable-candidates.d.ts +3 -2
  32. package/dist/queries/vue-composable-candidates.js +1 -1
  33. package/dist/runtime.js +1 -1
  34. package/docs/AGENT_GUIDE.md +42 -5
  35. package/docs/AI_FAILURE_MODES.md +28 -21
  36. package/docs/COMMAND_REFERENCE.md +4 -2
  37. package/docs/analyzer-inventory.md +5 -1
  38. package/docs/analyzer-validation-ledger.md +8 -0
  39. package/package.json +3 -2
  40. package/skills/concrete-plan/SKILL.md +3 -5
  41. package/skills/concrete-plan/agents/openai.yaml +4 -0
  42. package/skills/scip-adoption/SKILL.md +120 -0
  43. package/skills/scip-adoption/agents/openai.yaml +4 -0
  44. package/skills/scip-ai-cleanup/SKILL.md +12 -4
  45. package/skills/scip-ai-cleanup/agents/openai.yaml +4 -0
  46. package/skills/scip-api-impact/SKILL.md +147 -0
  47. package/skills/scip-api-impact/agents/openai.yaml +4 -0
  48. package/skills/scip-debloat/SKILL.md +15 -13
  49. package/skills/scip-debloat/agents/openai.yaml +4 -0
  50. package/skills/scip-debug/SKILL.md +119 -0
  51. package/skills/scip-debug/agents/openai.yaml +4 -0
  52. package/skills/scip-diagram/SKILL.md +138 -0
  53. package/skills/scip-diagram/agents/openai.yaml +4 -0
  54. package/skills/scip-directory-architecture/SKILL.md +2 -2
  55. package/skills/scip-directory-architecture/agents/openai.yaml +4 -0
  56. package/skills/scip-doc-reconcile/SKILL.md +1 -3
  57. package/skills/scip-doc-reconcile/agents/openai.yaml +4 -0
  58. package/skills/scip-explore/SKILL.md +8 -2
  59. package/skills/scip-explore/agents/openai.yaml +4 -0
  60. package/skills/scip-health-audit/SKILL.md +158 -0
  61. package/skills/scip-health-audit/agents/openai.yaml +4 -0
  62. package/skills/scip-health-improve/SKILL.md +151 -0
  63. package/skills/scip-health-improve/agents/openai.yaml +4 -0
  64. package/skills/scip-language-playbook/SKILL.md +7 -4
  65. package/skills/scip-language-playbook/agents/openai.yaml +4 -0
  66. package/skills/scip-maintainability/SKILL.md +7 -3
  67. package/skills/scip-maintainability/agents/openai.yaml +4 -0
  68. package/skills/scip-query/SKILL.md +74 -33
  69. package/skills/scip-query/agents/openai.yaml +4 -0
  70. package/skills/scip-query-setup/SKILL.md +65 -18
  71. package/skills/scip-query-setup/agents/openai.yaml +3 -0
  72. package/skills/scip-react-maintainability/SKILL.md +2 -2
  73. package/skills/scip-react-maintainability/agents/openai.yaml +4 -0
  74. package/skills/scip-triage-issue/SKILL.md +112 -0
  75. package/skills/scip-triage-issue/agents/openai.yaml +4 -0
  76. package/skills/scip-verify/SKILL.md +83 -232
  77. package/skills/scip-verify/agents/openai.yaml +4 -0
  78. package/skills/scip-vue-maintainability/SKILL.md +2 -3
  79. package/skills/scip-vue-maintainability/agents/openai.yaml +4 -0
  80. package/dist/chunk-7ADUXFRZ.js +0 -2
  81. package/dist/chunk-GLJAAKDW.js +0 -4
  82. package/dist/chunk-GS33KGAY.js +0 -2
  83. package/dist/chunk-I7TSQZ3J.js +0 -4
  84. package/dist/chunk-NP5HYVLX.js +0 -20
  85. package/dist/chunk-O4L4AB3T.js +0 -2
  86. package/dist/chunk-TO54DY4O.js +0 -2
  87. 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.
@@ -0,0 +1,4 @@
1
+ interface:
2
+ display_name: "SCIP Adoption"
3
+ short_description: "Adopt scip-query in a repository"
4
+ default_prompt: "Set up scip-query in this repository, verify local capabilities, write the health dossier, and hand off confirmed cleanup work."
@@ -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 # per-diff gate: echoes, missing partners, uncited docs
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,4 @@
1
+ interface:
2
+ display_name: "SCIP AI Cleanup"
3
+ short_description: "Clean up AI-generated code rot"
4
+ default_prompt: "Use $scip-ai-cleanup to find and fix AI-generated duplication, partial migrations, and stale cleanup fallout."
@@ -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.
@@ -0,0 +1,4 @@
1
+ interface:
2
+ display_name: "SCIP API Impact"
3
+ short_description: "Assess public API and boundary change impact"
4
+ default_prompt: "Assess the impact of this public API or module-boundary change with scip-query evidence and produce a migration-safe plan."
@@ -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, consolidation opportunities, pattern drift, and structural bloat from every possible angle. Produces a prioritized action list.
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
- ## When to Use This Skill
14
+ ## Scope Boundary
17
15
 
18
- - "Clean up this codebase"
19
- - "Find dead code"
20
- - "What can we delete?"
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 # cascade dead-code plan, COMPILER-VERIFIED per batch
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,4 @@
1
+ interface:
2
+ display_name: "SCIP Debloat"
3
+ short_description: "Find and remove structural bloat"
4
+ default_prompt: "Use $scip-debloat to find dead code, duplication, wrappers, stale abstractions, and other structural bloat."
@@ -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,4 @@
1
+ interface:
2
+ display_name: "SCIP Debug"
3
+ short_description: "Root-cause bugs with scip-query evidence"
4
+ default_prompt: "Use scip-query to trace a bug from entry point to root cause, propose a minimal fix, and verify the blast radius."
@@ -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.
@@ -0,0 +1,4 @@
1
+ interface:
2
+ display_name: "SCIP Diagram"
3
+ short_description: "Create HTML code-flow diagrams from scip-query"
4
+ default_prompt: "Generate an HTML diagram that explains this code path using scip-query evidence and command provenance."
@@ -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:
@@ -0,0 +1,4 @@
1
+ interface:
2
+ display_name: "SCIP Directory Architecture"
3
+ short_description: "Review and propose source folder boundaries"
4
+ default_prompt: "Use $scip-directory-architecture to review this repository directory structure and propose safer ownership boundaries."