diff --git a/graphify/skill-agents.md b/graphify/skill-agents.md index 190827d9ac..be74f7476d 100644 --- a/graphify/skill-agents.md +++ b/graphify/skill-agents.md @@ -689,6 +689,18 @@ Before traversal, expand the question against the graph's own vocabulary so a wo --- +## For /graphify affected + +When the user asks for a change's blast radius or "what calls/depends on X?", use `graphify affected "X"` rather than a broad `query`. It reverse-traverses the graph from X and reports the callers and dependents that a change could impact. For relation/depth filters and the exact workflow, see `references/query.md`. + +--- + +## Less-common maintenance commands + +Use these only when the request calls for them: `graphify tree` writes a collapsible hierarchy view; `graphify global add|remove|list|path` manages the cross-repository graph; `graphify check-update ` is the cron-safe stale-graph check; `graphify diagnose multigraph` reports same-endpoint edge-collapse risk; and `graphify merge-driver ` is for a Git merge-driver invocation. Run `graphify --help` before supplying flags, and do not substitute these commands for the normal build/query workflow. + +--- + ## For /graphify add and --watch Neither is part of the default build. When the user runs `/graphify add ` to fetch a URL into the corpus, or passes `--watch` to auto-rebuild on file changes, see `references/add-watch.md`. diff --git a/graphify/skill-amp.md b/graphify/skill-amp.md index 190827d9ac..be74f7476d 100644 --- a/graphify/skill-amp.md +++ b/graphify/skill-amp.md @@ -689,6 +689,18 @@ Before traversal, expand the question against the graph's own vocabulary so a wo --- +## For /graphify affected + +When the user asks for a change's blast radius or "what calls/depends on X?", use `graphify affected "X"` rather than a broad `query`. It reverse-traverses the graph from X and reports the callers and dependents that a change could impact. For relation/depth filters and the exact workflow, see `references/query.md`. + +--- + +## Less-common maintenance commands + +Use these only when the request calls for them: `graphify tree` writes a collapsible hierarchy view; `graphify global add|remove|list|path` manages the cross-repository graph; `graphify check-update ` is the cron-safe stale-graph check; `graphify diagnose multigraph` reports same-endpoint edge-collapse risk; and `graphify merge-driver ` is for a Git merge-driver invocation. Run `graphify --help` before supplying flags, and do not substitute these commands for the normal build/query workflow. + +--- + ## For /graphify add and --watch Neither is part of the default build. When the user runs `/graphify add ` to fetch a URL into the corpus, or passes `--watch` to auto-rebuild on file changes, see `references/add-watch.md`. diff --git a/graphify/skill-claw.md b/graphify/skill-claw.md index abd2811d23..60667e3121 100644 --- a/graphify/skill-claw.md +++ b/graphify/skill-claw.md @@ -692,6 +692,18 @@ Before traversal, expand the question against the graph's own vocabulary so a wo --- +## For /graphify affected + +When the user asks for a change's blast radius or "what calls/depends on X?", use `graphify affected "X"` rather than a broad `query`. It reverse-traverses the graph from X and reports the callers and dependents that a change could impact. For relation/depth filters and the exact workflow, see `references/query.md`. + +--- + +## Less-common maintenance commands + +Use these only when the request calls for them: `graphify tree` writes a collapsible hierarchy view; `graphify global add|remove|list|path` manages the cross-repository graph; `graphify check-update ` is the cron-safe stale-graph check; `graphify diagnose multigraph` reports same-endpoint edge-collapse risk; and `graphify merge-driver ` is for a Git merge-driver invocation. Run `graphify --help` before supplying flags, and do not substitute these commands for the normal build/query workflow. + +--- + ## For /graphify add and --watch Neither is part of the default build. When the user runs `/graphify add ` to fetch a URL into the corpus, or passes `--watch` to auto-rebuild on file changes, see `references/add-watch.md`. diff --git a/graphify/skill-codex.md b/graphify/skill-codex.md index af3f723c78..34ffc1a08c 100644 --- a/graphify/skill-codex.md +++ b/graphify/skill-codex.md @@ -689,6 +689,18 @@ Before traversal, expand the question against the graph's own vocabulary so a wo --- +## For /graphify affected + +When the user asks for a change's blast radius or "what calls/depends on X?", use `graphify affected "X"` rather than a broad `query`. It reverse-traverses the graph from X and reports the callers and dependents that a change could impact. For relation/depth filters and the exact workflow, see `references/query.md`. + +--- + +## Less-common maintenance commands + +Use these only when the request calls for them: `graphify tree` writes a collapsible hierarchy view; `graphify global add|remove|list|path` manages the cross-repository graph; `graphify check-update ` is the cron-safe stale-graph check; `graphify diagnose multigraph` reports same-endpoint edge-collapse risk; and `graphify merge-driver ` is for a Git merge-driver invocation. Run `graphify --help` before supplying flags, and do not substitute these commands for the normal build/query workflow. + +--- + ## For /graphify add and --watch Neither is part of the default build. When the user runs `/graphify add ` to fetch a URL into the corpus, or passes `--watch` to auto-rebuild on file changes, see `references/add-watch.md`. diff --git a/graphify/skill-copilot.md b/graphify/skill-copilot.md index abd2811d23..60667e3121 100644 --- a/graphify/skill-copilot.md +++ b/graphify/skill-copilot.md @@ -692,6 +692,18 @@ Before traversal, expand the question against the graph's own vocabulary so a wo --- +## For /graphify affected + +When the user asks for a change's blast radius or "what calls/depends on X?", use `graphify affected "X"` rather than a broad `query`. It reverse-traverses the graph from X and reports the callers and dependents that a change could impact. For relation/depth filters and the exact workflow, see `references/query.md`. + +--- + +## Less-common maintenance commands + +Use these only when the request calls for them: `graphify tree` writes a collapsible hierarchy view; `graphify global add|remove|list|path` manages the cross-repository graph; `graphify check-update ` is the cron-safe stale-graph check; `graphify diagnose multigraph` reports same-endpoint edge-collapse risk; and `graphify merge-driver ` is for a Git merge-driver invocation. Run `graphify --help` before supplying flags, and do not substitute these commands for the normal build/query workflow. + +--- + ## For /graphify add and --watch Neither is part of the default build. When the user runs `/graphify add ` to fetch a URL into the corpus, or passes `--watch` to auto-rebuild on file changes, see `references/add-watch.md`. diff --git a/graphify/skill-droid.md b/graphify/skill-droid.md index fd148d485d..9f5c291136 100644 --- a/graphify/skill-droid.md +++ b/graphify/skill-droid.md @@ -689,6 +689,18 @@ Before traversal, expand the question against the graph's own vocabulary so a wo --- +## For /graphify affected + +When the user asks for a change's blast radius or "what calls/depends on X?", use `graphify affected "X"` rather than a broad `query`. It reverse-traverses the graph from X and reports the callers and dependents that a change could impact. For relation/depth filters and the exact workflow, see `references/query.md`. + +--- + +## Less-common maintenance commands + +Use these only when the request calls for them: `graphify tree` writes a collapsible hierarchy view; `graphify global add|remove|list|path` manages the cross-repository graph; `graphify check-update ` is the cron-safe stale-graph check; `graphify diagnose multigraph` reports same-endpoint edge-collapse risk; and `graphify merge-driver ` is for a Git merge-driver invocation. Run `graphify --help` before supplying flags, and do not substitute these commands for the normal build/query workflow. + +--- + ## For /graphify add and --watch Neither is part of the default build. When the user runs `/graphify add ` to fetch a URL into the corpus, or passes `--watch` to auto-rebuild on file changes, see `references/add-watch.md`. diff --git a/graphify/skill-kilo.md b/graphify/skill-kilo.md index 3e70b050a4..514a9b88f7 100644 --- a/graphify/skill-kilo.md +++ b/graphify/skill-kilo.md @@ -692,6 +692,18 @@ Before traversal, expand the question against the graph's own vocabulary so a wo --- +## For /graphify affected + +When the user asks for a change's blast radius or "what calls/depends on X?", use `graphify affected "X"` rather than a broad `query`. It reverse-traverses the graph from X and reports the callers and dependents that a change could impact. For relation/depth filters and the exact workflow, see `references/query.md`. + +--- + +## Less-common maintenance commands + +Use these only when the request calls for them: `graphify tree` writes a collapsible hierarchy view; `graphify global add|remove|list|path` manages the cross-repository graph; `graphify check-update ` is the cron-safe stale-graph check; `graphify diagnose multigraph` reports same-endpoint edge-collapse risk; and `graphify merge-driver ` is for a Git merge-driver invocation. Run `graphify --help` before supplying flags, and do not substitute these commands for the normal build/query workflow. + +--- + ## For /graphify add and --watch Neither is part of the default build. When the user runs `/graphify add ` to fetch a URL into the corpus, or passes `--watch` to auto-rebuild on file changes, see `references/add-watch.md`. diff --git a/graphify/skill-kiro.md b/graphify/skill-kiro.md index abd2811d23..60667e3121 100644 --- a/graphify/skill-kiro.md +++ b/graphify/skill-kiro.md @@ -692,6 +692,18 @@ Before traversal, expand the question against the graph's own vocabulary so a wo --- +## For /graphify affected + +When the user asks for a change's blast radius or "what calls/depends on X?", use `graphify affected "X"` rather than a broad `query`. It reverse-traverses the graph from X and reports the callers and dependents that a change could impact. For relation/depth filters and the exact workflow, see `references/query.md`. + +--- + +## Less-common maintenance commands + +Use these only when the request calls for them: `graphify tree` writes a collapsible hierarchy view; `graphify global add|remove|list|path` manages the cross-repository graph; `graphify check-update ` is the cron-safe stale-graph check; `graphify diagnose multigraph` reports same-endpoint edge-collapse risk; and `graphify merge-driver ` is for a Git merge-driver invocation. Run `graphify --help` before supplying flags, and do not substitute these commands for the normal build/query workflow. + +--- + ## For /graphify add and --watch Neither is part of the default build. When the user runs `/graphify add ` to fetch a URL into the corpus, or passes `--watch` to auto-rebuild on file changes, see `references/add-watch.md`. diff --git a/graphify/skill-opencode.md b/graphify/skill-opencode.md index 91ced60675..f573d68b15 100644 --- a/graphify/skill-opencode.md +++ b/graphify/skill-opencode.md @@ -684,6 +684,18 @@ Before traversal, expand the question against the graph's own vocabulary so a wo --- +## For /graphify affected + +When the user asks for a change's blast radius or "what calls/depends on X?", use `graphify affected "X"` rather than a broad `query`. It reverse-traverses the graph from X and reports the callers and dependents that a change could impact. For relation/depth filters and the exact workflow, see `references/query.md`. + +--- + +## Less-common maintenance commands + +Use these only when the request calls for them: `graphify tree` writes a collapsible hierarchy view; `graphify global add|remove|list|path` manages the cross-repository graph; `graphify check-update ` is the cron-safe stale-graph check; `graphify diagnose multigraph` reports same-endpoint edge-collapse risk; and `graphify merge-driver ` is for a Git merge-driver invocation. Run `graphify --help` before supplying flags, and do not substitute these commands for the normal build/query workflow. + +--- + ## For /graphify add and --watch Neither is part of the default build. When the user runs `/graphify add ` to fetch a URL into the corpus, or passes `--watch` to auto-rebuild on file changes, see `references/add-watch.md`. diff --git a/graphify/skill-pi.md b/graphify/skill-pi.md index abd2811d23..60667e3121 100644 --- a/graphify/skill-pi.md +++ b/graphify/skill-pi.md @@ -692,6 +692,18 @@ Before traversal, expand the question against the graph's own vocabulary so a wo --- +## For /graphify affected + +When the user asks for a change's blast radius or "what calls/depends on X?", use `graphify affected "X"` rather than a broad `query`. It reverse-traverses the graph from X and reports the callers and dependents that a change could impact. For relation/depth filters and the exact workflow, see `references/query.md`. + +--- + +## Less-common maintenance commands + +Use these only when the request calls for them: `graphify tree` writes a collapsible hierarchy view; `graphify global add|remove|list|path` manages the cross-repository graph; `graphify check-update ` is the cron-safe stale-graph check; `graphify diagnose multigraph` reports same-endpoint edge-collapse risk; and `graphify merge-driver ` is for a Git merge-driver invocation. Run `graphify --help` before supplying flags, and do not substitute these commands for the normal build/query workflow. + +--- + ## For /graphify add and --watch Neither is part of the default build. When the user runs `/graphify add ` to fetch a URL into the corpus, or passes `--watch` to auto-rebuild on file changes, see `references/add-watch.md`. diff --git a/graphify/skill-trae.md b/graphify/skill-trae.md index 050667bc20..762c7d05de 100644 --- a/graphify/skill-trae.md +++ b/graphify/skill-trae.md @@ -690,6 +690,18 @@ Before traversal, expand the question against the graph's own vocabulary so a wo --- +## For /graphify affected + +When the user asks for a change's blast radius or "what calls/depends on X?", use `graphify affected "X"` rather than a broad `query`. It reverse-traverses the graph from X and reports the callers and dependents that a change could impact. For relation/depth filters and the exact workflow, see `references/query.md`. + +--- + +## Less-common maintenance commands + +Use these only when the request calls for them: `graphify tree` writes a collapsible hierarchy view; `graphify global add|remove|list|path` manages the cross-repository graph; `graphify check-update ` is the cron-safe stale-graph check; `graphify diagnose multigraph` reports same-endpoint edge-collapse risk; and `graphify merge-driver ` is for a Git merge-driver invocation. Run `graphify --help` before supplying flags, and do not substitute these commands for the normal build/query workflow. + +--- + ## For /graphify add and --watch Neither is part of the default build. When the user runs `/graphify add ` to fetch a URL into the corpus, or passes `--watch` to auto-rebuild on file changes, see `references/add-watch.md`. diff --git a/graphify/skill-vscode.md b/graphify/skill-vscode.md index 20c7c0835c..0e0df82af6 100644 --- a/graphify/skill-vscode.md +++ b/graphify/skill-vscode.md @@ -688,6 +688,18 @@ Before traversal, expand the question against the graph's own vocabulary so a wo --- +## For /graphify affected + +When the user asks for a change's blast radius or "what calls/depends on X?", use `graphify affected "X"` rather than a broad `query`. It reverse-traverses the graph from X and reports the callers and dependents that a change could impact. For relation/depth filters and the exact workflow, see `references/query.md`. + +--- + +## Less-common maintenance commands + +Use these only when the request calls for them: `graphify tree` writes a collapsible hierarchy view; `graphify global add|remove|list|path` manages the cross-repository graph; `graphify check-update ` is the cron-safe stale-graph check; `graphify diagnose multigraph` reports same-endpoint edge-collapse risk; and `graphify merge-driver ` is for a Git merge-driver invocation. Run `graphify --help` before supplying flags, and do not substitute these commands for the normal build/query workflow. + +--- + ## For /graphify add and --watch Neither is part of the default build. When the user runs `/graphify add ` to fetch a URL into the corpus, or passes `--watch` to auto-rebuild on file changes, see `references/add-watch.md`. diff --git a/graphify/skill-windows.md b/graphify/skill-windows.md index d631821ec3..a9bceaa2b6 100644 --- a/graphify/skill-windows.md +++ b/graphify/skill-windows.md @@ -716,6 +716,18 @@ Before traversal, expand the question against the graph's own vocabulary so a wo --- +## For /graphify affected + +When the user asks for a change's blast radius or "what calls/depends on X?", use `graphify affected "X"` rather than a broad `query`. It reverse-traverses the graph from X and reports the callers and dependents that a change could impact. For relation/depth filters and the exact workflow, see `references/query.md`. + +--- + +## Less-common maintenance commands + +Use these only when the request calls for them: `graphify tree` writes a collapsible hierarchy view; `graphify global add|remove|list|path` manages the cross-repository graph; `graphify check-update ` is the cron-safe stale-graph check; `graphify diagnose multigraph` reports same-endpoint edge-collapse risk; and `graphify merge-driver ` is for a Git merge-driver invocation. Run `graphify --help` before supplying flags, and do not substitute these commands for the normal build/query workflow. + +--- + ## For /graphify add and --watch Neither is part of the default build. When the user runs `/graphify add ` to fetch a URL into the corpus, or passes `--watch` to auto-rebuild on file changes, see `references/add-watch.md`. diff --git a/graphify/skill.md b/graphify/skill.md index abd2811d23..60667e3121 100644 --- a/graphify/skill.md +++ b/graphify/skill.md @@ -692,6 +692,18 @@ Before traversal, expand the question against the graph's own vocabulary so a wo --- +## For /graphify affected + +When the user asks for a change's blast radius or "what calls/depends on X?", use `graphify affected "X"` rather than a broad `query`. It reverse-traverses the graph from X and reports the callers and dependents that a change could impact. For relation/depth filters and the exact workflow, see `references/query.md`. + +--- + +## Less-common maintenance commands + +Use these only when the request calls for them: `graphify tree` writes a collapsible hierarchy view; `graphify global add|remove|list|path` manages the cross-repository graph; `graphify check-update ` is the cron-safe stale-graph check; `graphify diagnose multigraph` reports same-endpoint edge-collapse risk; and `graphify merge-driver ` is for a Git merge-driver invocation. Run `graphify --help` before supplying flags, and do not substitute these commands for the normal build/query workflow. + +--- + ## For /graphify add and --watch Neither is part of the default build. When the user runs `/graphify add ` to fetch a URL into the corpus, or passes `--watch` to auto-rebuild on file changes, see `references/add-watch.md`. diff --git a/graphify/skills/agents/references/query.md b/graphify/skills/agents/references/query.md index 56565eb782..85c6a303c6 100644 --- a/graphify/skills/agents/references/query.md +++ b/graphify/skills/agents/references/query.md @@ -20,6 +20,22 @@ if not Path('graphify-out/graph.json').exists(): ``` If it fails, stop and tell the user to run `/graphify ` first. +## For /graphify affected + +Use `affected` for a deterministic reverse blast-radius answer: "what calls X?", "what depends on X?", or "what could a change to X impact?". Do not replace it with a broad natural-language `query` when the user is asking that question. + +```bash +graphify affected "NODE_OR_LABEL" +``` + +The default depth is two reverse hops. Narrow the result when the user names a relationship, or widen it deliberately: + +```bash +graphify affected "NODE_OR_LABEL" --relation calls --depth 3 +``` + +Use `--graph PATH` when the graph is not at `graphify-out/graph.json`. Explain that the seed itself is the changed item; the printed nodes are the callers/dependents reached by the reverse traversal. If no nodes are found, report that the graph has no matching seed rather than inferring a negative result about the source repository. + ### Step 0 — Constrained query expansion (REQUIRED before traversal) graphify's `query` CLI matches nodes via case-folded substring + IDF — there is **no stemming, no synonyms, no cross-language match** inside the binary, and the inline fallback below matches the same way. If the user's question uses different language or different domain vocabulary than the graph's labels (user says "обработчик" / graph says "handler"; user says "authentication" / graph says "Guardian"), the literal matcher returns 0 hits and the answer collapses to noise. diff --git a/graphify/skills/agents/references/update.md b/graphify/skills/agents/references/update.md index 3632fd4126..4ce77933bb 100644 --- a/graphify/skills/agents/references/update.md +++ b/graphify/skills/agents/references/update.md @@ -208,3 +208,13 @@ graphify cluster-only . ``` `graphify cluster-only .` is **self-contained**: it re-clusters, names communities, and regenerates `GRAPH_REPORT.md`, `graph.json`, and `graph.html` from the existing graph. **Do not re-run Steps 5–9** — they read intermediate files (`.graphify_extract.json`, `.graphify_detect.json`, `.graphify_analysis.json`) that a prior build's cleanup (Step 9) already deleted, so they raise `FileNotFoundError` (#1392). When it finishes, present the refreshed `GRAPH_REPORT.md` summary as usual. + +## Verify apparently-successful maintenance runs + +Treat a zero exit code as the start of verification, not proof that the requested work happened: + +- `cluster-only` rebuilds communities; it is not the reliable way to force a new LLM naming pass when labels already exist. Run `graphify label . --backend BACKEND` to re-name communities, then inspect `GRAPH_REPORT.md`: a real labeling run has non-zero `Token cost` and labels other than `Community N`. +- `tree` writes `graphify-out/GRAPH_TREE.html`. If a hierarchy matters, inspect the generated view and ensure the chosen `--root` is the project root; a successful write alone does not prove the intended subtree was selected. +- If output says `Skipped graph.html`, `graph.json` and `GRAPH_REPORT.md` were still written. Use `--no-viz` for CI, or raise `GRAPHIFY_VIZ_NODE_LIMIT` only when the browser can handle the larger view. If writing `graph.json` itself hits the size guard, raise `GRAPHIFY_MAX_GRAPH_BYTES` (for example `700MB`) deliberately. +- A warning that `.sql` or `.tf` files produced zero nodes means that language is absent from the graph. Install the matching extra and rerun: `uv tool install "graphifyy[sql]"` or `uv tool install "graphifyy[terraform]"`. +- The `openai` backend requires `uv tool install "graphifyy[openai]"`. For an OpenAI-compatible gateway, set `OPENAI_BASE_URL` and `OPENAI_MODEL` and pass `--backend openai`. diff --git a/graphify/skills/amp/references/query.md b/graphify/skills/amp/references/query.md index 56565eb782..85c6a303c6 100644 --- a/graphify/skills/amp/references/query.md +++ b/graphify/skills/amp/references/query.md @@ -20,6 +20,22 @@ if not Path('graphify-out/graph.json').exists(): ``` If it fails, stop and tell the user to run `/graphify ` first. +## For /graphify affected + +Use `affected` for a deterministic reverse blast-radius answer: "what calls X?", "what depends on X?", or "what could a change to X impact?". Do not replace it with a broad natural-language `query` when the user is asking that question. + +```bash +graphify affected "NODE_OR_LABEL" +``` + +The default depth is two reverse hops. Narrow the result when the user names a relationship, or widen it deliberately: + +```bash +graphify affected "NODE_OR_LABEL" --relation calls --depth 3 +``` + +Use `--graph PATH` when the graph is not at `graphify-out/graph.json`. Explain that the seed itself is the changed item; the printed nodes are the callers/dependents reached by the reverse traversal. If no nodes are found, report that the graph has no matching seed rather than inferring a negative result about the source repository. + ### Step 0 — Constrained query expansion (REQUIRED before traversal) graphify's `query` CLI matches nodes via case-folded substring + IDF — there is **no stemming, no synonyms, no cross-language match** inside the binary, and the inline fallback below matches the same way. If the user's question uses different language or different domain vocabulary than the graph's labels (user says "обработчик" / graph says "handler"; user says "authentication" / graph says "Guardian"), the literal matcher returns 0 hits and the answer collapses to noise. diff --git a/graphify/skills/amp/references/update.md b/graphify/skills/amp/references/update.md index 3632fd4126..4ce77933bb 100644 --- a/graphify/skills/amp/references/update.md +++ b/graphify/skills/amp/references/update.md @@ -208,3 +208,13 @@ graphify cluster-only . ``` `graphify cluster-only .` is **self-contained**: it re-clusters, names communities, and regenerates `GRAPH_REPORT.md`, `graph.json`, and `graph.html` from the existing graph. **Do not re-run Steps 5–9** — they read intermediate files (`.graphify_extract.json`, `.graphify_detect.json`, `.graphify_analysis.json`) that a prior build's cleanup (Step 9) already deleted, so they raise `FileNotFoundError` (#1392). When it finishes, present the refreshed `GRAPH_REPORT.md` summary as usual. + +## Verify apparently-successful maintenance runs + +Treat a zero exit code as the start of verification, not proof that the requested work happened: + +- `cluster-only` rebuilds communities; it is not the reliable way to force a new LLM naming pass when labels already exist. Run `graphify label . --backend BACKEND` to re-name communities, then inspect `GRAPH_REPORT.md`: a real labeling run has non-zero `Token cost` and labels other than `Community N`. +- `tree` writes `graphify-out/GRAPH_TREE.html`. If a hierarchy matters, inspect the generated view and ensure the chosen `--root` is the project root; a successful write alone does not prove the intended subtree was selected. +- If output says `Skipped graph.html`, `graph.json` and `GRAPH_REPORT.md` were still written. Use `--no-viz` for CI, or raise `GRAPHIFY_VIZ_NODE_LIMIT` only when the browser can handle the larger view. If writing `graph.json` itself hits the size guard, raise `GRAPHIFY_MAX_GRAPH_BYTES` (for example `700MB`) deliberately. +- A warning that `.sql` or `.tf` files produced zero nodes means that language is absent from the graph. Install the matching extra and rerun: `uv tool install "graphifyy[sql]"` or `uv tool install "graphifyy[terraform]"`. +- The `openai` backend requires `uv tool install "graphifyy[openai]"`. For an OpenAI-compatible gateway, set `OPENAI_BASE_URL` and `OPENAI_MODEL` and pass `--backend openai`. diff --git a/graphify/skills/claude/references/query.md b/graphify/skills/claude/references/query.md index 56565eb782..85c6a303c6 100644 --- a/graphify/skills/claude/references/query.md +++ b/graphify/skills/claude/references/query.md @@ -20,6 +20,22 @@ if not Path('graphify-out/graph.json').exists(): ``` If it fails, stop and tell the user to run `/graphify ` first. +## For /graphify affected + +Use `affected` for a deterministic reverse blast-radius answer: "what calls X?", "what depends on X?", or "what could a change to X impact?". Do not replace it with a broad natural-language `query` when the user is asking that question. + +```bash +graphify affected "NODE_OR_LABEL" +``` + +The default depth is two reverse hops. Narrow the result when the user names a relationship, or widen it deliberately: + +```bash +graphify affected "NODE_OR_LABEL" --relation calls --depth 3 +``` + +Use `--graph PATH` when the graph is not at `graphify-out/graph.json`. Explain that the seed itself is the changed item; the printed nodes are the callers/dependents reached by the reverse traversal. If no nodes are found, report that the graph has no matching seed rather than inferring a negative result about the source repository. + ### Step 0 — Constrained query expansion (REQUIRED before traversal) graphify's `query` CLI matches nodes via case-folded substring + IDF — there is **no stemming, no synonyms, no cross-language match** inside the binary, and the inline fallback below matches the same way. If the user's question uses different language or different domain vocabulary than the graph's labels (user says "обработчик" / graph says "handler"; user says "authentication" / graph says "Guardian"), the literal matcher returns 0 hits and the answer collapses to noise. diff --git a/graphify/skills/claude/references/update.md b/graphify/skills/claude/references/update.md index 3632fd4126..4ce77933bb 100644 --- a/graphify/skills/claude/references/update.md +++ b/graphify/skills/claude/references/update.md @@ -208,3 +208,13 @@ graphify cluster-only . ``` `graphify cluster-only .` is **self-contained**: it re-clusters, names communities, and regenerates `GRAPH_REPORT.md`, `graph.json`, and `graph.html` from the existing graph. **Do not re-run Steps 5–9** — they read intermediate files (`.graphify_extract.json`, `.graphify_detect.json`, `.graphify_analysis.json`) that a prior build's cleanup (Step 9) already deleted, so they raise `FileNotFoundError` (#1392). When it finishes, present the refreshed `GRAPH_REPORT.md` summary as usual. + +## Verify apparently-successful maintenance runs + +Treat a zero exit code as the start of verification, not proof that the requested work happened: + +- `cluster-only` rebuilds communities; it is not the reliable way to force a new LLM naming pass when labels already exist. Run `graphify label . --backend BACKEND` to re-name communities, then inspect `GRAPH_REPORT.md`: a real labeling run has non-zero `Token cost` and labels other than `Community N`. +- `tree` writes `graphify-out/GRAPH_TREE.html`. If a hierarchy matters, inspect the generated view and ensure the chosen `--root` is the project root; a successful write alone does not prove the intended subtree was selected. +- If output says `Skipped graph.html`, `graph.json` and `GRAPH_REPORT.md` were still written. Use `--no-viz` for CI, or raise `GRAPHIFY_VIZ_NODE_LIMIT` only when the browser can handle the larger view. If writing `graph.json` itself hits the size guard, raise `GRAPHIFY_MAX_GRAPH_BYTES` (for example `700MB`) deliberately. +- A warning that `.sql` or `.tf` files produced zero nodes means that language is absent from the graph. Install the matching extra and rerun: `uv tool install "graphifyy[sql]"` or `uv tool install "graphifyy[terraform]"`. +- The `openai` backend requires `uv tool install "graphifyy[openai]"`. For an OpenAI-compatible gateway, set `OPENAI_BASE_URL` and `OPENAI_MODEL` and pass `--backend openai`. diff --git a/graphify/skills/claw/references/query.md b/graphify/skills/claw/references/query.md index 56565eb782..85c6a303c6 100644 --- a/graphify/skills/claw/references/query.md +++ b/graphify/skills/claw/references/query.md @@ -20,6 +20,22 @@ if not Path('graphify-out/graph.json').exists(): ``` If it fails, stop and tell the user to run `/graphify ` first. +## For /graphify affected + +Use `affected` for a deterministic reverse blast-radius answer: "what calls X?", "what depends on X?", or "what could a change to X impact?". Do not replace it with a broad natural-language `query` when the user is asking that question. + +```bash +graphify affected "NODE_OR_LABEL" +``` + +The default depth is two reverse hops. Narrow the result when the user names a relationship, or widen it deliberately: + +```bash +graphify affected "NODE_OR_LABEL" --relation calls --depth 3 +``` + +Use `--graph PATH` when the graph is not at `graphify-out/graph.json`. Explain that the seed itself is the changed item; the printed nodes are the callers/dependents reached by the reverse traversal. If no nodes are found, report that the graph has no matching seed rather than inferring a negative result about the source repository. + ### Step 0 — Constrained query expansion (REQUIRED before traversal) graphify's `query` CLI matches nodes via case-folded substring + IDF — there is **no stemming, no synonyms, no cross-language match** inside the binary, and the inline fallback below matches the same way. If the user's question uses different language or different domain vocabulary than the graph's labels (user says "обработчик" / graph says "handler"; user says "authentication" / graph says "Guardian"), the literal matcher returns 0 hits and the answer collapses to noise. diff --git a/graphify/skills/claw/references/update.md b/graphify/skills/claw/references/update.md index 3632fd4126..4ce77933bb 100644 --- a/graphify/skills/claw/references/update.md +++ b/graphify/skills/claw/references/update.md @@ -208,3 +208,13 @@ graphify cluster-only . ``` `graphify cluster-only .` is **self-contained**: it re-clusters, names communities, and regenerates `GRAPH_REPORT.md`, `graph.json`, and `graph.html` from the existing graph. **Do not re-run Steps 5–9** — they read intermediate files (`.graphify_extract.json`, `.graphify_detect.json`, `.graphify_analysis.json`) that a prior build's cleanup (Step 9) already deleted, so they raise `FileNotFoundError` (#1392). When it finishes, present the refreshed `GRAPH_REPORT.md` summary as usual. + +## Verify apparently-successful maintenance runs + +Treat a zero exit code as the start of verification, not proof that the requested work happened: + +- `cluster-only` rebuilds communities; it is not the reliable way to force a new LLM naming pass when labels already exist. Run `graphify label . --backend BACKEND` to re-name communities, then inspect `GRAPH_REPORT.md`: a real labeling run has non-zero `Token cost` and labels other than `Community N`. +- `tree` writes `graphify-out/GRAPH_TREE.html`. If a hierarchy matters, inspect the generated view and ensure the chosen `--root` is the project root; a successful write alone does not prove the intended subtree was selected. +- If output says `Skipped graph.html`, `graph.json` and `GRAPH_REPORT.md` were still written. Use `--no-viz` for CI, or raise `GRAPHIFY_VIZ_NODE_LIMIT` only when the browser can handle the larger view. If writing `graph.json` itself hits the size guard, raise `GRAPHIFY_MAX_GRAPH_BYTES` (for example `700MB`) deliberately. +- A warning that `.sql` or `.tf` files produced zero nodes means that language is absent from the graph. Install the matching extra and rerun: `uv tool install "graphifyy[sql]"` or `uv tool install "graphifyy[terraform]"`. +- The `openai` backend requires `uv tool install "graphifyy[openai]"`. For an OpenAI-compatible gateway, set `OPENAI_BASE_URL` and `OPENAI_MODEL` and pass `--backend openai`. diff --git a/graphify/skills/codex/references/query.md b/graphify/skills/codex/references/query.md index 56565eb782..85c6a303c6 100644 --- a/graphify/skills/codex/references/query.md +++ b/graphify/skills/codex/references/query.md @@ -20,6 +20,22 @@ if not Path('graphify-out/graph.json').exists(): ``` If it fails, stop and tell the user to run `/graphify ` first. +## For /graphify affected + +Use `affected` for a deterministic reverse blast-radius answer: "what calls X?", "what depends on X?", or "what could a change to X impact?". Do not replace it with a broad natural-language `query` when the user is asking that question. + +```bash +graphify affected "NODE_OR_LABEL" +``` + +The default depth is two reverse hops. Narrow the result when the user names a relationship, or widen it deliberately: + +```bash +graphify affected "NODE_OR_LABEL" --relation calls --depth 3 +``` + +Use `--graph PATH` when the graph is not at `graphify-out/graph.json`. Explain that the seed itself is the changed item; the printed nodes are the callers/dependents reached by the reverse traversal. If no nodes are found, report that the graph has no matching seed rather than inferring a negative result about the source repository. + ### Step 0 — Constrained query expansion (REQUIRED before traversal) graphify's `query` CLI matches nodes via case-folded substring + IDF — there is **no stemming, no synonyms, no cross-language match** inside the binary, and the inline fallback below matches the same way. If the user's question uses different language or different domain vocabulary than the graph's labels (user says "обработчик" / graph says "handler"; user says "authentication" / graph says "Guardian"), the literal matcher returns 0 hits and the answer collapses to noise. diff --git a/graphify/skills/codex/references/update.md b/graphify/skills/codex/references/update.md index 3632fd4126..4ce77933bb 100644 --- a/graphify/skills/codex/references/update.md +++ b/graphify/skills/codex/references/update.md @@ -208,3 +208,13 @@ graphify cluster-only . ``` `graphify cluster-only .` is **self-contained**: it re-clusters, names communities, and regenerates `GRAPH_REPORT.md`, `graph.json`, and `graph.html` from the existing graph. **Do not re-run Steps 5–9** — they read intermediate files (`.graphify_extract.json`, `.graphify_detect.json`, `.graphify_analysis.json`) that a prior build's cleanup (Step 9) already deleted, so they raise `FileNotFoundError` (#1392). When it finishes, present the refreshed `GRAPH_REPORT.md` summary as usual. + +## Verify apparently-successful maintenance runs + +Treat a zero exit code as the start of verification, not proof that the requested work happened: + +- `cluster-only` rebuilds communities; it is not the reliable way to force a new LLM naming pass when labels already exist. Run `graphify label . --backend BACKEND` to re-name communities, then inspect `GRAPH_REPORT.md`: a real labeling run has non-zero `Token cost` and labels other than `Community N`. +- `tree` writes `graphify-out/GRAPH_TREE.html`. If a hierarchy matters, inspect the generated view and ensure the chosen `--root` is the project root; a successful write alone does not prove the intended subtree was selected. +- If output says `Skipped graph.html`, `graph.json` and `GRAPH_REPORT.md` were still written. Use `--no-viz` for CI, or raise `GRAPHIFY_VIZ_NODE_LIMIT` only when the browser can handle the larger view. If writing `graph.json` itself hits the size guard, raise `GRAPHIFY_MAX_GRAPH_BYTES` (for example `700MB`) deliberately. +- A warning that `.sql` or `.tf` files produced zero nodes means that language is absent from the graph. Install the matching extra and rerun: `uv tool install "graphifyy[sql]"` or `uv tool install "graphifyy[terraform]"`. +- The `openai` backend requires `uv tool install "graphifyy[openai]"`. For an OpenAI-compatible gateway, set `OPENAI_BASE_URL` and `OPENAI_MODEL` and pass `--backend openai`. diff --git a/graphify/skills/copilot/references/query.md b/graphify/skills/copilot/references/query.md index 56565eb782..85c6a303c6 100644 --- a/graphify/skills/copilot/references/query.md +++ b/graphify/skills/copilot/references/query.md @@ -20,6 +20,22 @@ if not Path('graphify-out/graph.json').exists(): ``` If it fails, stop and tell the user to run `/graphify ` first. +## For /graphify affected + +Use `affected` for a deterministic reverse blast-radius answer: "what calls X?", "what depends on X?", or "what could a change to X impact?". Do not replace it with a broad natural-language `query` when the user is asking that question. + +```bash +graphify affected "NODE_OR_LABEL" +``` + +The default depth is two reverse hops. Narrow the result when the user names a relationship, or widen it deliberately: + +```bash +graphify affected "NODE_OR_LABEL" --relation calls --depth 3 +``` + +Use `--graph PATH` when the graph is not at `graphify-out/graph.json`. Explain that the seed itself is the changed item; the printed nodes are the callers/dependents reached by the reverse traversal. If no nodes are found, report that the graph has no matching seed rather than inferring a negative result about the source repository. + ### Step 0 — Constrained query expansion (REQUIRED before traversal) graphify's `query` CLI matches nodes via case-folded substring + IDF — there is **no stemming, no synonyms, no cross-language match** inside the binary, and the inline fallback below matches the same way. If the user's question uses different language or different domain vocabulary than the graph's labels (user says "обработчик" / graph says "handler"; user says "authentication" / graph says "Guardian"), the literal matcher returns 0 hits and the answer collapses to noise. diff --git a/graphify/skills/copilot/references/update.md b/graphify/skills/copilot/references/update.md index 3632fd4126..4ce77933bb 100644 --- a/graphify/skills/copilot/references/update.md +++ b/graphify/skills/copilot/references/update.md @@ -208,3 +208,13 @@ graphify cluster-only . ``` `graphify cluster-only .` is **self-contained**: it re-clusters, names communities, and regenerates `GRAPH_REPORT.md`, `graph.json`, and `graph.html` from the existing graph. **Do not re-run Steps 5–9** — they read intermediate files (`.graphify_extract.json`, `.graphify_detect.json`, `.graphify_analysis.json`) that a prior build's cleanup (Step 9) already deleted, so they raise `FileNotFoundError` (#1392). When it finishes, present the refreshed `GRAPH_REPORT.md` summary as usual. + +## Verify apparently-successful maintenance runs + +Treat a zero exit code as the start of verification, not proof that the requested work happened: + +- `cluster-only` rebuilds communities; it is not the reliable way to force a new LLM naming pass when labels already exist. Run `graphify label . --backend BACKEND` to re-name communities, then inspect `GRAPH_REPORT.md`: a real labeling run has non-zero `Token cost` and labels other than `Community N`. +- `tree` writes `graphify-out/GRAPH_TREE.html`. If a hierarchy matters, inspect the generated view and ensure the chosen `--root` is the project root; a successful write alone does not prove the intended subtree was selected. +- If output says `Skipped graph.html`, `graph.json` and `GRAPH_REPORT.md` were still written. Use `--no-viz` for CI, or raise `GRAPHIFY_VIZ_NODE_LIMIT` only when the browser can handle the larger view. If writing `graph.json` itself hits the size guard, raise `GRAPHIFY_MAX_GRAPH_BYTES` (for example `700MB`) deliberately. +- A warning that `.sql` or `.tf` files produced zero nodes means that language is absent from the graph. Install the matching extra and rerun: `uv tool install "graphifyy[sql]"` or `uv tool install "graphifyy[terraform]"`. +- The `openai` backend requires `uv tool install "graphifyy[openai]"`. For an OpenAI-compatible gateway, set `OPENAI_BASE_URL` and `OPENAI_MODEL` and pass `--backend openai`. diff --git a/graphify/skills/droid/references/query.md b/graphify/skills/droid/references/query.md index 56565eb782..85c6a303c6 100644 --- a/graphify/skills/droid/references/query.md +++ b/graphify/skills/droid/references/query.md @@ -20,6 +20,22 @@ if not Path('graphify-out/graph.json').exists(): ``` If it fails, stop and tell the user to run `/graphify ` first. +## For /graphify affected + +Use `affected` for a deterministic reverse blast-radius answer: "what calls X?", "what depends on X?", or "what could a change to X impact?". Do not replace it with a broad natural-language `query` when the user is asking that question. + +```bash +graphify affected "NODE_OR_LABEL" +``` + +The default depth is two reverse hops. Narrow the result when the user names a relationship, or widen it deliberately: + +```bash +graphify affected "NODE_OR_LABEL" --relation calls --depth 3 +``` + +Use `--graph PATH` when the graph is not at `graphify-out/graph.json`. Explain that the seed itself is the changed item; the printed nodes are the callers/dependents reached by the reverse traversal. If no nodes are found, report that the graph has no matching seed rather than inferring a negative result about the source repository. + ### Step 0 — Constrained query expansion (REQUIRED before traversal) graphify's `query` CLI matches nodes via case-folded substring + IDF — there is **no stemming, no synonyms, no cross-language match** inside the binary, and the inline fallback below matches the same way. If the user's question uses different language or different domain vocabulary than the graph's labels (user says "обработчик" / graph says "handler"; user says "authentication" / graph says "Guardian"), the literal matcher returns 0 hits and the answer collapses to noise. diff --git a/graphify/skills/droid/references/update.md b/graphify/skills/droid/references/update.md index 3632fd4126..4ce77933bb 100644 --- a/graphify/skills/droid/references/update.md +++ b/graphify/skills/droid/references/update.md @@ -208,3 +208,13 @@ graphify cluster-only . ``` `graphify cluster-only .` is **self-contained**: it re-clusters, names communities, and regenerates `GRAPH_REPORT.md`, `graph.json`, and `graph.html` from the existing graph. **Do not re-run Steps 5–9** — they read intermediate files (`.graphify_extract.json`, `.graphify_detect.json`, `.graphify_analysis.json`) that a prior build's cleanup (Step 9) already deleted, so they raise `FileNotFoundError` (#1392). When it finishes, present the refreshed `GRAPH_REPORT.md` summary as usual. + +## Verify apparently-successful maintenance runs + +Treat a zero exit code as the start of verification, not proof that the requested work happened: + +- `cluster-only` rebuilds communities; it is not the reliable way to force a new LLM naming pass when labels already exist. Run `graphify label . --backend BACKEND` to re-name communities, then inspect `GRAPH_REPORT.md`: a real labeling run has non-zero `Token cost` and labels other than `Community N`. +- `tree` writes `graphify-out/GRAPH_TREE.html`. If a hierarchy matters, inspect the generated view and ensure the chosen `--root` is the project root; a successful write alone does not prove the intended subtree was selected. +- If output says `Skipped graph.html`, `graph.json` and `GRAPH_REPORT.md` were still written. Use `--no-viz` for CI, or raise `GRAPHIFY_VIZ_NODE_LIMIT` only when the browser can handle the larger view. If writing `graph.json` itself hits the size guard, raise `GRAPHIFY_MAX_GRAPH_BYTES` (for example `700MB`) deliberately. +- A warning that `.sql` or `.tf` files produced zero nodes means that language is absent from the graph. Install the matching extra and rerun: `uv tool install "graphifyy[sql]"` or `uv tool install "graphifyy[terraform]"`. +- The `openai` backend requires `uv tool install "graphifyy[openai]"`. For an OpenAI-compatible gateway, set `OPENAI_BASE_URL` and `OPENAI_MODEL` and pass `--backend openai`. diff --git a/graphify/skills/kilo/references/query.md b/graphify/skills/kilo/references/query.md index 56565eb782..85c6a303c6 100644 --- a/graphify/skills/kilo/references/query.md +++ b/graphify/skills/kilo/references/query.md @@ -20,6 +20,22 @@ if not Path('graphify-out/graph.json').exists(): ``` If it fails, stop and tell the user to run `/graphify ` first. +## For /graphify affected + +Use `affected` for a deterministic reverse blast-radius answer: "what calls X?", "what depends on X?", or "what could a change to X impact?". Do not replace it with a broad natural-language `query` when the user is asking that question. + +```bash +graphify affected "NODE_OR_LABEL" +``` + +The default depth is two reverse hops. Narrow the result when the user names a relationship, or widen it deliberately: + +```bash +graphify affected "NODE_OR_LABEL" --relation calls --depth 3 +``` + +Use `--graph PATH` when the graph is not at `graphify-out/graph.json`. Explain that the seed itself is the changed item; the printed nodes are the callers/dependents reached by the reverse traversal. If no nodes are found, report that the graph has no matching seed rather than inferring a negative result about the source repository. + ### Step 0 — Constrained query expansion (REQUIRED before traversal) graphify's `query` CLI matches nodes via case-folded substring + IDF — there is **no stemming, no synonyms, no cross-language match** inside the binary, and the inline fallback below matches the same way. If the user's question uses different language or different domain vocabulary than the graph's labels (user says "обработчик" / graph says "handler"; user says "authentication" / graph says "Guardian"), the literal matcher returns 0 hits and the answer collapses to noise. diff --git a/graphify/skills/kilo/references/update.md b/graphify/skills/kilo/references/update.md index 3632fd4126..4ce77933bb 100644 --- a/graphify/skills/kilo/references/update.md +++ b/graphify/skills/kilo/references/update.md @@ -208,3 +208,13 @@ graphify cluster-only . ``` `graphify cluster-only .` is **self-contained**: it re-clusters, names communities, and regenerates `GRAPH_REPORT.md`, `graph.json`, and `graph.html` from the existing graph. **Do not re-run Steps 5–9** — they read intermediate files (`.graphify_extract.json`, `.graphify_detect.json`, `.graphify_analysis.json`) that a prior build's cleanup (Step 9) already deleted, so they raise `FileNotFoundError` (#1392). When it finishes, present the refreshed `GRAPH_REPORT.md` summary as usual. + +## Verify apparently-successful maintenance runs + +Treat a zero exit code as the start of verification, not proof that the requested work happened: + +- `cluster-only` rebuilds communities; it is not the reliable way to force a new LLM naming pass when labels already exist. Run `graphify label . --backend BACKEND` to re-name communities, then inspect `GRAPH_REPORT.md`: a real labeling run has non-zero `Token cost` and labels other than `Community N`. +- `tree` writes `graphify-out/GRAPH_TREE.html`. If a hierarchy matters, inspect the generated view and ensure the chosen `--root` is the project root; a successful write alone does not prove the intended subtree was selected. +- If output says `Skipped graph.html`, `graph.json` and `GRAPH_REPORT.md` were still written. Use `--no-viz` for CI, or raise `GRAPHIFY_VIZ_NODE_LIMIT` only when the browser can handle the larger view. If writing `graph.json` itself hits the size guard, raise `GRAPHIFY_MAX_GRAPH_BYTES` (for example `700MB`) deliberately. +- A warning that `.sql` or `.tf` files produced zero nodes means that language is absent from the graph. Install the matching extra and rerun: `uv tool install "graphifyy[sql]"` or `uv tool install "graphifyy[terraform]"`. +- The `openai` backend requires `uv tool install "graphifyy[openai]"`. For an OpenAI-compatible gateway, set `OPENAI_BASE_URL` and `OPENAI_MODEL` and pass `--backend openai`. diff --git a/graphify/skills/kiro/references/query.md b/graphify/skills/kiro/references/query.md index 56565eb782..85c6a303c6 100644 --- a/graphify/skills/kiro/references/query.md +++ b/graphify/skills/kiro/references/query.md @@ -20,6 +20,22 @@ if not Path('graphify-out/graph.json').exists(): ``` If it fails, stop and tell the user to run `/graphify ` first. +## For /graphify affected + +Use `affected` for a deterministic reverse blast-radius answer: "what calls X?", "what depends on X?", or "what could a change to X impact?". Do not replace it with a broad natural-language `query` when the user is asking that question. + +```bash +graphify affected "NODE_OR_LABEL" +``` + +The default depth is two reverse hops. Narrow the result when the user names a relationship, or widen it deliberately: + +```bash +graphify affected "NODE_OR_LABEL" --relation calls --depth 3 +``` + +Use `--graph PATH` when the graph is not at `graphify-out/graph.json`. Explain that the seed itself is the changed item; the printed nodes are the callers/dependents reached by the reverse traversal. If no nodes are found, report that the graph has no matching seed rather than inferring a negative result about the source repository. + ### Step 0 — Constrained query expansion (REQUIRED before traversal) graphify's `query` CLI matches nodes via case-folded substring + IDF — there is **no stemming, no synonyms, no cross-language match** inside the binary, and the inline fallback below matches the same way. If the user's question uses different language or different domain vocabulary than the graph's labels (user says "обработчик" / graph says "handler"; user says "authentication" / graph says "Guardian"), the literal matcher returns 0 hits and the answer collapses to noise. diff --git a/graphify/skills/kiro/references/update.md b/graphify/skills/kiro/references/update.md index 3632fd4126..4ce77933bb 100644 --- a/graphify/skills/kiro/references/update.md +++ b/graphify/skills/kiro/references/update.md @@ -208,3 +208,13 @@ graphify cluster-only . ``` `graphify cluster-only .` is **self-contained**: it re-clusters, names communities, and regenerates `GRAPH_REPORT.md`, `graph.json`, and `graph.html` from the existing graph. **Do not re-run Steps 5–9** — they read intermediate files (`.graphify_extract.json`, `.graphify_detect.json`, `.graphify_analysis.json`) that a prior build's cleanup (Step 9) already deleted, so they raise `FileNotFoundError` (#1392). When it finishes, present the refreshed `GRAPH_REPORT.md` summary as usual. + +## Verify apparently-successful maintenance runs + +Treat a zero exit code as the start of verification, not proof that the requested work happened: + +- `cluster-only` rebuilds communities; it is not the reliable way to force a new LLM naming pass when labels already exist. Run `graphify label . --backend BACKEND` to re-name communities, then inspect `GRAPH_REPORT.md`: a real labeling run has non-zero `Token cost` and labels other than `Community N`. +- `tree` writes `graphify-out/GRAPH_TREE.html`. If a hierarchy matters, inspect the generated view and ensure the chosen `--root` is the project root; a successful write alone does not prove the intended subtree was selected. +- If output says `Skipped graph.html`, `graph.json` and `GRAPH_REPORT.md` were still written. Use `--no-viz` for CI, or raise `GRAPHIFY_VIZ_NODE_LIMIT` only when the browser can handle the larger view. If writing `graph.json` itself hits the size guard, raise `GRAPHIFY_MAX_GRAPH_BYTES` (for example `700MB`) deliberately. +- A warning that `.sql` or `.tf` files produced zero nodes means that language is absent from the graph. Install the matching extra and rerun: `uv tool install "graphifyy[sql]"` or `uv tool install "graphifyy[terraform]"`. +- The `openai` backend requires `uv tool install "graphifyy[openai]"`. For an OpenAI-compatible gateway, set `OPENAI_BASE_URL` and `OPENAI_MODEL` and pass `--backend openai`. diff --git a/graphify/skills/opencode/references/query.md b/graphify/skills/opencode/references/query.md index 56565eb782..85c6a303c6 100644 --- a/graphify/skills/opencode/references/query.md +++ b/graphify/skills/opencode/references/query.md @@ -20,6 +20,22 @@ if not Path('graphify-out/graph.json').exists(): ``` If it fails, stop and tell the user to run `/graphify ` first. +## For /graphify affected + +Use `affected` for a deterministic reverse blast-radius answer: "what calls X?", "what depends on X?", or "what could a change to X impact?". Do not replace it with a broad natural-language `query` when the user is asking that question. + +```bash +graphify affected "NODE_OR_LABEL" +``` + +The default depth is two reverse hops. Narrow the result when the user names a relationship, or widen it deliberately: + +```bash +graphify affected "NODE_OR_LABEL" --relation calls --depth 3 +``` + +Use `--graph PATH` when the graph is not at `graphify-out/graph.json`. Explain that the seed itself is the changed item; the printed nodes are the callers/dependents reached by the reverse traversal. If no nodes are found, report that the graph has no matching seed rather than inferring a negative result about the source repository. + ### Step 0 — Constrained query expansion (REQUIRED before traversal) graphify's `query` CLI matches nodes via case-folded substring + IDF — there is **no stemming, no synonyms, no cross-language match** inside the binary, and the inline fallback below matches the same way. If the user's question uses different language or different domain vocabulary than the graph's labels (user says "обработчик" / graph says "handler"; user says "authentication" / graph says "Guardian"), the literal matcher returns 0 hits and the answer collapses to noise. diff --git a/graphify/skills/opencode/references/update.md b/graphify/skills/opencode/references/update.md index 3632fd4126..4ce77933bb 100644 --- a/graphify/skills/opencode/references/update.md +++ b/graphify/skills/opencode/references/update.md @@ -208,3 +208,13 @@ graphify cluster-only . ``` `graphify cluster-only .` is **self-contained**: it re-clusters, names communities, and regenerates `GRAPH_REPORT.md`, `graph.json`, and `graph.html` from the existing graph. **Do not re-run Steps 5–9** — they read intermediate files (`.graphify_extract.json`, `.graphify_detect.json`, `.graphify_analysis.json`) that a prior build's cleanup (Step 9) already deleted, so they raise `FileNotFoundError` (#1392). When it finishes, present the refreshed `GRAPH_REPORT.md` summary as usual. + +## Verify apparently-successful maintenance runs + +Treat a zero exit code as the start of verification, not proof that the requested work happened: + +- `cluster-only` rebuilds communities; it is not the reliable way to force a new LLM naming pass when labels already exist. Run `graphify label . --backend BACKEND` to re-name communities, then inspect `GRAPH_REPORT.md`: a real labeling run has non-zero `Token cost` and labels other than `Community N`. +- `tree` writes `graphify-out/GRAPH_TREE.html`. If a hierarchy matters, inspect the generated view and ensure the chosen `--root` is the project root; a successful write alone does not prove the intended subtree was selected. +- If output says `Skipped graph.html`, `graph.json` and `GRAPH_REPORT.md` were still written. Use `--no-viz` for CI, or raise `GRAPHIFY_VIZ_NODE_LIMIT` only when the browser can handle the larger view. If writing `graph.json` itself hits the size guard, raise `GRAPHIFY_MAX_GRAPH_BYTES` (for example `700MB`) deliberately. +- A warning that `.sql` or `.tf` files produced zero nodes means that language is absent from the graph. Install the matching extra and rerun: `uv tool install "graphifyy[sql]"` or `uv tool install "graphifyy[terraform]"`. +- The `openai` backend requires `uv tool install "graphifyy[openai]"`. For an OpenAI-compatible gateway, set `OPENAI_BASE_URL` and `OPENAI_MODEL` and pass `--backend openai`. diff --git a/graphify/skills/pi/references/query.md b/graphify/skills/pi/references/query.md index 56565eb782..85c6a303c6 100644 --- a/graphify/skills/pi/references/query.md +++ b/graphify/skills/pi/references/query.md @@ -20,6 +20,22 @@ if not Path('graphify-out/graph.json').exists(): ``` If it fails, stop and tell the user to run `/graphify ` first. +## For /graphify affected + +Use `affected` for a deterministic reverse blast-radius answer: "what calls X?", "what depends on X?", or "what could a change to X impact?". Do not replace it with a broad natural-language `query` when the user is asking that question. + +```bash +graphify affected "NODE_OR_LABEL" +``` + +The default depth is two reverse hops. Narrow the result when the user names a relationship, or widen it deliberately: + +```bash +graphify affected "NODE_OR_LABEL" --relation calls --depth 3 +``` + +Use `--graph PATH` when the graph is not at `graphify-out/graph.json`. Explain that the seed itself is the changed item; the printed nodes are the callers/dependents reached by the reverse traversal. If no nodes are found, report that the graph has no matching seed rather than inferring a negative result about the source repository. + ### Step 0 — Constrained query expansion (REQUIRED before traversal) graphify's `query` CLI matches nodes via case-folded substring + IDF — there is **no stemming, no synonyms, no cross-language match** inside the binary, and the inline fallback below matches the same way. If the user's question uses different language or different domain vocabulary than the graph's labels (user says "обработчик" / graph says "handler"; user says "authentication" / graph says "Guardian"), the literal matcher returns 0 hits and the answer collapses to noise. diff --git a/graphify/skills/pi/references/update.md b/graphify/skills/pi/references/update.md index 3632fd4126..4ce77933bb 100644 --- a/graphify/skills/pi/references/update.md +++ b/graphify/skills/pi/references/update.md @@ -208,3 +208,13 @@ graphify cluster-only . ``` `graphify cluster-only .` is **self-contained**: it re-clusters, names communities, and regenerates `GRAPH_REPORT.md`, `graph.json`, and `graph.html` from the existing graph. **Do not re-run Steps 5–9** — they read intermediate files (`.graphify_extract.json`, `.graphify_detect.json`, `.graphify_analysis.json`) that a prior build's cleanup (Step 9) already deleted, so they raise `FileNotFoundError` (#1392). When it finishes, present the refreshed `GRAPH_REPORT.md` summary as usual. + +## Verify apparently-successful maintenance runs + +Treat a zero exit code as the start of verification, not proof that the requested work happened: + +- `cluster-only` rebuilds communities; it is not the reliable way to force a new LLM naming pass when labels already exist. Run `graphify label . --backend BACKEND` to re-name communities, then inspect `GRAPH_REPORT.md`: a real labeling run has non-zero `Token cost` and labels other than `Community N`. +- `tree` writes `graphify-out/GRAPH_TREE.html`. If a hierarchy matters, inspect the generated view and ensure the chosen `--root` is the project root; a successful write alone does not prove the intended subtree was selected. +- If output says `Skipped graph.html`, `graph.json` and `GRAPH_REPORT.md` were still written. Use `--no-viz` for CI, or raise `GRAPHIFY_VIZ_NODE_LIMIT` only when the browser can handle the larger view. If writing `graph.json` itself hits the size guard, raise `GRAPHIFY_MAX_GRAPH_BYTES` (for example `700MB`) deliberately. +- A warning that `.sql` or `.tf` files produced zero nodes means that language is absent from the graph. Install the matching extra and rerun: `uv tool install "graphifyy[sql]"` or `uv tool install "graphifyy[terraform]"`. +- The `openai` backend requires `uv tool install "graphifyy[openai]"`. For an OpenAI-compatible gateway, set `OPENAI_BASE_URL` and `OPENAI_MODEL` and pass `--backend openai`. diff --git a/graphify/skills/trae/references/query.md b/graphify/skills/trae/references/query.md index 56565eb782..85c6a303c6 100644 --- a/graphify/skills/trae/references/query.md +++ b/graphify/skills/trae/references/query.md @@ -20,6 +20,22 @@ if not Path('graphify-out/graph.json').exists(): ``` If it fails, stop and tell the user to run `/graphify ` first. +## For /graphify affected + +Use `affected` for a deterministic reverse blast-radius answer: "what calls X?", "what depends on X?", or "what could a change to X impact?". Do not replace it with a broad natural-language `query` when the user is asking that question. + +```bash +graphify affected "NODE_OR_LABEL" +``` + +The default depth is two reverse hops. Narrow the result when the user names a relationship, or widen it deliberately: + +```bash +graphify affected "NODE_OR_LABEL" --relation calls --depth 3 +``` + +Use `--graph PATH` when the graph is not at `graphify-out/graph.json`. Explain that the seed itself is the changed item; the printed nodes are the callers/dependents reached by the reverse traversal. If no nodes are found, report that the graph has no matching seed rather than inferring a negative result about the source repository. + ### Step 0 — Constrained query expansion (REQUIRED before traversal) graphify's `query` CLI matches nodes via case-folded substring + IDF — there is **no stemming, no synonyms, no cross-language match** inside the binary, and the inline fallback below matches the same way. If the user's question uses different language or different domain vocabulary than the graph's labels (user says "обработчик" / graph says "handler"; user says "authentication" / graph says "Guardian"), the literal matcher returns 0 hits and the answer collapses to noise. diff --git a/graphify/skills/trae/references/update.md b/graphify/skills/trae/references/update.md index 3632fd4126..4ce77933bb 100644 --- a/graphify/skills/trae/references/update.md +++ b/graphify/skills/trae/references/update.md @@ -208,3 +208,13 @@ graphify cluster-only . ``` `graphify cluster-only .` is **self-contained**: it re-clusters, names communities, and regenerates `GRAPH_REPORT.md`, `graph.json`, and `graph.html` from the existing graph. **Do not re-run Steps 5–9** — they read intermediate files (`.graphify_extract.json`, `.graphify_detect.json`, `.graphify_analysis.json`) that a prior build's cleanup (Step 9) already deleted, so they raise `FileNotFoundError` (#1392). When it finishes, present the refreshed `GRAPH_REPORT.md` summary as usual. + +## Verify apparently-successful maintenance runs + +Treat a zero exit code as the start of verification, not proof that the requested work happened: + +- `cluster-only` rebuilds communities; it is not the reliable way to force a new LLM naming pass when labels already exist. Run `graphify label . --backend BACKEND` to re-name communities, then inspect `GRAPH_REPORT.md`: a real labeling run has non-zero `Token cost` and labels other than `Community N`. +- `tree` writes `graphify-out/GRAPH_TREE.html`. If a hierarchy matters, inspect the generated view and ensure the chosen `--root` is the project root; a successful write alone does not prove the intended subtree was selected. +- If output says `Skipped graph.html`, `graph.json` and `GRAPH_REPORT.md` were still written. Use `--no-viz` for CI, or raise `GRAPHIFY_VIZ_NODE_LIMIT` only when the browser can handle the larger view. If writing `graph.json` itself hits the size guard, raise `GRAPHIFY_MAX_GRAPH_BYTES` (for example `700MB`) deliberately. +- A warning that `.sql` or `.tf` files produced zero nodes means that language is absent from the graph. Install the matching extra and rerun: `uv tool install "graphifyy[sql]"` or `uv tool install "graphifyy[terraform]"`. +- The `openai` backend requires `uv tool install "graphifyy[openai]"`. For an OpenAI-compatible gateway, set `OPENAI_BASE_URL` and `OPENAI_MODEL` and pass `--backend openai`. diff --git a/graphify/skills/vscode/references/query.md b/graphify/skills/vscode/references/query.md index 56565eb782..85c6a303c6 100644 --- a/graphify/skills/vscode/references/query.md +++ b/graphify/skills/vscode/references/query.md @@ -20,6 +20,22 @@ if not Path('graphify-out/graph.json').exists(): ``` If it fails, stop and tell the user to run `/graphify ` first. +## For /graphify affected + +Use `affected` for a deterministic reverse blast-radius answer: "what calls X?", "what depends on X?", or "what could a change to X impact?". Do not replace it with a broad natural-language `query` when the user is asking that question. + +```bash +graphify affected "NODE_OR_LABEL" +``` + +The default depth is two reverse hops. Narrow the result when the user names a relationship, or widen it deliberately: + +```bash +graphify affected "NODE_OR_LABEL" --relation calls --depth 3 +``` + +Use `--graph PATH` when the graph is not at `graphify-out/graph.json`. Explain that the seed itself is the changed item; the printed nodes are the callers/dependents reached by the reverse traversal. If no nodes are found, report that the graph has no matching seed rather than inferring a negative result about the source repository. + ### Step 0 — Constrained query expansion (REQUIRED before traversal) graphify's `query` CLI matches nodes via case-folded substring + IDF — there is **no stemming, no synonyms, no cross-language match** inside the binary, and the inline fallback below matches the same way. If the user's question uses different language or different domain vocabulary than the graph's labels (user says "обработчик" / graph says "handler"; user says "authentication" / graph says "Guardian"), the literal matcher returns 0 hits and the answer collapses to noise. diff --git a/graphify/skills/vscode/references/update.md b/graphify/skills/vscode/references/update.md index 3632fd4126..4ce77933bb 100644 --- a/graphify/skills/vscode/references/update.md +++ b/graphify/skills/vscode/references/update.md @@ -208,3 +208,13 @@ graphify cluster-only . ``` `graphify cluster-only .` is **self-contained**: it re-clusters, names communities, and regenerates `GRAPH_REPORT.md`, `graph.json`, and `graph.html` from the existing graph. **Do not re-run Steps 5–9** — they read intermediate files (`.graphify_extract.json`, `.graphify_detect.json`, `.graphify_analysis.json`) that a prior build's cleanup (Step 9) already deleted, so they raise `FileNotFoundError` (#1392). When it finishes, present the refreshed `GRAPH_REPORT.md` summary as usual. + +## Verify apparently-successful maintenance runs + +Treat a zero exit code as the start of verification, not proof that the requested work happened: + +- `cluster-only` rebuilds communities; it is not the reliable way to force a new LLM naming pass when labels already exist. Run `graphify label . --backend BACKEND` to re-name communities, then inspect `GRAPH_REPORT.md`: a real labeling run has non-zero `Token cost` and labels other than `Community N`. +- `tree` writes `graphify-out/GRAPH_TREE.html`. If a hierarchy matters, inspect the generated view and ensure the chosen `--root` is the project root; a successful write alone does not prove the intended subtree was selected. +- If output says `Skipped graph.html`, `graph.json` and `GRAPH_REPORT.md` were still written. Use `--no-viz` for CI, or raise `GRAPHIFY_VIZ_NODE_LIMIT` only when the browser can handle the larger view. If writing `graph.json` itself hits the size guard, raise `GRAPHIFY_MAX_GRAPH_BYTES` (for example `700MB`) deliberately. +- A warning that `.sql` or `.tf` files produced zero nodes means that language is absent from the graph. Install the matching extra and rerun: `uv tool install "graphifyy[sql]"` or `uv tool install "graphifyy[terraform]"`. +- The `openai` backend requires `uv tool install "graphifyy[openai]"`. For an OpenAI-compatible gateway, set `OPENAI_BASE_URL` and `OPENAI_MODEL` and pass `--backend openai`. diff --git a/graphify/skills/windows/references/query.md b/graphify/skills/windows/references/query.md index 56565eb782..85c6a303c6 100644 --- a/graphify/skills/windows/references/query.md +++ b/graphify/skills/windows/references/query.md @@ -20,6 +20,22 @@ if not Path('graphify-out/graph.json').exists(): ``` If it fails, stop and tell the user to run `/graphify ` first. +## For /graphify affected + +Use `affected` for a deterministic reverse blast-radius answer: "what calls X?", "what depends on X?", or "what could a change to X impact?". Do not replace it with a broad natural-language `query` when the user is asking that question. + +```bash +graphify affected "NODE_OR_LABEL" +``` + +The default depth is two reverse hops. Narrow the result when the user names a relationship, or widen it deliberately: + +```bash +graphify affected "NODE_OR_LABEL" --relation calls --depth 3 +``` + +Use `--graph PATH` when the graph is not at `graphify-out/graph.json`. Explain that the seed itself is the changed item; the printed nodes are the callers/dependents reached by the reverse traversal. If no nodes are found, report that the graph has no matching seed rather than inferring a negative result about the source repository. + ### Step 0 — Constrained query expansion (REQUIRED before traversal) graphify's `query` CLI matches nodes via case-folded substring + IDF — there is **no stemming, no synonyms, no cross-language match** inside the binary, and the inline fallback below matches the same way. If the user's question uses different language or different domain vocabulary than the graph's labels (user says "обработчик" / graph says "handler"; user says "authentication" / graph says "Guardian"), the literal matcher returns 0 hits and the answer collapses to noise. diff --git a/graphify/skills/windows/references/update.md b/graphify/skills/windows/references/update.md index 3632fd4126..4ce77933bb 100644 --- a/graphify/skills/windows/references/update.md +++ b/graphify/skills/windows/references/update.md @@ -208,3 +208,13 @@ graphify cluster-only . ``` `graphify cluster-only .` is **self-contained**: it re-clusters, names communities, and regenerates `GRAPH_REPORT.md`, `graph.json`, and `graph.html` from the existing graph. **Do not re-run Steps 5–9** — they read intermediate files (`.graphify_extract.json`, `.graphify_detect.json`, `.graphify_analysis.json`) that a prior build's cleanup (Step 9) already deleted, so they raise `FileNotFoundError` (#1392). When it finishes, present the refreshed `GRAPH_REPORT.md` summary as usual. + +## Verify apparently-successful maintenance runs + +Treat a zero exit code as the start of verification, not proof that the requested work happened: + +- `cluster-only` rebuilds communities; it is not the reliable way to force a new LLM naming pass when labels already exist. Run `graphify label . --backend BACKEND` to re-name communities, then inspect `GRAPH_REPORT.md`: a real labeling run has non-zero `Token cost` and labels other than `Community N`. +- `tree` writes `graphify-out/GRAPH_TREE.html`. If a hierarchy matters, inspect the generated view and ensure the chosen `--root` is the project root; a successful write alone does not prove the intended subtree was selected. +- If output says `Skipped graph.html`, `graph.json` and `GRAPH_REPORT.md` were still written. Use `--no-viz` for CI, or raise `GRAPHIFY_VIZ_NODE_LIMIT` only when the browser can handle the larger view. If writing `graph.json` itself hits the size guard, raise `GRAPHIFY_MAX_GRAPH_BYTES` (for example `700MB`) deliberately. +- A warning that `.sql` or `.tf` files produced zero nodes means that language is absent from the graph. Install the matching extra and rerun: `uv tool install "graphifyy[sql]"` or `uv tool install "graphifyy[terraform]"`. +- The `openai` backend requires `uv tool install "graphifyy[openai]"`. For an OpenAI-compatible gateway, set `OPENAI_BASE_URL` and `OPENAI_MODEL` and pass `--backend openai`. diff --git a/tools/skillgen/expected/graphify__skill-agents.md b/tools/skillgen/expected/graphify__skill-agents.md index 190827d9ac..be74f7476d 100644 --- a/tools/skillgen/expected/graphify__skill-agents.md +++ b/tools/skillgen/expected/graphify__skill-agents.md @@ -689,6 +689,18 @@ Before traversal, expand the question against the graph's own vocabulary so a wo --- +## For /graphify affected + +When the user asks for a change's blast radius or "what calls/depends on X?", use `graphify affected "X"` rather than a broad `query`. It reverse-traverses the graph from X and reports the callers and dependents that a change could impact. For relation/depth filters and the exact workflow, see `references/query.md`. + +--- + +## Less-common maintenance commands + +Use these only when the request calls for them: `graphify tree` writes a collapsible hierarchy view; `graphify global add|remove|list|path` manages the cross-repository graph; `graphify check-update ` is the cron-safe stale-graph check; `graphify diagnose multigraph` reports same-endpoint edge-collapse risk; and `graphify merge-driver ` is for a Git merge-driver invocation. Run `graphify --help` before supplying flags, and do not substitute these commands for the normal build/query workflow. + +--- + ## For /graphify add and --watch Neither is part of the default build. When the user runs `/graphify add ` to fetch a URL into the corpus, or passes `--watch` to auto-rebuild on file changes, see `references/add-watch.md`. diff --git a/tools/skillgen/expected/graphify__skill-amp.md b/tools/skillgen/expected/graphify__skill-amp.md index 190827d9ac..be74f7476d 100644 --- a/tools/skillgen/expected/graphify__skill-amp.md +++ b/tools/skillgen/expected/graphify__skill-amp.md @@ -689,6 +689,18 @@ Before traversal, expand the question against the graph's own vocabulary so a wo --- +## For /graphify affected + +When the user asks for a change's blast radius or "what calls/depends on X?", use `graphify affected "X"` rather than a broad `query`. It reverse-traverses the graph from X and reports the callers and dependents that a change could impact. For relation/depth filters and the exact workflow, see `references/query.md`. + +--- + +## Less-common maintenance commands + +Use these only when the request calls for them: `graphify tree` writes a collapsible hierarchy view; `graphify global add|remove|list|path` manages the cross-repository graph; `graphify check-update ` is the cron-safe stale-graph check; `graphify diagnose multigraph` reports same-endpoint edge-collapse risk; and `graphify merge-driver ` is for a Git merge-driver invocation. Run `graphify --help` before supplying flags, and do not substitute these commands for the normal build/query workflow. + +--- + ## For /graphify add and --watch Neither is part of the default build. When the user runs `/graphify add ` to fetch a URL into the corpus, or passes `--watch` to auto-rebuild on file changes, see `references/add-watch.md`. diff --git a/tools/skillgen/expected/graphify__skill-claw.md b/tools/skillgen/expected/graphify__skill-claw.md index abd2811d23..60667e3121 100644 --- a/tools/skillgen/expected/graphify__skill-claw.md +++ b/tools/skillgen/expected/graphify__skill-claw.md @@ -692,6 +692,18 @@ Before traversal, expand the question against the graph's own vocabulary so a wo --- +## For /graphify affected + +When the user asks for a change's blast radius or "what calls/depends on X?", use `graphify affected "X"` rather than a broad `query`. It reverse-traverses the graph from X and reports the callers and dependents that a change could impact. For relation/depth filters and the exact workflow, see `references/query.md`. + +--- + +## Less-common maintenance commands + +Use these only when the request calls for them: `graphify tree` writes a collapsible hierarchy view; `graphify global add|remove|list|path` manages the cross-repository graph; `graphify check-update ` is the cron-safe stale-graph check; `graphify diagnose multigraph` reports same-endpoint edge-collapse risk; and `graphify merge-driver ` is for a Git merge-driver invocation. Run `graphify --help` before supplying flags, and do not substitute these commands for the normal build/query workflow. + +--- + ## For /graphify add and --watch Neither is part of the default build. When the user runs `/graphify add ` to fetch a URL into the corpus, or passes `--watch` to auto-rebuild on file changes, see `references/add-watch.md`. diff --git a/tools/skillgen/expected/graphify__skill-codex.md b/tools/skillgen/expected/graphify__skill-codex.md index af3f723c78..34ffc1a08c 100644 --- a/tools/skillgen/expected/graphify__skill-codex.md +++ b/tools/skillgen/expected/graphify__skill-codex.md @@ -689,6 +689,18 @@ Before traversal, expand the question against the graph's own vocabulary so a wo --- +## For /graphify affected + +When the user asks for a change's blast radius or "what calls/depends on X?", use `graphify affected "X"` rather than a broad `query`. It reverse-traverses the graph from X and reports the callers and dependents that a change could impact. For relation/depth filters and the exact workflow, see `references/query.md`. + +--- + +## Less-common maintenance commands + +Use these only when the request calls for them: `graphify tree` writes a collapsible hierarchy view; `graphify global add|remove|list|path` manages the cross-repository graph; `graphify check-update ` is the cron-safe stale-graph check; `graphify diagnose multigraph` reports same-endpoint edge-collapse risk; and `graphify merge-driver ` is for a Git merge-driver invocation. Run `graphify --help` before supplying flags, and do not substitute these commands for the normal build/query workflow. + +--- + ## For /graphify add and --watch Neither is part of the default build. When the user runs `/graphify add ` to fetch a URL into the corpus, or passes `--watch` to auto-rebuild on file changes, see `references/add-watch.md`. diff --git a/tools/skillgen/expected/graphify__skill-copilot.md b/tools/skillgen/expected/graphify__skill-copilot.md index abd2811d23..60667e3121 100644 --- a/tools/skillgen/expected/graphify__skill-copilot.md +++ b/tools/skillgen/expected/graphify__skill-copilot.md @@ -692,6 +692,18 @@ Before traversal, expand the question against the graph's own vocabulary so a wo --- +## For /graphify affected + +When the user asks for a change's blast radius or "what calls/depends on X?", use `graphify affected "X"` rather than a broad `query`. It reverse-traverses the graph from X and reports the callers and dependents that a change could impact. For relation/depth filters and the exact workflow, see `references/query.md`. + +--- + +## Less-common maintenance commands + +Use these only when the request calls for them: `graphify tree` writes a collapsible hierarchy view; `graphify global add|remove|list|path` manages the cross-repository graph; `graphify check-update ` is the cron-safe stale-graph check; `graphify diagnose multigraph` reports same-endpoint edge-collapse risk; and `graphify merge-driver ` is for a Git merge-driver invocation. Run `graphify --help` before supplying flags, and do not substitute these commands for the normal build/query workflow. + +--- + ## For /graphify add and --watch Neither is part of the default build. When the user runs `/graphify add ` to fetch a URL into the corpus, or passes `--watch` to auto-rebuild on file changes, see `references/add-watch.md`. diff --git a/tools/skillgen/expected/graphify__skill-droid.md b/tools/skillgen/expected/graphify__skill-droid.md index fd148d485d..9f5c291136 100644 --- a/tools/skillgen/expected/graphify__skill-droid.md +++ b/tools/skillgen/expected/graphify__skill-droid.md @@ -689,6 +689,18 @@ Before traversal, expand the question against the graph's own vocabulary so a wo --- +## For /graphify affected + +When the user asks for a change's blast radius or "what calls/depends on X?", use `graphify affected "X"` rather than a broad `query`. It reverse-traverses the graph from X and reports the callers and dependents that a change could impact. For relation/depth filters and the exact workflow, see `references/query.md`. + +--- + +## Less-common maintenance commands + +Use these only when the request calls for them: `graphify tree` writes a collapsible hierarchy view; `graphify global add|remove|list|path` manages the cross-repository graph; `graphify check-update ` is the cron-safe stale-graph check; `graphify diagnose multigraph` reports same-endpoint edge-collapse risk; and `graphify merge-driver ` is for a Git merge-driver invocation. Run `graphify --help` before supplying flags, and do not substitute these commands for the normal build/query workflow. + +--- + ## For /graphify add and --watch Neither is part of the default build. When the user runs `/graphify add ` to fetch a URL into the corpus, or passes `--watch` to auto-rebuild on file changes, see `references/add-watch.md`. diff --git a/tools/skillgen/expected/graphify__skill-kilo.md b/tools/skillgen/expected/graphify__skill-kilo.md index 3e70b050a4..514a9b88f7 100644 --- a/tools/skillgen/expected/graphify__skill-kilo.md +++ b/tools/skillgen/expected/graphify__skill-kilo.md @@ -692,6 +692,18 @@ Before traversal, expand the question against the graph's own vocabulary so a wo --- +## For /graphify affected + +When the user asks for a change's blast radius or "what calls/depends on X?", use `graphify affected "X"` rather than a broad `query`. It reverse-traverses the graph from X and reports the callers and dependents that a change could impact. For relation/depth filters and the exact workflow, see `references/query.md`. + +--- + +## Less-common maintenance commands + +Use these only when the request calls for them: `graphify tree` writes a collapsible hierarchy view; `graphify global add|remove|list|path` manages the cross-repository graph; `graphify check-update ` is the cron-safe stale-graph check; `graphify diagnose multigraph` reports same-endpoint edge-collapse risk; and `graphify merge-driver ` is for a Git merge-driver invocation. Run `graphify --help` before supplying flags, and do not substitute these commands for the normal build/query workflow. + +--- + ## For /graphify add and --watch Neither is part of the default build. When the user runs `/graphify add ` to fetch a URL into the corpus, or passes `--watch` to auto-rebuild on file changes, see `references/add-watch.md`. diff --git a/tools/skillgen/expected/graphify__skill-kiro.md b/tools/skillgen/expected/graphify__skill-kiro.md index abd2811d23..60667e3121 100644 --- a/tools/skillgen/expected/graphify__skill-kiro.md +++ b/tools/skillgen/expected/graphify__skill-kiro.md @@ -692,6 +692,18 @@ Before traversal, expand the question against the graph's own vocabulary so a wo --- +## For /graphify affected + +When the user asks for a change's blast radius or "what calls/depends on X?", use `graphify affected "X"` rather than a broad `query`. It reverse-traverses the graph from X and reports the callers and dependents that a change could impact. For relation/depth filters and the exact workflow, see `references/query.md`. + +--- + +## Less-common maintenance commands + +Use these only when the request calls for them: `graphify tree` writes a collapsible hierarchy view; `graphify global add|remove|list|path` manages the cross-repository graph; `graphify check-update ` is the cron-safe stale-graph check; `graphify diagnose multigraph` reports same-endpoint edge-collapse risk; and `graphify merge-driver ` is for a Git merge-driver invocation. Run `graphify --help` before supplying flags, and do not substitute these commands for the normal build/query workflow. + +--- + ## For /graphify add and --watch Neither is part of the default build. When the user runs `/graphify add ` to fetch a URL into the corpus, or passes `--watch` to auto-rebuild on file changes, see `references/add-watch.md`. diff --git a/tools/skillgen/expected/graphify__skill-opencode.md b/tools/skillgen/expected/graphify__skill-opencode.md index 91ced60675..f573d68b15 100644 --- a/tools/skillgen/expected/graphify__skill-opencode.md +++ b/tools/skillgen/expected/graphify__skill-opencode.md @@ -684,6 +684,18 @@ Before traversal, expand the question against the graph's own vocabulary so a wo --- +## For /graphify affected + +When the user asks for a change's blast radius or "what calls/depends on X?", use `graphify affected "X"` rather than a broad `query`. It reverse-traverses the graph from X and reports the callers and dependents that a change could impact. For relation/depth filters and the exact workflow, see `references/query.md`. + +--- + +## Less-common maintenance commands + +Use these only when the request calls for them: `graphify tree` writes a collapsible hierarchy view; `graphify global add|remove|list|path` manages the cross-repository graph; `graphify check-update ` is the cron-safe stale-graph check; `graphify diagnose multigraph` reports same-endpoint edge-collapse risk; and `graphify merge-driver ` is for a Git merge-driver invocation. Run `graphify --help` before supplying flags, and do not substitute these commands for the normal build/query workflow. + +--- + ## For /graphify add and --watch Neither is part of the default build. When the user runs `/graphify add ` to fetch a URL into the corpus, or passes `--watch` to auto-rebuild on file changes, see `references/add-watch.md`. diff --git a/tools/skillgen/expected/graphify__skill-pi.md b/tools/skillgen/expected/graphify__skill-pi.md index abd2811d23..60667e3121 100644 --- a/tools/skillgen/expected/graphify__skill-pi.md +++ b/tools/skillgen/expected/graphify__skill-pi.md @@ -692,6 +692,18 @@ Before traversal, expand the question against the graph's own vocabulary so a wo --- +## For /graphify affected + +When the user asks for a change's blast radius or "what calls/depends on X?", use `graphify affected "X"` rather than a broad `query`. It reverse-traverses the graph from X and reports the callers and dependents that a change could impact. For relation/depth filters and the exact workflow, see `references/query.md`. + +--- + +## Less-common maintenance commands + +Use these only when the request calls for them: `graphify tree` writes a collapsible hierarchy view; `graphify global add|remove|list|path` manages the cross-repository graph; `graphify check-update ` is the cron-safe stale-graph check; `graphify diagnose multigraph` reports same-endpoint edge-collapse risk; and `graphify merge-driver ` is for a Git merge-driver invocation. Run `graphify --help` before supplying flags, and do not substitute these commands for the normal build/query workflow. + +--- + ## For /graphify add and --watch Neither is part of the default build. When the user runs `/graphify add ` to fetch a URL into the corpus, or passes `--watch` to auto-rebuild on file changes, see `references/add-watch.md`. diff --git a/tools/skillgen/expected/graphify__skill-trae.md b/tools/skillgen/expected/graphify__skill-trae.md index 050667bc20..762c7d05de 100644 --- a/tools/skillgen/expected/graphify__skill-trae.md +++ b/tools/skillgen/expected/graphify__skill-trae.md @@ -690,6 +690,18 @@ Before traversal, expand the question against the graph's own vocabulary so a wo --- +## For /graphify affected + +When the user asks for a change's blast radius or "what calls/depends on X?", use `graphify affected "X"` rather than a broad `query`. It reverse-traverses the graph from X and reports the callers and dependents that a change could impact. For relation/depth filters and the exact workflow, see `references/query.md`. + +--- + +## Less-common maintenance commands + +Use these only when the request calls for them: `graphify tree` writes a collapsible hierarchy view; `graphify global add|remove|list|path` manages the cross-repository graph; `graphify check-update ` is the cron-safe stale-graph check; `graphify diagnose multigraph` reports same-endpoint edge-collapse risk; and `graphify merge-driver ` is for a Git merge-driver invocation. Run `graphify --help` before supplying flags, and do not substitute these commands for the normal build/query workflow. + +--- + ## For /graphify add and --watch Neither is part of the default build. When the user runs `/graphify add ` to fetch a URL into the corpus, or passes `--watch` to auto-rebuild on file changes, see `references/add-watch.md`. diff --git a/tools/skillgen/expected/graphify__skill-vscode.md b/tools/skillgen/expected/graphify__skill-vscode.md index 20c7c0835c..0e0df82af6 100644 --- a/tools/skillgen/expected/graphify__skill-vscode.md +++ b/tools/skillgen/expected/graphify__skill-vscode.md @@ -688,6 +688,18 @@ Before traversal, expand the question against the graph's own vocabulary so a wo --- +## For /graphify affected + +When the user asks for a change's blast radius or "what calls/depends on X?", use `graphify affected "X"` rather than a broad `query`. It reverse-traverses the graph from X and reports the callers and dependents that a change could impact. For relation/depth filters and the exact workflow, see `references/query.md`. + +--- + +## Less-common maintenance commands + +Use these only when the request calls for them: `graphify tree` writes a collapsible hierarchy view; `graphify global add|remove|list|path` manages the cross-repository graph; `graphify check-update ` is the cron-safe stale-graph check; `graphify diagnose multigraph` reports same-endpoint edge-collapse risk; and `graphify merge-driver ` is for a Git merge-driver invocation. Run `graphify --help` before supplying flags, and do not substitute these commands for the normal build/query workflow. + +--- + ## For /graphify add and --watch Neither is part of the default build. When the user runs `/graphify add ` to fetch a URL into the corpus, or passes `--watch` to auto-rebuild on file changes, see `references/add-watch.md`. diff --git a/tools/skillgen/expected/graphify__skill-windows.md b/tools/skillgen/expected/graphify__skill-windows.md index d631821ec3..a9bceaa2b6 100644 --- a/tools/skillgen/expected/graphify__skill-windows.md +++ b/tools/skillgen/expected/graphify__skill-windows.md @@ -716,6 +716,18 @@ Before traversal, expand the question against the graph's own vocabulary so a wo --- +## For /graphify affected + +When the user asks for a change's blast radius or "what calls/depends on X?", use `graphify affected "X"` rather than a broad `query`. It reverse-traverses the graph from X and reports the callers and dependents that a change could impact. For relation/depth filters and the exact workflow, see `references/query.md`. + +--- + +## Less-common maintenance commands + +Use these only when the request calls for them: `graphify tree` writes a collapsible hierarchy view; `graphify global add|remove|list|path` manages the cross-repository graph; `graphify check-update ` is the cron-safe stale-graph check; `graphify diagnose multigraph` reports same-endpoint edge-collapse risk; and `graphify merge-driver ` is for a Git merge-driver invocation. Run `graphify --help` before supplying flags, and do not substitute these commands for the normal build/query workflow. + +--- + ## For /graphify add and --watch Neither is part of the default build. When the user runs `/graphify add ` to fetch a URL into the corpus, or passes `--watch` to auto-rebuild on file changes, see `references/add-watch.md`. diff --git a/tools/skillgen/expected/graphify__skill.md b/tools/skillgen/expected/graphify__skill.md index abd2811d23..60667e3121 100644 --- a/tools/skillgen/expected/graphify__skill.md +++ b/tools/skillgen/expected/graphify__skill.md @@ -692,6 +692,18 @@ Before traversal, expand the question against the graph's own vocabulary so a wo --- +## For /graphify affected + +When the user asks for a change's blast radius or "what calls/depends on X?", use `graphify affected "X"` rather than a broad `query`. It reverse-traverses the graph from X and reports the callers and dependents that a change could impact. For relation/depth filters and the exact workflow, see `references/query.md`. + +--- + +## Less-common maintenance commands + +Use these only when the request calls for them: `graphify tree` writes a collapsible hierarchy view; `graphify global add|remove|list|path` manages the cross-repository graph; `graphify check-update ` is the cron-safe stale-graph check; `graphify diagnose multigraph` reports same-endpoint edge-collapse risk; and `graphify merge-driver ` is for a Git merge-driver invocation. Run `graphify --help` before supplying flags, and do not substitute these commands for the normal build/query workflow. + +--- + ## For /graphify add and --watch Neither is part of the default build. When the user runs `/graphify add ` to fetch a URL into the corpus, or passes `--watch` to auto-rebuild on file changes, see `references/add-watch.md`. diff --git a/tools/skillgen/expected/graphify__skills__agents__references__query.md b/tools/skillgen/expected/graphify__skills__agents__references__query.md index 56565eb782..85c6a303c6 100644 --- a/tools/skillgen/expected/graphify__skills__agents__references__query.md +++ b/tools/skillgen/expected/graphify__skills__agents__references__query.md @@ -20,6 +20,22 @@ if not Path('graphify-out/graph.json').exists(): ``` If it fails, stop and tell the user to run `/graphify ` first. +## For /graphify affected + +Use `affected` for a deterministic reverse blast-radius answer: "what calls X?", "what depends on X?", or "what could a change to X impact?". Do not replace it with a broad natural-language `query` when the user is asking that question. + +```bash +graphify affected "NODE_OR_LABEL" +``` + +The default depth is two reverse hops. Narrow the result when the user names a relationship, or widen it deliberately: + +```bash +graphify affected "NODE_OR_LABEL" --relation calls --depth 3 +``` + +Use `--graph PATH` when the graph is not at `graphify-out/graph.json`. Explain that the seed itself is the changed item; the printed nodes are the callers/dependents reached by the reverse traversal. If no nodes are found, report that the graph has no matching seed rather than inferring a negative result about the source repository. + ### Step 0 — Constrained query expansion (REQUIRED before traversal) graphify's `query` CLI matches nodes via case-folded substring + IDF — there is **no stemming, no synonyms, no cross-language match** inside the binary, and the inline fallback below matches the same way. If the user's question uses different language or different domain vocabulary than the graph's labels (user says "обработчик" / graph says "handler"; user says "authentication" / graph says "Guardian"), the literal matcher returns 0 hits and the answer collapses to noise. diff --git a/tools/skillgen/expected/graphify__skills__agents__references__update.md b/tools/skillgen/expected/graphify__skills__agents__references__update.md index 3632fd4126..4ce77933bb 100644 --- a/tools/skillgen/expected/graphify__skills__agents__references__update.md +++ b/tools/skillgen/expected/graphify__skills__agents__references__update.md @@ -208,3 +208,13 @@ graphify cluster-only . ``` `graphify cluster-only .` is **self-contained**: it re-clusters, names communities, and regenerates `GRAPH_REPORT.md`, `graph.json`, and `graph.html` from the existing graph. **Do not re-run Steps 5–9** — they read intermediate files (`.graphify_extract.json`, `.graphify_detect.json`, `.graphify_analysis.json`) that a prior build's cleanup (Step 9) already deleted, so they raise `FileNotFoundError` (#1392). When it finishes, present the refreshed `GRAPH_REPORT.md` summary as usual. + +## Verify apparently-successful maintenance runs + +Treat a zero exit code as the start of verification, not proof that the requested work happened: + +- `cluster-only` rebuilds communities; it is not the reliable way to force a new LLM naming pass when labels already exist. Run `graphify label . --backend BACKEND` to re-name communities, then inspect `GRAPH_REPORT.md`: a real labeling run has non-zero `Token cost` and labels other than `Community N`. +- `tree` writes `graphify-out/GRAPH_TREE.html`. If a hierarchy matters, inspect the generated view and ensure the chosen `--root` is the project root; a successful write alone does not prove the intended subtree was selected. +- If output says `Skipped graph.html`, `graph.json` and `GRAPH_REPORT.md` were still written. Use `--no-viz` for CI, or raise `GRAPHIFY_VIZ_NODE_LIMIT` only when the browser can handle the larger view. If writing `graph.json` itself hits the size guard, raise `GRAPHIFY_MAX_GRAPH_BYTES` (for example `700MB`) deliberately. +- A warning that `.sql` or `.tf` files produced zero nodes means that language is absent from the graph. Install the matching extra and rerun: `uv tool install "graphifyy[sql]"` or `uv tool install "graphifyy[terraform]"`. +- The `openai` backend requires `uv tool install "graphifyy[openai]"`. For an OpenAI-compatible gateway, set `OPENAI_BASE_URL` and `OPENAI_MODEL` and pass `--backend openai`. diff --git a/tools/skillgen/expected/graphify__skills__amp__references__query.md b/tools/skillgen/expected/graphify__skills__amp__references__query.md index 56565eb782..85c6a303c6 100644 --- a/tools/skillgen/expected/graphify__skills__amp__references__query.md +++ b/tools/skillgen/expected/graphify__skills__amp__references__query.md @@ -20,6 +20,22 @@ if not Path('graphify-out/graph.json').exists(): ``` If it fails, stop and tell the user to run `/graphify ` first. +## For /graphify affected + +Use `affected` for a deterministic reverse blast-radius answer: "what calls X?", "what depends on X?", or "what could a change to X impact?". Do not replace it with a broad natural-language `query` when the user is asking that question. + +```bash +graphify affected "NODE_OR_LABEL" +``` + +The default depth is two reverse hops. Narrow the result when the user names a relationship, or widen it deliberately: + +```bash +graphify affected "NODE_OR_LABEL" --relation calls --depth 3 +``` + +Use `--graph PATH` when the graph is not at `graphify-out/graph.json`. Explain that the seed itself is the changed item; the printed nodes are the callers/dependents reached by the reverse traversal. If no nodes are found, report that the graph has no matching seed rather than inferring a negative result about the source repository. + ### Step 0 — Constrained query expansion (REQUIRED before traversal) graphify's `query` CLI matches nodes via case-folded substring + IDF — there is **no stemming, no synonyms, no cross-language match** inside the binary, and the inline fallback below matches the same way. If the user's question uses different language or different domain vocabulary than the graph's labels (user says "обработчик" / graph says "handler"; user says "authentication" / graph says "Guardian"), the literal matcher returns 0 hits and the answer collapses to noise. diff --git a/tools/skillgen/expected/graphify__skills__amp__references__update.md b/tools/skillgen/expected/graphify__skills__amp__references__update.md index 3632fd4126..4ce77933bb 100644 --- a/tools/skillgen/expected/graphify__skills__amp__references__update.md +++ b/tools/skillgen/expected/graphify__skills__amp__references__update.md @@ -208,3 +208,13 @@ graphify cluster-only . ``` `graphify cluster-only .` is **self-contained**: it re-clusters, names communities, and regenerates `GRAPH_REPORT.md`, `graph.json`, and `graph.html` from the existing graph. **Do not re-run Steps 5–9** — they read intermediate files (`.graphify_extract.json`, `.graphify_detect.json`, `.graphify_analysis.json`) that a prior build's cleanup (Step 9) already deleted, so they raise `FileNotFoundError` (#1392). When it finishes, present the refreshed `GRAPH_REPORT.md` summary as usual. + +## Verify apparently-successful maintenance runs + +Treat a zero exit code as the start of verification, not proof that the requested work happened: + +- `cluster-only` rebuilds communities; it is not the reliable way to force a new LLM naming pass when labels already exist. Run `graphify label . --backend BACKEND` to re-name communities, then inspect `GRAPH_REPORT.md`: a real labeling run has non-zero `Token cost` and labels other than `Community N`. +- `tree` writes `graphify-out/GRAPH_TREE.html`. If a hierarchy matters, inspect the generated view and ensure the chosen `--root` is the project root; a successful write alone does not prove the intended subtree was selected. +- If output says `Skipped graph.html`, `graph.json` and `GRAPH_REPORT.md` were still written. Use `--no-viz` for CI, or raise `GRAPHIFY_VIZ_NODE_LIMIT` only when the browser can handle the larger view. If writing `graph.json` itself hits the size guard, raise `GRAPHIFY_MAX_GRAPH_BYTES` (for example `700MB`) deliberately. +- A warning that `.sql` or `.tf` files produced zero nodes means that language is absent from the graph. Install the matching extra and rerun: `uv tool install "graphifyy[sql]"` or `uv tool install "graphifyy[terraform]"`. +- The `openai` backend requires `uv tool install "graphifyy[openai]"`. For an OpenAI-compatible gateway, set `OPENAI_BASE_URL` and `OPENAI_MODEL` and pass `--backend openai`. diff --git a/tools/skillgen/expected/graphify__skills__claude__references__query.md b/tools/skillgen/expected/graphify__skills__claude__references__query.md index 56565eb782..85c6a303c6 100644 --- a/tools/skillgen/expected/graphify__skills__claude__references__query.md +++ b/tools/skillgen/expected/graphify__skills__claude__references__query.md @@ -20,6 +20,22 @@ if not Path('graphify-out/graph.json').exists(): ``` If it fails, stop and tell the user to run `/graphify ` first. +## For /graphify affected + +Use `affected` for a deterministic reverse blast-radius answer: "what calls X?", "what depends on X?", or "what could a change to X impact?". Do not replace it with a broad natural-language `query` when the user is asking that question. + +```bash +graphify affected "NODE_OR_LABEL" +``` + +The default depth is two reverse hops. Narrow the result when the user names a relationship, or widen it deliberately: + +```bash +graphify affected "NODE_OR_LABEL" --relation calls --depth 3 +``` + +Use `--graph PATH` when the graph is not at `graphify-out/graph.json`. Explain that the seed itself is the changed item; the printed nodes are the callers/dependents reached by the reverse traversal. If no nodes are found, report that the graph has no matching seed rather than inferring a negative result about the source repository. + ### Step 0 — Constrained query expansion (REQUIRED before traversal) graphify's `query` CLI matches nodes via case-folded substring + IDF — there is **no stemming, no synonyms, no cross-language match** inside the binary, and the inline fallback below matches the same way. If the user's question uses different language or different domain vocabulary than the graph's labels (user says "обработчик" / graph says "handler"; user says "authentication" / graph says "Guardian"), the literal matcher returns 0 hits and the answer collapses to noise. diff --git a/tools/skillgen/expected/graphify__skills__claude__references__update.md b/tools/skillgen/expected/graphify__skills__claude__references__update.md index 3632fd4126..4ce77933bb 100644 --- a/tools/skillgen/expected/graphify__skills__claude__references__update.md +++ b/tools/skillgen/expected/graphify__skills__claude__references__update.md @@ -208,3 +208,13 @@ graphify cluster-only . ``` `graphify cluster-only .` is **self-contained**: it re-clusters, names communities, and regenerates `GRAPH_REPORT.md`, `graph.json`, and `graph.html` from the existing graph. **Do not re-run Steps 5–9** — they read intermediate files (`.graphify_extract.json`, `.graphify_detect.json`, `.graphify_analysis.json`) that a prior build's cleanup (Step 9) already deleted, so they raise `FileNotFoundError` (#1392). When it finishes, present the refreshed `GRAPH_REPORT.md` summary as usual. + +## Verify apparently-successful maintenance runs + +Treat a zero exit code as the start of verification, not proof that the requested work happened: + +- `cluster-only` rebuilds communities; it is not the reliable way to force a new LLM naming pass when labels already exist. Run `graphify label . --backend BACKEND` to re-name communities, then inspect `GRAPH_REPORT.md`: a real labeling run has non-zero `Token cost` and labels other than `Community N`. +- `tree` writes `graphify-out/GRAPH_TREE.html`. If a hierarchy matters, inspect the generated view and ensure the chosen `--root` is the project root; a successful write alone does not prove the intended subtree was selected. +- If output says `Skipped graph.html`, `graph.json` and `GRAPH_REPORT.md` were still written. Use `--no-viz` for CI, or raise `GRAPHIFY_VIZ_NODE_LIMIT` only when the browser can handle the larger view. If writing `graph.json` itself hits the size guard, raise `GRAPHIFY_MAX_GRAPH_BYTES` (for example `700MB`) deliberately. +- A warning that `.sql` or `.tf` files produced zero nodes means that language is absent from the graph. Install the matching extra and rerun: `uv tool install "graphifyy[sql]"` or `uv tool install "graphifyy[terraform]"`. +- The `openai` backend requires `uv tool install "graphifyy[openai]"`. For an OpenAI-compatible gateway, set `OPENAI_BASE_URL` and `OPENAI_MODEL` and pass `--backend openai`. diff --git a/tools/skillgen/expected/graphify__skills__claw__references__query.md b/tools/skillgen/expected/graphify__skills__claw__references__query.md index 56565eb782..85c6a303c6 100644 --- a/tools/skillgen/expected/graphify__skills__claw__references__query.md +++ b/tools/skillgen/expected/graphify__skills__claw__references__query.md @@ -20,6 +20,22 @@ if not Path('graphify-out/graph.json').exists(): ``` If it fails, stop and tell the user to run `/graphify ` first. +## For /graphify affected + +Use `affected` for a deterministic reverse blast-radius answer: "what calls X?", "what depends on X?", or "what could a change to X impact?". Do not replace it with a broad natural-language `query` when the user is asking that question. + +```bash +graphify affected "NODE_OR_LABEL" +``` + +The default depth is two reverse hops. Narrow the result when the user names a relationship, or widen it deliberately: + +```bash +graphify affected "NODE_OR_LABEL" --relation calls --depth 3 +``` + +Use `--graph PATH` when the graph is not at `graphify-out/graph.json`. Explain that the seed itself is the changed item; the printed nodes are the callers/dependents reached by the reverse traversal. If no nodes are found, report that the graph has no matching seed rather than inferring a negative result about the source repository. + ### Step 0 — Constrained query expansion (REQUIRED before traversal) graphify's `query` CLI matches nodes via case-folded substring + IDF — there is **no stemming, no synonyms, no cross-language match** inside the binary, and the inline fallback below matches the same way. If the user's question uses different language or different domain vocabulary than the graph's labels (user says "обработчик" / graph says "handler"; user says "authentication" / graph says "Guardian"), the literal matcher returns 0 hits and the answer collapses to noise. diff --git a/tools/skillgen/expected/graphify__skills__claw__references__update.md b/tools/skillgen/expected/graphify__skills__claw__references__update.md index 3632fd4126..4ce77933bb 100644 --- a/tools/skillgen/expected/graphify__skills__claw__references__update.md +++ b/tools/skillgen/expected/graphify__skills__claw__references__update.md @@ -208,3 +208,13 @@ graphify cluster-only . ``` `graphify cluster-only .` is **self-contained**: it re-clusters, names communities, and regenerates `GRAPH_REPORT.md`, `graph.json`, and `graph.html` from the existing graph. **Do not re-run Steps 5–9** — they read intermediate files (`.graphify_extract.json`, `.graphify_detect.json`, `.graphify_analysis.json`) that a prior build's cleanup (Step 9) already deleted, so they raise `FileNotFoundError` (#1392). When it finishes, present the refreshed `GRAPH_REPORT.md` summary as usual. + +## Verify apparently-successful maintenance runs + +Treat a zero exit code as the start of verification, not proof that the requested work happened: + +- `cluster-only` rebuilds communities; it is not the reliable way to force a new LLM naming pass when labels already exist. Run `graphify label . --backend BACKEND` to re-name communities, then inspect `GRAPH_REPORT.md`: a real labeling run has non-zero `Token cost` and labels other than `Community N`. +- `tree` writes `graphify-out/GRAPH_TREE.html`. If a hierarchy matters, inspect the generated view and ensure the chosen `--root` is the project root; a successful write alone does not prove the intended subtree was selected. +- If output says `Skipped graph.html`, `graph.json` and `GRAPH_REPORT.md` were still written. Use `--no-viz` for CI, or raise `GRAPHIFY_VIZ_NODE_LIMIT` only when the browser can handle the larger view. If writing `graph.json` itself hits the size guard, raise `GRAPHIFY_MAX_GRAPH_BYTES` (for example `700MB`) deliberately. +- A warning that `.sql` or `.tf` files produced zero nodes means that language is absent from the graph. Install the matching extra and rerun: `uv tool install "graphifyy[sql]"` or `uv tool install "graphifyy[terraform]"`. +- The `openai` backend requires `uv tool install "graphifyy[openai]"`. For an OpenAI-compatible gateway, set `OPENAI_BASE_URL` and `OPENAI_MODEL` and pass `--backend openai`. diff --git a/tools/skillgen/expected/graphify__skills__codex__references__query.md b/tools/skillgen/expected/graphify__skills__codex__references__query.md index 56565eb782..85c6a303c6 100644 --- a/tools/skillgen/expected/graphify__skills__codex__references__query.md +++ b/tools/skillgen/expected/graphify__skills__codex__references__query.md @@ -20,6 +20,22 @@ if not Path('graphify-out/graph.json').exists(): ``` If it fails, stop and tell the user to run `/graphify ` first. +## For /graphify affected + +Use `affected` for a deterministic reverse blast-radius answer: "what calls X?", "what depends on X?", or "what could a change to X impact?". Do not replace it with a broad natural-language `query` when the user is asking that question. + +```bash +graphify affected "NODE_OR_LABEL" +``` + +The default depth is two reverse hops. Narrow the result when the user names a relationship, or widen it deliberately: + +```bash +graphify affected "NODE_OR_LABEL" --relation calls --depth 3 +``` + +Use `--graph PATH` when the graph is not at `graphify-out/graph.json`. Explain that the seed itself is the changed item; the printed nodes are the callers/dependents reached by the reverse traversal. If no nodes are found, report that the graph has no matching seed rather than inferring a negative result about the source repository. + ### Step 0 — Constrained query expansion (REQUIRED before traversal) graphify's `query` CLI matches nodes via case-folded substring + IDF — there is **no stemming, no synonyms, no cross-language match** inside the binary, and the inline fallback below matches the same way. If the user's question uses different language or different domain vocabulary than the graph's labels (user says "обработчик" / graph says "handler"; user says "authentication" / graph says "Guardian"), the literal matcher returns 0 hits and the answer collapses to noise. diff --git a/tools/skillgen/expected/graphify__skills__codex__references__update.md b/tools/skillgen/expected/graphify__skills__codex__references__update.md index 3632fd4126..4ce77933bb 100644 --- a/tools/skillgen/expected/graphify__skills__codex__references__update.md +++ b/tools/skillgen/expected/graphify__skills__codex__references__update.md @@ -208,3 +208,13 @@ graphify cluster-only . ``` `graphify cluster-only .` is **self-contained**: it re-clusters, names communities, and regenerates `GRAPH_REPORT.md`, `graph.json`, and `graph.html` from the existing graph. **Do not re-run Steps 5–9** — they read intermediate files (`.graphify_extract.json`, `.graphify_detect.json`, `.graphify_analysis.json`) that a prior build's cleanup (Step 9) already deleted, so they raise `FileNotFoundError` (#1392). When it finishes, present the refreshed `GRAPH_REPORT.md` summary as usual. + +## Verify apparently-successful maintenance runs + +Treat a zero exit code as the start of verification, not proof that the requested work happened: + +- `cluster-only` rebuilds communities; it is not the reliable way to force a new LLM naming pass when labels already exist. Run `graphify label . --backend BACKEND` to re-name communities, then inspect `GRAPH_REPORT.md`: a real labeling run has non-zero `Token cost` and labels other than `Community N`. +- `tree` writes `graphify-out/GRAPH_TREE.html`. If a hierarchy matters, inspect the generated view and ensure the chosen `--root` is the project root; a successful write alone does not prove the intended subtree was selected. +- If output says `Skipped graph.html`, `graph.json` and `GRAPH_REPORT.md` were still written. Use `--no-viz` for CI, or raise `GRAPHIFY_VIZ_NODE_LIMIT` only when the browser can handle the larger view. If writing `graph.json` itself hits the size guard, raise `GRAPHIFY_MAX_GRAPH_BYTES` (for example `700MB`) deliberately. +- A warning that `.sql` or `.tf` files produced zero nodes means that language is absent from the graph. Install the matching extra and rerun: `uv tool install "graphifyy[sql]"` or `uv tool install "graphifyy[terraform]"`. +- The `openai` backend requires `uv tool install "graphifyy[openai]"`. For an OpenAI-compatible gateway, set `OPENAI_BASE_URL` and `OPENAI_MODEL` and pass `--backend openai`. diff --git a/tools/skillgen/expected/graphify__skills__copilot__references__query.md b/tools/skillgen/expected/graphify__skills__copilot__references__query.md index 56565eb782..85c6a303c6 100644 --- a/tools/skillgen/expected/graphify__skills__copilot__references__query.md +++ b/tools/skillgen/expected/graphify__skills__copilot__references__query.md @@ -20,6 +20,22 @@ if not Path('graphify-out/graph.json').exists(): ``` If it fails, stop and tell the user to run `/graphify ` first. +## For /graphify affected + +Use `affected` for a deterministic reverse blast-radius answer: "what calls X?", "what depends on X?", or "what could a change to X impact?". Do not replace it with a broad natural-language `query` when the user is asking that question. + +```bash +graphify affected "NODE_OR_LABEL" +``` + +The default depth is two reverse hops. Narrow the result when the user names a relationship, or widen it deliberately: + +```bash +graphify affected "NODE_OR_LABEL" --relation calls --depth 3 +``` + +Use `--graph PATH` when the graph is not at `graphify-out/graph.json`. Explain that the seed itself is the changed item; the printed nodes are the callers/dependents reached by the reverse traversal. If no nodes are found, report that the graph has no matching seed rather than inferring a negative result about the source repository. + ### Step 0 — Constrained query expansion (REQUIRED before traversal) graphify's `query` CLI matches nodes via case-folded substring + IDF — there is **no stemming, no synonyms, no cross-language match** inside the binary, and the inline fallback below matches the same way. If the user's question uses different language or different domain vocabulary than the graph's labels (user says "обработчик" / graph says "handler"; user says "authentication" / graph says "Guardian"), the literal matcher returns 0 hits and the answer collapses to noise. diff --git a/tools/skillgen/expected/graphify__skills__copilot__references__update.md b/tools/skillgen/expected/graphify__skills__copilot__references__update.md index 3632fd4126..4ce77933bb 100644 --- a/tools/skillgen/expected/graphify__skills__copilot__references__update.md +++ b/tools/skillgen/expected/graphify__skills__copilot__references__update.md @@ -208,3 +208,13 @@ graphify cluster-only . ``` `graphify cluster-only .` is **self-contained**: it re-clusters, names communities, and regenerates `GRAPH_REPORT.md`, `graph.json`, and `graph.html` from the existing graph. **Do not re-run Steps 5–9** — they read intermediate files (`.graphify_extract.json`, `.graphify_detect.json`, `.graphify_analysis.json`) that a prior build's cleanup (Step 9) already deleted, so they raise `FileNotFoundError` (#1392). When it finishes, present the refreshed `GRAPH_REPORT.md` summary as usual. + +## Verify apparently-successful maintenance runs + +Treat a zero exit code as the start of verification, not proof that the requested work happened: + +- `cluster-only` rebuilds communities; it is not the reliable way to force a new LLM naming pass when labels already exist. Run `graphify label . --backend BACKEND` to re-name communities, then inspect `GRAPH_REPORT.md`: a real labeling run has non-zero `Token cost` and labels other than `Community N`. +- `tree` writes `graphify-out/GRAPH_TREE.html`. If a hierarchy matters, inspect the generated view and ensure the chosen `--root` is the project root; a successful write alone does not prove the intended subtree was selected. +- If output says `Skipped graph.html`, `graph.json` and `GRAPH_REPORT.md` were still written. Use `--no-viz` for CI, or raise `GRAPHIFY_VIZ_NODE_LIMIT` only when the browser can handle the larger view. If writing `graph.json` itself hits the size guard, raise `GRAPHIFY_MAX_GRAPH_BYTES` (for example `700MB`) deliberately. +- A warning that `.sql` or `.tf` files produced zero nodes means that language is absent from the graph. Install the matching extra and rerun: `uv tool install "graphifyy[sql]"` or `uv tool install "graphifyy[terraform]"`. +- The `openai` backend requires `uv tool install "graphifyy[openai]"`. For an OpenAI-compatible gateway, set `OPENAI_BASE_URL` and `OPENAI_MODEL` and pass `--backend openai`. diff --git a/tools/skillgen/expected/graphify__skills__droid__references__query.md b/tools/skillgen/expected/graphify__skills__droid__references__query.md index 56565eb782..85c6a303c6 100644 --- a/tools/skillgen/expected/graphify__skills__droid__references__query.md +++ b/tools/skillgen/expected/graphify__skills__droid__references__query.md @@ -20,6 +20,22 @@ if not Path('graphify-out/graph.json').exists(): ``` If it fails, stop and tell the user to run `/graphify ` first. +## For /graphify affected + +Use `affected` for a deterministic reverse blast-radius answer: "what calls X?", "what depends on X?", or "what could a change to X impact?". Do not replace it with a broad natural-language `query` when the user is asking that question. + +```bash +graphify affected "NODE_OR_LABEL" +``` + +The default depth is two reverse hops. Narrow the result when the user names a relationship, or widen it deliberately: + +```bash +graphify affected "NODE_OR_LABEL" --relation calls --depth 3 +``` + +Use `--graph PATH` when the graph is not at `graphify-out/graph.json`. Explain that the seed itself is the changed item; the printed nodes are the callers/dependents reached by the reverse traversal. If no nodes are found, report that the graph has no matching seed rather than inferring a negative result about the source repository. + ### Step 0 — Constrained query expansion (REQUIRED before traversal) graphify's `query` CLI matches nodes via case-folded substring + IDF — there is **no stemming, no synonyms, no cross-language match** inside the binary, and the inline fallback below matches the same way. If the user's question uses different language or different domain vocabulary than the graph's labels (user says "обработчик" / graph says "handler"; user says "authentication" / graph says "Guardian"), the literal matcher returns 0 hits and the answer collapses to noise. diff --git a/tools/skillgen/expected/graphify__skills__droid__references__update.md b/tools/skillgen/expected/graphify__skills__droid__references__update.md index 3632fd4126..4ce77933bb 100644 --- a/tools/skillgen/expected/graphify__skills__droid__references__update.md +++ b/tools/skillgen/expected/graphify__skills__droid__references__update.md @@ -208,3 +208,13 @@ graphify cluster-only . ``` `graphify cluster-only .` is **self-contained**: it re-clusters, names communities, and regenerates `GRAPH_REPORT.md`, `graph.json`, and `graph.html` from the existing graph. **Do not re-run Steps 5–9** — they read intermediate files (`.graphify_extract.json`, `.graphify_detect.json`, `.graphify_analysis.json`) that a prior build's cleanup (Step 9) already deleted, so they raise `FileNotFoundError` (#1392). When it finishes, present the refreshed `GRAPH_REPORT.md` summary as usual. + +## Verify apparently-successful maintenance runs + +Treat a zero exit code as the start of verification, not proof that the requested work happened: + +- `cluster-only` rebuilds communities; it is not the reliable way to force a new LLM naming pass when labels already exist. Run `graphify label . --backend BACKEND` to re-name communities, then inspect `GRAPH_REPORT.md`: a real labeling run has non-zero `Token cost` and labels other than `Community N`. +- `tree` writes `graphify-out/GRAPH_TREE.html`. If a hierarchy matters, inspect the generated view and ensure the chosen `--root` is the project root; a successful write alone does not prove the intended subtree was selected. +- If output says `Skipped graph.html`, `graph.json` and `GRAPH_REPORT.md` were still written. Use `--no-viz` for CI, or raise `GRAPHIFY_VIZ_NODE_LIMIT` only when the browser can handle the larger view. If writing `graph.json` itself hits the size guard, raise `GRAPHIFY_MAX_GRAPH_BYTES` (for example `700MB`) deliberately. +- A warning that `.sql` or `.tf` files produced zero nodes means that language is absent from the graph. Install the matching extra and rerun: `uv tool install "graphifyy[sql]"` or `uv tool install "graphifyy[terraform]"`. +- The `openai` backend requires `uv tool install "graphifyy[openai]"`. For an OpenAI-compatible gateway, set `OPENAI_BASE_URL` and `OPENAI_MODEL` and pass `--backend openai`. diff --git a/tools/skillgen/expected/graphify__skills__kilo__references__query.md b/tools/skillgen/expected/graphify__skills__kilo__references__query.md index 56565eb782..85c6a303c6 100644 --- a/tools/skillgen/expected/graphify__skills__kilo__references__query.md +++ b/tools/skillgen/expected/graphify__skills__kilo__references__query.md @@ -20,6 +20,22 @@ if not Path('graphify-out/graph.json').exists(): ``` If it fails, stop and tell the user to run `/graphify ` first. +## For /graphify affected + +Use `affected` for a deterministic reverse blast-radius answer: "what calls X?", "what depends on X?", or "what could a change to X impact?". Do not replace it with a broad natural-language `query` when the user is asking that question. + +```bash +graphify affected "NODE_OR_LABEL" +``` + +The default depth is two reverse hops. Narrow the result when the user names a relationship, or widen it deliberately: + +```bash +graphify affected "NODE_OR_LABEL" --relation calls --depth 3 +``` + +Use `--graph PATH` when the graph is not at `graphify-out/graph.json`. Explain that the seed itself is the changed item; the printed nodes are the callers/dependents reached by the reverse traversal. If no nodes are found, report that the graph has no matching seed rather than inferring a negative result about the source repository. + ### Step 0 — Constrained query expansion (REQUIRED before traversal) graphify's `query` CLI matches nodes via case-folded substring + IDF — there is **no stemming, no synonyms, no cross-language match** inside the binary, and the inline fallback below matches the same way. If the user's question uses different language or different domain vocabulary than the graph's labels (user says "обработчик" / graph says "handler"; user says "authentication" / graph says "Guardian"), the literal matcher returns 0 hits and the answer collapses to noise. diff --git a/tools/skillgen/expected/graphify__skills__kilo__references__update.md b/tools/skillgen/expected/graphify__skills__kilo__references__update.md index 3632fd4126..4ce77933bb 100644 --- a/tools/skillgen/expected/graphify__skills__kilo__references__update.md +++ b/tools/skillgen/expected/graphify__skills__kilo__references__update.md @@ -208,3 +208,13 @@ graphify cluster-only . ``` `graphify cluster-only .` is **self-contained**: it re-clusters, names communities, and regenerates `GRAPH_REPORT.md`, `graph.json`, and `graph.html` from the existing graph. **Do not re-run Steps 5–9** — they read intermediate files (`.graphify_extract.json`, `.graphify_detect.json`, `.graphify_analysis.json`) that a prior build's cleanup (Step 9) already deleted, so they raise `FileNotFoundError` (#1392). When it finishes, present the refreshed `GRAPH_REPORT.md` summary as usual. + +## Verify apparently-successful maintenance runs + +Treat a zero exit code as the start of verification, not proof that the requested work happened: + +- `cluster-only` rebuilds communities; it is not the reliable way to force a new LLM naming pass when labels already exist. Run `graphify label . --backend BACKEND` to re-name communities, then inspect `GRAPH_REPORT.md`: a real labeling run has non-zero `Token cost` and labels other than `Community N`. +- `tree` writes `graphify-out/GRAPH_TREE.html`. If a hierarchy matters, inspect the generated view and ensure the chosen `--root` is the project root; a successful write alone does not prove the intended subtree was selected. +- If output says `Skipped graph.html`, `graph.json` and `GRAPH_REPORT.md` were still written. Use `--no-viz` for CI, or raise `GRAPHIFY_VIZ_NODE_LIMIT` only when the browser can handle the larger view. If writing `graph.json` itself hits the size guard, raise `GRAPHIFY_MAX_GRAPH_BYTES` (for example `700MB`) deliberately. +- A warning that `.sql` or `.tf` files produced zero nodes means that language is absent from the graph. Install the matching extra and rerun: `uv tool install "graphifyy[sql]"` or `uv tool install "graphifyy[terraform]"`. +- The `openai` backend requires `uv tool install "graphifyy[openai]"`. For an OpenAI-compatible gateway, set `OPENAI_BASE_URL` and `OPENAI_MODEL` and pass `--backend openai`. diff --git a/tools/skillgen/expected/graphify__skills__kiro__references__query.md b/tools/skillgen/expected/graphify__skills__kiro__references__query.md index 56565eb782..85c6a303c6 100644 --- a/tools/skillgen/expected/graphify__skills__kiro__references__query.md +++ b/tools/skillgen/expected/graphify__skills__kiro__references__query.md @@ -20,6 +20,22 @@ if not Path('graphify-out/graph.json').exists(): ``` If it fails, stop and tell the user to run `/graphify ` first. +## For /graphify affected + +Use `affected` for a deterministic reverse blast-radius answer: "what calls X?", "what depends on X?", or "what could a change to X impact?". Do not replace it with a broad natural-language `query` when the user is asking that question. + +```bash +graphify affected "NODE_OR_LABEL" +``` + +The default depth is two reverse hops. Narrow the result when the user names a relationship, or widen it deliberately: + +```bash +graphify affected "NODE_OR_LABEL" --relation calls --depth 3 +``` + +Use `--graph PATH` when the graph is not at `graphify-out/graph.json`. Explain that the seed itself is the changed item; the printed nodes are the callers/dependents reached by the reverse traversal. If no nodes are found, report that the graph has no matching seed rather than inferring a negative result about the source repository. + ### Step 0 — Constrained query expansion (REQUIRED before traversal) graphify's `query` CLI matches nodes via case-folded substring + IDF — there is **no stemming, no synonyms, no cross-language match** inside the binary, and the inline fallback below matches the same way. If the user's question uses different language or different domain vocabulary than the graph's labels (user says "обработчик" / graph says "handler"; user says "authentication" / graph says "Guardian"), the literal matcher returns 0 hits and the answer collapses to noise. diff --git a/tools/skillgen/expected/graphify__skills__kiro__references__update.md b/tools/skillgen/expected/graphify__skills__kiro__references__update.md index 3632fd4126..4ce77933bb 100644 --- a/tools/skillgen/expected/graphify__skills__kiro__references__update.md +++ b/tools/skillgen/expected/graphify__skills__kiro__references__update.md @@ -208,3 +208,13 @@ graphify cluster-only . ``` `graphify cluster-only .` is **self-contained**: it re-clusters, names communities, and regenerates `GRAPH_REPORT.md`, `graph.json`, and `graph.html` from the existing graph. **Do not re-run Steps 5–9** — they read intermediate files (`.graphify_extract.json`, `.graphify_detect.json`, `.graphify_analysis.json`) that a prior build's cleanup (Step 9) already deleted, so they raise `FileNotFoundError` (#1392). When it finishes, present the refreshed `GRAPH_REPORT.md` summary as usual. + +## Verify apparently-successful maintenance runs + +Treat a zero exit code as the start of verification, not proof that the requested work happened: + +- `cluster-only` rebuilds communities; it is not the reliable way to force a new LLM naming pass when labels already exist. Run `graphify label . --backend BACKEND` to re-name communities, then inspect `GRAPH_REPORT.md`: a real labeling run has non-zero `Token cost` and labels other than `Community N`. +- `tree` writes `graphify-out/GRAPH_TREE.html`. If a hierarchy matters, inspect the generated view and ensure the chosen `--root` is the project root; a successful write alone does not prove the intended subtree was selected. +- If output says `Skipped graph.html`, `graph.json` and `GRAPH_REPORT.md` were still written. Use `--no-viz` for CI, or raise `GRAPHIFY_VIZ_NODE_LIMIT` only when the browser can handle the larger view. If writing `graph.json` itself hits the size guard, raise `GRAPHIFY_MAX_GRAPH_BYTES` (for example `700MB`) deliberately. +- A warning that `.sql` or `.tf` files produced zero nodes means that language is absent from the graph. Install the matching extra and rerun: `uv tool install "graphifyy[sql]"` or `uv tool install "graphifyy[terraform]"`. +- The `openai` backend requires `uv tool install "graphifyy[openai]"`. For an OpenAI-compatible gateway, set `OPENAI_BASE_URL` and `OPENAI_MODEL` and pass `--backend openai`. diff --git a/tools/skillgen/expected/graphify__skills__opencode__references__query.md b/tools/skillgen/expected/graphify__skills__opencode__references__query.md index 56565eb782..85c6a303c6 100644 --- a/tools/skillgen/expected/graphify__skills__opencode__references__query.md +++ b/tools/skillgen/expected/graphify__skills__opencode__references__query.md @@ -20,6 +20,22 @@ if not Path('graphify-out/graph.json').exists(): ``` If it fails, stop and tell the user to run `/graphify ` first. +## For /graphify affected + +Use `affected` for a deterministic reverse blast-radius answer: "what calls X?", "what depends on X?", or "what could a change to X impact?". Do not replace it with a broad natural-language `query` when the user is asking that question. + +```bash +graphify affected "NODE_OR_LABEL" +``` + +The default depth is two reverse hops. Narrow the result when the user names a relationship, or widen it deliberately: + +```bash +graphify affected "NODE_OR_LABEL" --relation calls --depth 3 +``` + +Use `--graph PATH` when the graph is not at `graphify-out/graph.json`. Explain that the seed itself is the changed item; the printed nodes are the callers/dependents reached by the reverse traversal. If no nodes are found, report that the graph has no matching seed rather than inferring a negative result about the source repository. + ### Step 0 — Constrained query expansion (REQUIRED before traversal) graphify's `query` CLI matches nodes via case-folded substring + IDF — there is **no stemming, no synonyms, no cross-language match** inside the binary, and the inline fallback below matches the same way. If the user's question uses different language or different domain vocabulary than the graph's labels (user says "обработчик" / graph says "handler"; user says "authentication" / graph says "Guardian"), the literal matcher returns 0 hits and the answer collapses to noise. diff --git a/tools/skillgen/expected/graphify__skills__opencode__references__update.md b/tools/skillgen/expected/graphify__skills__opencode__references__update.md index 3632fd4126..4ce77933bb 100644 --- a/tools/skillgen/expected/graphify__skills__opencode__references__update.md +++ b/tools/skillgen/expected/graphify__skills__opencode__references__update.md @@ -208,3 +208,13 @@ graphify cluster-only . ``` `graphify cluster-only .` is **self-contained**: it re-clusters, names communities, and regenerates `GRAPH_REPORT.md`, `graph.json`, and `graph.html` from the existing graph. **Do not re-run Steps 5–9** — they read intermediate files (`.graphify_extract.json`, `.graphify_detect.json`, `.graphify_analysis.json`) that a prior build's cleanup (Step 9) already deleted, so they raise `FileNotFoundError` (#1392). When it finishes, present the refreshed `GRAPH_REPORT.md` summary as usual. + +## Verify apparently-successful maintenance runs + +Treat a zero exit code as the start of verification, not proof that the requested work happened: + +- `cluster-only` rebuilds communities; it is not the reliable way to force a new LLM naming pass when labels already exist. Run `graphify label . --backend BACKEND` to re-name communities, then inspect `GRAPH_REPORT.md`: a real labeling run has non-zero `Token cost` and labels other than `Community N`. +- `tree` writes `graphify-out/GRAPH_TREE.html`. If a hierarchy matters, inspect the generated view and ensure the chosen `--root` is the project root; a successful write alone does not prove the intended subtree was selected. +- If output says `Skipped graph.html`, `graph.json` and `GRAPH_REPORT.md` were still written. Use `--no-viz` for CI, or raise `GRAPHIFY_VIZ_NODE_LIMIT` only when the browser can handle the larger view. If writing `graph.json` itself hits the size guard, raise `GRAPHIFY_MAX_GRAPH_BYTES` (for example `700MB`) deliberately. +- A warning that `.sql` or `.tf` files produced zero nodes means that language is absent from the graph. Install the matching extra and rerun: `uv tool install "graphifyy[sql]"` or `uv tool install "graphifyy[terraform]"`. +- The `openai` backend requires `uv tool install "graphifyy[openai]"`. For an OpenAI-compatible gateway, set `OPENAI_BASE_URL` and `OPENAI_MODEL` and pass `--backend openai`. diff --git a/tools/skillgen/expected/graphify__skills__pi__references__query.md b/tools/skillgen/expected/graphify__skills__pi__references__query.md index 56565eb782..85c6a303c6 100644 --- a/tools/skillgen/expected/graphify__skills__pi__references__query.md +++ b/tools/skillgen/expected/graphify__skills__pi__references__query.md @@ -20,6 +20,22 @@ if not Path('graphify-out/graph.json').exists(): ``` If it fails, stop and tell the user to run `/graphify ` first. +## For /graphify affected + +Use `affected` for a deterministic reverse blast-radius answer: "what calls X?", "what depends on X?", or "what could a change to X impact?". Do not replace it with a broad natural-language `query` when the user is asking that question. + +```bash +graphify affected "NODE_OR_LABEL" +``` + +The default depth is two reverse hops. Narrow the result when the user names a relationship, or widen it deliberately: + +```bash +graphify affected "NODE_OR_LABEL" --relation calls --depth 3 +``` + +Use `--graph PATH` when the graph is not at `graphify-out/graph.json`. Explain that the seed itself is the changed item; the printed nodes are the callers/dependents reached by the reverse traversal. If no nodes are found, report that the graph has no matching seed rather than inferring a negative result about the source repository. + ### Step 0 — Constrained query expansion (REQUIRED before traversal) graphify's `query` CLI matches nodes via case-folded substring + IDF — there is **no stemming, no synonyms, no cross-language match** inside the binary, and the inline fallback below matches the same way. If the user's question uses different language or different domain vocabulary than the graph's labels (user says "обработчик" / graph says "handler"; user says "authentication" / graph says "Guardian"), the literal matcher returns 0 hits and the answer collapses to noise. diff --git a/tools/skillgen/expected/graphify__skills__pi__references__update.md b/tools/skillgen/expected/graphify__skills__pi__references__update.md index 3632fd4126..4ce77933bb 100644 --- a/tools/skillgen/expected/graphify__skills__pi__references__update.md +++ b/tools/skillgen/expected/graphify__skills__pi__references__update.md @@ -208,3 +208,13 @@ graphify cluster-only . ``` `graphify cluster-only .` is **self-contained**: it re-clusters, names communities, and regenerates `GRAPH_REPORT.md`, `graph.json`, and `graph.html` from the existing graph. **Do not re-run Steps 5–9** — they read intermediate files (`.graphify_extract.json`, `.graphify_detect.json`, `.graphify_analysis.json`) that a prior build's cleanup (Step 9) already deleted, so they raise `FileNotFoundError` (#1392). When it finishes, present the refreshed `GRAPH_REPORT.md` summary as usual. + +## Verify apparently-successful maintenance runs + +Treat a zero exit code as the start of verification, not proof that the requested work happened: + +- `cluster-only` rebuilds communities; it is not the reliable way to force a new LLM naming pass when labels already exist. Run `graphify label . --backend BACKEND` to re-name communities, then inspect `GRAPH_REPORT.md`: a real labeling run has non-zero `Token cost` and labels other than `Community N`. +- `tree` writes `graphify-out/GRAPH_TREE.html`. If a hierarchy matters, inspect the generated view and ensure the chosen `--root` is the project root; a successful write alone does not prove the intended subtree was selected. +- If output says `Skipped graph.html`, `graph.json` and `GRAPH_REPORT.md` were still written. Use `--no-viz` for CI, or raise `GRAPHIFY_VIZ_NODE_LIMIT` only when the browser can handle the larger view. If writing `graph.json` itself hits the size guard, raise `GRAPHIFY_MAX_GRAPH_BYTES` (for example `700MB`) deliberately. +- A warning that `.sql` or `.tf` files produced zero nodes means that language is absent from the graph. Install the matching extra and rerun: `uv tool install "graphifyy[sql]"` or `uv tool install "graphifyy[terraform]"`. +- The `openai` backend requires `uv tool install "graphifyy[openai]"`. For an OpenAI-compatible gateway, set `OPENAI_BASE_URL` and `OPENAI_MODEL` and pass `--backend openai`. diff --git a/tools/skillgen/expected/graphify__skills__trae__references__query.md b/tools/skillgen/expected/graphify__skills__trae__references__query.md index 56565eb782..85c6a303c6 100644 --- a/tools/skillgen/expected/graphify__skills__trae__references__query.md +++ b/tools/skillgen/expected/graphify__skills__trae__references__query.md @@ -20,6 +20,22 @@ if not Path('graphify-out/graph.json').exists(): ``` If it fails, stop and tell the user to run `/graphify ` first. +## For /graphify affected + +Use `affected` for a deterministic reverse blast-radius answer: "what calls X?", "what depends on X?", or "what could a change to X impact?". Do not replace it with a broad natural-language `query` when the user is asking that question. + +```bash +graphify affected "NODE_OR_LABEL" +``` + +The default depth is two reverse hops. Narrow the result when the user names a relationship, or widen it deliberately: + +```bash +graphify affected "NODE_OR_LABEL" --relation calls --depth 3 +``` + +Use `--graph PATH` when the graph is not at `graphify-out/graph.json`. Explain that the seed itself is the changed item; the printed nodes are the callers/dependents reached by the reverse traversal. If no nodes are found, report that the graph has no matching seed rather than inferring a negative result about the source repository. + ### Step 0 — Constrained query expansion (REQUIRED before traversal) graphify's `query` CLI matches nodes via case-folded substring + IDF — there is **no stemming, no synonyms, no cross-language match** inside the binary, and the inline fallback below matches the same way. If the user's question uses different language or different domain vocabulary than the graph's labels (user says "обработчик" / graph says "handler"; user says "authentication" / graph says "Guardian"), the literal matcher returns 0 hits and the answer collapses to noise. diff --git a/tools/skillgen/expected/graphify__skills__trae__references__update.md b/tools/skillgen/expected/graphify__skills__trae__references__update.md index 3632fd4126..4ce77933bb 100644 --- a/tools/skillgen/expected/graphify__skills__trae__references__update.md +++ b/tools/skillgen/expected/graphify__skills__trae__references__update.md @@ -208,3 +208,13 @@ graphify cluster-only . ``` `graphify cluster-only .` is **self-contained**: it re-clusters, names communities, and regenerates `GRAPH_REPORT.md`, `graph.json`, and `graph.html` from the existing graph. **Do not re-run Steps 5–9** — they read intermediate files (`.graphify_extract.json`, `.graphify_detect.json`, `.graphify_analysis.json`) that a prior build's cleanup (Step 9) already deleted, so they raise `FileNotFoundError` (#1392). When it finishes, present the refreshed `GRAPH_REPORT.md` summary as usual. + +## Verify apparently-successful maintenance runs + +Treat a zero exit code as the start of verification, not proof that the requested work happened: + +- `cluster-only` rebuilds communities; it is not the reliable way to force a new LLM naming pass when labels already exist. Run `graphify label . --backend BACKEND` to re-name communities, then inspect `GRAPH_REPORT.md`: a real labeling run has non-zero `Token cost` and labels other than `Community N`. +- `tree` writes `graphify-out/GRAPH_TREE.html`. If a hierarchy matters, inspect the generated view and ensure the chosen `--root` is the project root; a successful write alone does not prove the intended subtree was selected. +- If output says `Skipped graph.html`, `graph.json` and `GRAPH_REPORT.md` were still written. Use `--no-viz` for CI, or raise `GRAPHIFY_VIZ_NODE_LIMIT` only when the browser can handle the larger view. If writing `graph.json` itself hits the size guard, raise `GRAPHIFY_MAX_GRAPH_BYTES` (for example `700MB`) deliberately. +- A warning that `.sql` or `.tf` files produced zero nodes means that language is absent from the graph. Install the matching extra and rerun: `uv tool install "graphifyy[sql]"` or `uv tool install "graphifyy[terraform]"`. +- The `openai` backend requires `uv tool install "graphifyy[openai]"`. For an OpenAI-compatible gateway, set `OPENAI_BASE_URL` and `OPENAI_MODEL` and pass `--backend openai`. diff --git a/tools/skillgen/expected/graphify__skills__vscode__references__query.md b/tools/skillgen/expected/graphify__skills__vscode__references__query.md index 56565eb782..85c6a303c6 100644 --- a/tools/skillgen/expected/graphify__skills__vscode__references__query.md +++ b/tools/skillgen/expected/graphify__skills__vscode__references__query.md @@ -20,6 +20,22 @@ if not Path('graphify-out/graph.json').exists(): ``` If it fails, stop and tell the user to run `/graphify ` first. +## For /graphify affected + +Use `affected` for a deterministic reverse blast-radius answer: "what calls X?", "what depends on X?", or "what could a change to X impact?". Do not replace it with a broad natural-language `query` when the user is asking that question. + +```bash +graphify affected "NODE_OR_LABEL" +``` + +The default depth is two reverse hops. Narrow the result when the user names a relationship, or widen it deliberately: + +```bash +graphify affected "NODE_OR_LABEL" --relation calls --depth 3 +``` + +Use `--graph PATH` when the graph is not at `graphify-out/graph.json`. Explain that the seed itself is the changed item; the printed nodes are the callers/dependents reached by the reverse traversal. If no nodes are found, report that the graph has no matching seed rather than inferring a negative result about the source repository. + ### Step 0 — Constrained query expansion (REQUIRED before traversal) graphify's `query` CLI matches nodes via case-folded substring + IDF — there is **no stemming, no synonyms, no cross-language match** inside the binary, and the inline fallback below matches the same way. If the user's question uses different language or different domain vocabulary than the graph's labels (user says "обработчик" / graph says "handler"; user says "authentication" / graph says "Guardian"), the literal matcher returns 0 hits and the answer collapses to noise. diff --git a/tools/skillgen/expected/graphify__skills__vscode__references__update.md b/tools/skillgen/expected/graphify__skills__vscode__references__update.md index 3632fd4126..4ce77933bb 100644 --- a/tools/skillgen/expected/graphify__skills__vscode__references__update.md +++ b/tools/skillgen/expected/graphify__skills__vscode__references__update.md @@ -208,3 +208,13 @@ graphify cluster-only . ``` `graphify cluster-only .` is **self-contained**: it re-clusters, names communities, and regenerates `GRAPH_REPORT.md`, `graph.json`, and `graph.html` from the existing graph. **Do not re-run Steps 5–9** — they read intermediate files (`.graphify_extract.json`, `.graphify_detect.json`, `.graphify_analysis.json`) that a prior build's cleanup (Step 9) already deleted, so they raise `FileNotFoundError` (#1392). When it finishes, present the refreshed `GRAPH_REPORT.md` summary as usual. + +## Verify apparently-successful maintenance runs + +Treat a zero exit code as the start of verification, not proof that the requested work happened: + +- `cluster-only` rebuilds communities; it is not the reliable way to force a new LLM naming pass when labels already exist. Run `graphify label . --backend BACKEND` to re-name communities, then inspect `GRAPH_REPORT.md`: a real labeling run has non-zero `Token cost` and labels other than `Community N`. +- `tree` writes `graphify-out/GRAPH_TREE.html`. If a hierarchy matters, inspect the generated view and ensure the chosen `--root` is the project root; a successful write alone does not prove the intended subtree was selected. +- If output says `Skipped graph.html`, `graph.json` and `GRAPH_REPORT.md` were still written. Use `--no-viz` for CI, or raise `GRAPHIFY_VIZ_NODE_LIMIT` only when the browser can handle the larger view. If writing `graph.json` itself hits the size guard, raise `GRAPHIFY_MAX_GRAPH_BYTES` (for example `700MB`) deliberately. +- A warning that `.sql` or `.tf` files produced zero nodes means that language is absent from the graph. Install the matching extra and rerun: `uv tool install "graphifyy[sql]"` or `uv tool install "graphifyy[terraform]"`. +- The `openai` backend requires `uv tool install "graphifyy[openai]"`. For an OpenAI-compatible gateway, set `OPENAI_BASE_URL` and `OPENAI_MODEL` and pass `--backend openai`. diff --git a/tools/skillgen/expected/graphify__skills__windows__references__query.md b/tools/skillgen/expected/graphify__skills__windows__references__query.md index 56565eb782..85c6a303c6 100644 --- a/tools/skillgen/expected/graphify__skills__windows__references__query.md +++ b/tools/skillgen/expected/graphify__skills__windows__references__query.md @@ -20,6 +20,22 @@ if not Path('graphify-out/graph.json').exists(): ``` If it fails, stop and tell the user to run `/graphify ` first. +## For /graphify affected + +Use `affected` for a deterministic reverse blast-radius answer: "what calls X?", "what depends on X?", or "what could a change to X impact?". Do not replace it with a broad natural-language `query` when the user is asking that question. + +```bash +graphify affected "NODE_OR_LABEL" +``` + +The default depth is two reverse hops. Narrow the result when the user names a relationship, or widen it deliberately: + +```bash +graphify affected "NODE_OR_LABEL" --relation calls --depth 3 +``` + +Use `--graph PATH` when the graph is not at `graphify-out/graph.json`. Explain that the seed itself is the changed item; the printed nodes are the callers/dependents reached by the reverse traversal. If no nodes are found, report that the graph has no matching seed rather than inferring a negative result about the source repository. + ### Step 0 — Constrained query expansion (REQUIRED before traversal) graphify's `query` CLI matches nodes via case-folded substring + IDF — there is **no stemming, no synonyms, no cross-language match** inside the binary, and the inline fallback below matches the same way. If the user's question uses different language or different domain vocabulary than the graph's labels (user says "обработчик" / graph says "handler"; user says "authentication" / graph says "Guardian"), the literal matcher returns 0 hits and the answer collapses to noise. diff --git a/tools/skillgen/expected/graphify__skills__windows__references__update.md b/tools/skillgen/expected/graphify__skills__windows__references__update.md index 3632fd4126..4ce77933bb 100644 --- a/tools/skillgen/expected/graphify__skills__windows__references__update.md +++ b/tools/skillgen/expected/graphify__skills__windows__references__update.md @@ -208,3 +208,13 @@ graphify cluster-only . ``` `graphify cluster-only .` is **self-contained**: it re-clusters, names communities, and regenerates `GRAPH_REPORT.md`, `graph.json`, and `graph.html` from the existing graph. **Do not re-run Steps 5–9** — they read intermediate files (`.graphify_extract.json`, `.graphify_detect.json`, `.graphify_analysis.json`) that a prior build's cleanup (Step 9) already deleted, so they raise `FileNotFoundError` (#1392). When it finishes, present the refreshed `GRAPH_REPORT.md` summary as usual. + +## Verify apparently-successful maintenance runs + +Treat a zero exit code as the start of verification, not proof that the requested work happened: + +- `cluster-only` rebuilds communities; it is not the reliable way to force a new LLM naming pass when labels already exist. Run `graphify label . --backend BACKEND` to re-name communities, then inspect `GRAPH_REPORT.md`: a real labeling run has non-zero `Token cost` and labels other than `Community N`. +- `tree` writes `graphify-out/GRAPH_TREE.html`. If a hierarchy matters, inspect the generated view and ensure the chosen `--root` is the project root; a successful write alone does not prove the intended subtree was selected. +- If output says `Skipped graph.html`, `graph.json` and `GRAPH_REPORT.md` were still written. Use `--no-viz` for CI, or raise `GRAPHIFY_VIZ_NODE_LIMIT` only when the browser can handle the larger view. If writing `graph.json` itself hits the size guard, raise `GRAPHIFY_MAX_GRAPH_BYTES` (for example `700MB`) deliberately. +- A warning that `.sql` or `.tf` files produced zero nodes means that language is absent from the graph. Install the matching extra and rerun: `uv tool install "graphifyy[sql]"` or `uv tool install "graphifyy[terraform]"`. +- The `openai` backend requires `uv tool install "graphifyy[openai]"`. For an OpenAI-compatible gateway, set `OPENAI_BASE_URL` and `OPENAI_MODEL` and pass `--backend openai`. diff --git a/tools/skillgen/fragments/core/core.md b/tools/skillgen/fragments/core/core.md index c527a12563..a135e5e6dd 100644 --- a/tools/skillgen/fragments/core/core.md +++ b/tools/skillgen/fragments/core/core.md @@ -609,6 +609,18 @@ Both are non-default subcommands. `--update` re-extracts only new or changed fil --- +## For /graphify affected + +When the user asks for a change's blast radius or "what calls/depends on X?", use `graphify affected "X"` rather than a broad `query`. It reverse-traverses the graph from X and reports the callers and dependents that a change could impact. For relation/depth filters and the exact workflow, see `references/query.md`. + +--- + +## Less-common maintenance commands + +Use these only when the request calls for them: `graphify tree` writes a collapsible hierarchy view; `graphify global add|remove|list|path` manages the cross-repository graph; `graphify check-update ` is the cron-safe stale-graph check; `graphify diagnose multigraph` reports same-endpoint edge-collapse risk; and `graphify merge-driver ` is for a Git merge-driver invocation. Run `graphify --help` before supplying flags, and do not substitute these commands for the normal build/query workflow. + +--- + ## For /graphify add and --watch Neither is part of the default build. When the user runs `/graphify add ` to fetch a URL into the corpus, or passes `--watch` to auto-rebuild on file changes, see `references/add-watch.md`. diff --git a/tools/skillgen/fragments/references/query/default.md b/tools/skillgen/fragments/references/query/default.md index 56565eb782..85c6a303c6 100644 --- a/tools/skillgen/fragments/references/query/default.md +++ b/tools/skillgen/fragments/references/query/default.md @@ -20,6 +20,22 @@ if not Path('graphify-out/graph.json').exists(): ``` If it fails, stop and tell the user to run `/graphify ` first. +## For /graphify affected + +Use `affected` for a deterministic reverse blast-radius answer: "what calls X?", "what depends on X?", or "what could a change to X impact?". Do not replace it with a broad natural-language `query` when the user is asking that question. + +```bash +graphify affected "NODE_OR_LABEL" +``` + +The default depth is two reverse hops. Narrow the result when the user names a relationship, or widen it deliberately: + +```bash +graphify affected "NODE_OR_LABEL" --relation calls --depth 3 +``` + +Use `--graph PATH` when the graph is not at `graphify-out/graph.json`. Explain that the seed itself is the changed item; the printed nodes are the callers/dependents reached by the reverse traversal. If no nodes are found, report that the graph has no matching seed rather than inferring a negative result about the source repository. + ### Step 0 — Constrained query expansion (REQUIRED before traversal) graphify's `query` CLI matches nodes via case-folded substring + IDF — there is **no stemming, no synonyms, no cross-language match** inside the binary, and the inline fallback below matches the same way. If the user's question uses different language or different domain vocabulary than the graph's labels (user says "обработчик" / graph says "handler"; user says "authentication" / graph says "Guardian"), the literal matcher returns 0 hits and the answer collapses to noise. diff --git a/tools/skillgen/fragments/references/shared/update.md b/tools/skillgen/fragments/references/shared/update.md index 3632fd4126..4ce77933bb 100644 --- a/tools/skillgen/fragments/references/shared/update.md +++ b/tools/skillgen/fragments/references/shared/update.md @@ -208,3 +208,13 @@ graphify cluster-only . ``` `graphify cluster-only .` is **self-contained**: it re-clusters, names communities, and regenerates `GRAPH_REPORT.md`, `graph.json`, and `graph.html` from the existing graph. **Do not re-run Steps 5–9** — they read intermediate files (`.graphify_extract.json`, `.graphify_detect.json`, `.graphify_analysis.json`) that a prior build's cleanup (Step 9) already deleted, so they raise `FileNotFoundError` (#1392). When it finishes, present the refreshed `GRAPH_REPORT.md` summary as usual. + +## Verify apparently-successful maintenance runs + +Treat a zero exit code as the start of verification, not proof that the requested work happened: + +- `cluster-only` rebuilds communities; it is not the reliable way to force a new LLM naming pass when labels already exist. Run `graphify label . --backend BACKEND` to re-name communities, then inspect `GRAPH_REPORT.md`: a real labeling run has non-zero `Token cost` and labels other than `Community N`. +- `tree` writes `graphify-out/GRAPH_TREE.html`. If a hierarchy matters, inspect the generated view and ensure the chosen `--root` is the project root; a successful write alone does not prove the intended subtree was selected. +- If output says `Skipped graph.html`, `graph.json` and `GRAPH_REPORT.md` were still written. Use `--no-viz` for CI, or raise `GRAPHIFY_VIZ_NODE_LIMIT` only when the browser can handle the larger view. If writing `graph.json` itself hits the size guard, raise `GRAPHIFY_MAX_GRAPH_BYTES` (for example `700MB`) deliberately. +- A warning that `.sql` or `.tf` files produced zero nodes means that language is absent from the graph. Install the matching extra and rerun: `uv tool install "graphifyy[sql]"` or `uv tool install "graphifyy[terraform]"`. +- The `openai` backend requires `uv tool install "graphifyy[openai]"`. For an OpenAI-compatible gateway, set `OPENAI_BASE_URL` and `OPENAI_MODEL` and pass `--backend openai`.