From d572b9b3c1aaa6fcbf290ba22347fc15d5737248 Mon Sep 17 00:00:00 2001 From: abhay-codes07 Date: Mon, 31 Aug 2026 13:45:07 +0530 Subject: [PATCH] fix(skill): name `graphify affected` in every always-on block (#3177) The always-on block is the text that reaches the agent on EVERY session - and none of the six templates mentioned `affected`. Measured on a real deployment: zero calls in 262 sessions, while the verbs the block does name (query, path, explain) were used daily once the graph was consulted at all. Agents reach for what the block names. All six templates (CLAUDE.md, AGENTS.md, GEMINI.md, Copilot instructions, Antigravity rules, Kiro steering) now name the blast-radius verb beside query/path/explain, in each template's own voice, and the additions are recorded as sanctioned edits against the frozen v8 baseline so the always-on round-trip validator keeps guarding everything else. Artifacts regenerated, expected/ blessed, all five skillgen validators pass. --- graphify/always_on/agents-md.md | 1 + graphify/always_on/antigravity-rules.md | 1 + graphify/always_on/claude-md.md | 1 + graphify/always_on/gemini-md.md | 1 + graphify/always_on/kiro-steering.md | 2 +- graphify/always_on/vscode-instructions.md | 3 +- tests/test_always_on_affected.py | 32 +++++++++++++++++++ tests/test_skillgen.py | 27 +++++++++++++--- .../graphify__always_on__agents-md.md | 1 + .../graphify__always_on__antigravity-rules.md | 1 + .../graphify__always_on__claude-md.md | 1 + .../graphify__always_on__gemini-md.md | 1 + .../graphify__always_on__kiro-steering.md | 2 +- ...raphify__always_on__vscode-instructions.md | 3 +- .../skillgen/fragments/always-on/agents-md.md | 1 + .../fragments/always-on/antigravity-rules.md | 1 + .../skillgen/fragments/always-on/claude-md.md | 1 + .../skillgen/fragments/always-on/gemini-md.md | 1 + .../fragments/always-on/kiro-steering.md | 2 +- .../always-on/vscode-instructions.md | 3 +- tools/skillgen/gen.py | 31 ++++++++++++++++++ 21 files changed, 106 insertions(+), 11 deletions(-) create mode 100644 tests/test_always_on_affected.py diff --git a/graphify/always_on/agents-md.md b/graphify/always_on/agents-md.md index 6511cd1dd5..feda8d7332 100644 --- a/graphify/always_on/agents-md.md +++ b/graphify/always_on/agents-md.md @@ -6,6 +6,7 @@ When the user types `/graphify`, use the installed graphify skill or instruction Rules: - For codebase questions, first run `graphify query ""` when graphify-out/graph.json exists. Use `graphify path "" ""` for relationships and `graphify explain ""` for focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output. +- Before modifying a symbol or judging a change's impact, run `graphify affected ""` — the blast radius (reverse dependencies), which query/path/explain do not show. - Dirty graphify-out/ files are expected after hooks or incremental updates; dirty graph files are not a reason to skip graphify. Only skip graphify if the task is about stale or incorrect graph output, or the user explicitly says not to use it. - If graphify-out/wiki/index.md exists, use it for broad navigation instead of raw source browsing. - Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context. diff --git a/graphify/always_on/antigravity-rules.md b/graphify/always_on/antigravity-rules.md index 0fc7864147..aa682a2efc 100644 --- a/graphify/always_on/antigravity-rules.md +++ b/graphify/always_on/antigravity-rules.md @@ -9,6 +9,7 @@ This project has a graphify knowledge graph at graphify-out/. Rules: - For codebase or architecture questions, when `graphify-out/graph.json` exists, first run `graphify query ""` (CLI) or `query_graph` (MCP). Use `graphify path "" ""` / `shortest_path` for relationships and `graphify explain ""` / `get_node` for focused concepts. These return a scoped subgraph, usually much smaller than `GRAPH_REPORT.md` or raw grep output. +- Before modifying a symbol or judging a change's impact, run `graphify affected ""` — the blast radius (reverse dependencies), which query/path/explain do not show. - If graphify-out/wiki/index.md exists, navigate it instead of reading raw files - Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context - After modifying code files in this session, run `graphify update .` to keep the graph current (AST-only, no API cost) diff --git a/graphify/always_on/claude-md.md b/graphify/always_on/claude-md.md index 417efeb27e..20cbe2896e 100644 --- a/graphify/always_on/claude-md.md +++ b/graphify/always_on/claude-md.md @@ -4,6 +4,7 @@ This project has a knowledge graph at graphify-out/ with god nodes, community st Rules: - For codebase questions, first run `graphify query ""` when graphify-out/graph.json exists. Use `graphify path "" ""` for relationships and `graphify explain ""` for focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output. +- Before modifying a symbol or judging a change's impact, run `graphify affected ""` — the blast radius (reverse dependencies), which query/path/explain do not show. - If graphify-out/wiki/index.md exists, use it for broad navigation instead of raw source browsing. - Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context. - After modifying code, run `graphify update .` to keep the graph current (AST-only, no API cost). diff --git a/graphify/always_on/gemini-md.md b/graphify/always_on/gemini-md.md index 417efeb27e..20cbe2896e 100644 --- a/graphify/always_on/gemini-md.md +++ b/graphify/always_on/gemini-md.md @@ -4,6 +4,7 @@ This project has a knowledge graph at graphify-out/ with god nodes, community st Rules: - For codebase questions, first run `graphify query ""` when graphify-out/graph.json exists. Use `graphify path "" ""` for relationships and `graphify explain ""` for focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output. +- Before modifying a symbol or judging a change's impact, run `graphify affected ""` — the blast radius (reverse dependencies), which query/path/explain do not show. - If graphify-out/wiki/index.md exists, use it for broad navigation instead of raw source browsing. - Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context. - After modifying code, run `graphify update .` to keep the graph current (AST-only, no API cost). diff --git a/graphify/always_on/kiro-steering.md b/graphify/always_on/kiro-steering.md index cb6f4543db..6a9a9ada4d 100644 --- a/graphify/always_on/kiro-steering.md +++ b/graphify/always_on/kiro-steering.md @@ -2,4 +2,4 @@ inclusion: always --- -graphify: A knowledge graph of this project lives in `graphify-out/`. For codebase, architecture, or dependency questions, when `graphify-out/graph.json` exists, first run `graphify query ""` (or `graphify path "" ""` / `graphify explain ""`). These return a scoped subgraph, usually much smaller than `GRAPH_REPORT.md` or raw grep output. Read `GRAPH_REPORT.md` only for broad architecture review or when those commands do not surface enough context. +graphify: A knowledge graph of this project lives in `graphify-out/`. For codebase, architecture, or dependency questions, when `graphify-out/graph.json` exists, first run `graphify query ""` (or `graphify path "" ""` / `graphify explain ""`). These return a scoped subgraph, usually much smaller than `GRAPH_REPORT.md` or raw grep output. Read `GRAPH_REPORT.md` only for broad architecture review or when those commands do not surface enough context. Before modifying a symbol, run `graphify affected ""` for its blast radius (reverse dependencies). diff --git a/graphify/always_on/vscode-instructions.md b/graphify/always_on/vscode-instructions.md index 9cb983c950..7f6c6f5121 100644 --- a/graphify/always_on/vscode-instructions.md +++ b/graphify/always_on/vscode-instructions.md @@ -4,7 +4,8 @@ For any question about this repo's architecture, structure, components, or how t code, your first action should be `graphify query ""` when `graphify-out/graph.json` exists. Use `graphify path "" ""` for relationship questions and `graphify explain ""` for focused-concept questions. These return a scoped subgraph, usually much smaller than the full -report or raw grep output. +report or raw grep output. Before modifying a symbol or assessing a change's impact, run +`graphify affected ""` for its blast radius (reverse dependencies). Triggers: "how do I…", "where is…", "what does … do", "add/modify a ", "explain the architecture", or anything that depends on how files or classes relate. diff --git a/tests/test_always_on_affected.py b/tests/test_always_on_affected.py new file mode 100644 index 0000000000..18a052596f --- /dev/null +++ b/tests/test_always_on_affected.py @@ -0,0 +1,32 @@ +"""Every always-on block names `graphify affected` (#3177). + +The always-on text is what reaches the agent on every session — and none of +the six templates mentioned `affected`, so in 262 measured sessions it was +called zero times while the verbs the block does name (query/explain) were +used daily. The block now names the blast-radius verb beside them. +""" +from __future__ import annotations + +from pathlib import Path + +import pytest + +ALWAYS_ON = Path(__file__).resolve().parent.parent / "graphify" / "always_on" +BLOCKS = sorted(p.name for p in ALWAYS_ON.glob("*.md")) + + +def test_all_six_blocks_exist(): + assert len(BLOCKS) == 6, BLOCKS + + +@pytest.mark.parametrize("name", BLOCKS) +def test_every_block_names_the_blast_radius_verb(name): + body = (ALWAYS_ON / name).read_text(encoding="utf-8") + assert "graphify affected" in body, f"{name} never names affected" + assert "blast radius" in body + + +@pytest.mark.parametrize("name", BLOCKS) +def test_the_existing_verbs_are_still_named(name): + body = (ALWAYS_ON / name).read_text(encoding="utf-8") + assert "graphify query" in body diff --git a/tests/test_skillgen.py b/tests/test_skillgen.py index 63a6f7c173..e5c33eb561 100644 --- a/tests/test_skillgen.py +++ b/tests/test_skillgen.py @@ -750,15 +750,32 @@ def test_always_on_roundtrip_is_byte_faithful(): "When the user types `/graphify`, use the installed graphify skill or instructions " "before doing anything else." ) - # The sanctioned-edit registry holds exactly this single old->new substitution. - assert gen.ALWAYS_ON_SANCTIONED_EDITS["_AGENTS_MD_SECTION"] == ( - (old_instruction, new_instruction), + # The sanctioned-edit registry still opens with the #1530 substitution... + assert gen.ALWAYS_ON_SANCTIONED_EDITS["_AGENTS_MD_SECTION"][0] == ( + old_instruction, new_instruction, ) + # ...and every constant now carries exactly one #3177 edit that adds the + # blast-radius verb without removing anything else (the new text embeds + # the old, so the substitution is purely additive). + for const_name in gen.ALWAYS_ON_BLOCKS.values(): + pairs = gen.ALWAYS_ON_SANCTIONED_EDITS[const_name] + affected_pairs = [(o, n) for o, n in pairs if "graphify affected" in n] + assert len(affected_pairs) == 1, const_name + o, n = affected_pairs[0] + # Additive modulo line wrapping: the old text's words survive as the + # prefix of the new text's words. + assert n.split()[: len(o.split())] == o.split(), ( + f"{const_name}: the #3177 edit must be additive" + ) baseline_agents = gen._always_on_constants(gen.ALWAYS_ON_BASELINE_REF)["_AGENTS_MD_SECTION"] - # The ONLY divergence from the frozen baseline is the sanctioned sentence — + # The ONLY divergences from the frozen baseline are the sanctioned edits — # any other byte drift would have surfaced as a problem above. assert old_instruction in baseline_agents - assert baseline_agents.replace(old_instruction, new_instruction) == rendered_agents + expected_agents = baseline_agents + for o, n in gen.ALWAYS_ON_SANCTIONED_EDITS["_AGENTS_MD_SECTION"]: + assert o in expected_agents + expected_agents = expected_agents.replace(o, n) + assert expected_agents == rendered_agents assert "`skill` tool" not in rendered_agents assert 'skill: "graphify"' not in rendered_agents diff --git a/tools/skillgen/expected/graphify__always_on__agents-md.md b/tools/skillgen/expected/graphify__always_on__agents-md.md index 6511cd1dd5..feda8d7332 100644 --- a/tools/skillgen/expected/graphify__always_on__agents-md.md +++ b/tools/skillgen/expected/graphify__always_on__agents-md.md @@ -6,6 +6,7 @@ When the user types `/graphify`, use the installed graphify skill or instruction Rules: - For codebase questions, first run `graphify query ""` when graphify-out/graph.json exists. Use `graphify path "" ""` for relationships and `graphify explain ""` for focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output. +- Before modifying a symbol or judging a change's impact, run `graphify affected ""` — the blast radius (reverse dependencies), which query/path/explain do not show. - Dirty graphify-out/ files are expected after hooks or incremental updates; dirty graph files are not a reason to skip graphify. Only skip graphify if the task is about stale or incorrect graph output, or the user explicitly says not to use it. - If graphify-out/wiki/index.md exists, use it for broad navigation instead of raw source browsing. - Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context. diff --git a/tools/skillgen/expected/graphify__always_on__antigravity-rules.md b/tools/skillgen/expected/graphify__always_on__antigravity-rules.md index 0fc7864147..aa682a2efc 100644 --- a/tools/skillgen/expected/graphify__always_on__antigravity-rules.md +++ b/tools/skillgen/expected/graphify__always_on__antigravity-rules.md @@ -9,6 +9,7 @@ This project has a graphify knowledge graph at graphify-out/. Rules: - For codebase or architecture questions, when `graphify-out/graph.json` exists, first run `graphify query ""` (CLI) or `query_graph` (MCP). Use `graphify path "" ""` / `shortest_path` for relationships and `graphify explain ""` / `get_node` for focused concepts. These return a scoped subgraph, usually much smaller than `GRAPH_REPORT.md` or raw grep output. +- Before modifying a symbol or judging a change's impact, run `graphify affected ""` — the blast radius (reverse dependencies), which query/path/explain do not show. - If graphify-out/wiki/index.md exists, navigate it instead of reading raw files - Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context - After modifying code files in this session, run `graphify update .` to keep the graph current (AST-only, no API cost) diff --git a/tools/skillgen/expected/graphify__always_on__claude-md.md b/tools/skillgen/expected/graphify__always_on__claude-md.md index 417efeb27e..20cbe2896e 100644 --- a/tools/skillgen/expected/graphify__always_on__claude-md.md +++ b/tools/skillgen/expected/graphify__always_on__claude-md.md @@ -4,6 +4,7 @@ This project has a knowledge graph at graphify-out/ with god nodes, community st Rules: - For codebase questions, first run `graphify query ""` when graphify-out/graph.json exists. Use `graphify path "" ""` for relationships and `graphify explain ""` for focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output. +- Before modifying a symbol or judging a change's impact, run `graphify affected ""` — the blast radius (reverse dependencies), which query/path/explain do not show. - If graphify-out/wiki/index.md exists, use it for broad navigation instead of raw source browsing. - Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context. - After modifying code, run `graphify update .` to keep the graph current (AST-only, no API cost). diff --git a/tools/skillgen/expected/graphify__always_on__gemini-md.md b/tools/skillgen/expected/graphify__always_on__gemini-md.md index 417efeb27e..20cbe2896e 100644 --- a/tools/skillgen/expected/graphify__always_on__gemini-md.md +++ b/tools/skillgen/expected/graphify__always_on__gemini-md.md @@ -4,6 +4,7 @@ This project has a knowledge graph at graphify-out/ with god nodes, community st Rules: - For codebase questions, first run `graphify query ""` when graphify-out/graph.json exists. Use `graphify path "" ""` for relationships and `graphify explain ""` for focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output. +- Before modifying a symbol or judging a change's impact, run `graphify affected ""` — the blast radius (reverse dependencies), which query/path/explain do not show. - If graphify-out/wiki/index.md exists, use it for broad navigation instead of raw source browsing. - Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context. - After modifying code, run `graphify update .` to keep the graph current (AST-only, no API cost). diff --git a/tools/skillgen/expected/graphify__always_on__kiro-steering.md b/tools/skillgen/expected/graphify__always_on__kiro-steering.md index cb6f4543db..6a9a9ada4d 100644 --- a/tools/skillgen/expected/graphify__always_on__kiro-steering.md +++ b/tools/skillgen/expected/graphify__always_on__kiro-steering.md @@ -2,4 +2,4 @@ inclusion: always --- -graphify: A knowledge graph of this project lives in `graphify-out/`. For codebase, architecture, or dependency questions, when `graphify-out/graph.json` exists, first run `graphify query ""` (or `graphify path "" ""` / `graphify explain ""`). These return a scoped subgraph, usually much smaller than `GRAPH_REPORT.md` or raw grep output. Read `GRAPH_REPORT.md` only for broad architecture review or when those commands do not surface enough context. +graphify: A knowledge graph of this project lives in `graphify-out/`. For codebase, architecture, or dependency questions, when `graphify-out/graph.json` exists, first run `graphify query ""` (or `graphify path "" ""` / `graphify explain ""`). These return a scoped subgraph, usually much smaller than `GRAPH_REPORT.md` or raw grep output. Read `GRAPH_REPORT.md` only for broad architecture review or when those commands do not surface enough context. Before modifying a symbol, run `graphify affected ""` for its blast radius (reverse dependencies). diff --git a/tools/skillgen/expected/graphify__always_on__vscode-instructions.md b/tools/skillgen/expected/graphify__always_on__vscode-instructions.md index 9cb983c950..7f6c6f5121 100644 --- a/tools/skillgen/expected/graphify__always_on__vscode-instructions.md +++ b/tools/skillgen/expected/graphify__always_on__vscode-instructions.md @@ -4,7 +4,8 @@ For any question about this repo's architecture, structure, components, or how t code, your first action should be `graphify query ""` when `graphify-out/graph.json` exists. Use `graphify path "" ""` for relationship questions and `graphify explain ""` for focused-concept questions. These return a scoped subgraph, usually much smaller than the full -report or raw grep output. +report or raw grep output. Before modifying a symbol or assessing a change's impact, run +`graphify affected ""` for its blast radius (reverse dependencies). Triggers: "how do I…", "where is…", "what does … do", "add/modify a ", "explain the architecture", or anything that depends on how files or classes relate. diff --git a/tools/skillgen/fragments/always-on/agents-md.md b/tools/skillgen/fragments/always-on/agents-md.md index 6511cd1dd5..feda8d7332 100644 --- a/tools/skillgen/fragments/always-on/agents-md.md +++ b/tools/skillgen/fragments/always-on/agents-md.md @@ -6,6 +6,7 @@ When the user types `/graphify`, use the installed graphify skill or instruction Rules: - For codebase questions, first run `graphify query ""` when graphify-out/graph.json exists. Use `graphify path "" ""` for relationships and `graphify explain ""` for focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output. +- Before modifying a symbol or judging a change's impact, run `graphify affected ""` — the blast radius (reverse dependencies), which query/path/explain do not show. - Dirty graphify-out/ files are expected after hooks or incremental updates; dirty graph files are not a reason to skip graphify. Only skip graphify if the task is about stale or incorrect graph output, or the user explicitly says not to use it. - If graphify-out/wiki/index.md exists, use it for broad navigation instead of raw source browsing. - Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context. diff --git a/tools/skillgen/fragments/always-on/antigravity-rules.md b/tools/skillgen/fragments/always-on/antigravity-rules.md index 0fc7864147..aa682a2efc 100644 --- a/tools/skillgen/fragments/always-on/antigravity-rules.md +++ b/tools/skillgen/fragments/always-on/antigravity-rules.md @@ -9,6 +9,7 @@ This project has a graphify knowledge graph at graphify-out/. Rules: - For codebase or architecture questions, when `graphify-out/graph.json` exists, first run `graphify query ""` (CLI) or `query_graph` (MCP). Use `graphify path "" ""` / `shortest_path` for relationships and `graphify explain ""` / `get_node` for focused concepts. These return a scoped subgraph, usually much smaller than `GRAPH_REPORT.md` or raw grep output. +- Before modifying a symbol or judging a change's impact, run `graphify affected ""` — the blast radius (reverse dependencies), which query/path/explain do not show. - If graphify-out/wiki/index.md exists, navigate it instead of reading raw files - Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context - After modifying code files in this session, run `graphify update .` to keep the graph current (AST-only, no API cost) diff --git a/tools/skillgen/fragments/always-on/claude-md.md b/tools/skillgen/fragments/always-on/claude-md.md index 417efeb27e..20cbe2896e 100644 --- a/tools/skillgen/fragments/always-on/claude-md.md +++ b/tools/skillgen/fragments/always-on/claude-md.md @@ -4,6 +4,7 @@ This project has a knowledge graph at graphify-out/ with god nodes, community st Rules: - For codebase questions, first run `graphify query ""` when graphify-out/graph.json exists. Use `graphify path "" ""` for relationships and `graphify explain ""` for focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output. +- Before modifying a symbol or judging a change's impact, run `graphify affected ""` — the blast radius (reverse dependencies), which query/path/explain do not show. - If graphify-out/wiki/index.md exists, use it for broad navigation instead of raw source browsing. - Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context. - After modifying code, run `graphify update .` to keep the graph current (AST-only, no API cost). diff --git a/tools/skillgen/fragments/always-on/gemini-md.md b/tools/skillgen/fragments/always-on/gemini-md.md index 417efeb27e..20cbe2896e 100644 --- a/tools/skillgen/fragments/always-on/gemini-md.md +++ b/tools/skillgen/fragments/always-on/gemini-md.md @@ -4,6 +4,7 @@ This project has a knowledge graph at graphify-out/ with god nodes, community st Rules: - For codebase questions, first run `graphify query ""` when graphify-out/graph.json exists. Use `graphify path "" ""` for relationships and `graphify explain ""` for focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output. +- Before modifying a symbol or judging a change's impact, run `graphify affected ""` — the blast radius (reverse dependencies), which query/path/explain do not show. - If graphify-out/wiki/index.md exists, use it for broad navigation instead of raw source browsing. - Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context. - After modifying code, run `graphify update .` to keep the graph current (AST-only, no API cost). diff --git a/tools/skillgen/fragments/always-on/kiro-steering.md b/tools/skillgen/fragments/always-on/kiro-steering.md index cb6f4543db..6a9a9ada4d 100644 --- a/tools/skillgen/fragments/always-on/kiro-steering.md +++ b/tools/skillgen/fragments/always-on/kiro-steering.md @@ -2,4 +2,4 @@ inclusion: always --- -graphify: A knowledge graph of this project lives in `graphify-out/`. For codebase, architecture, or dependency questions, when `graphify-out/graph.json` exists, first run `graphify query ""` (or `graphify path "" ""` / `graphify explain ""`). These return a scoped subgraph, usually much smaller than `GRAPH_REPORT.md` or raw grep output. Read `GRAPH_REPORT.md` only for broad architecture review or when those commands do not surface enough context. +graphify: A knowledge graph of this project lives in `graphify-out/`. For codebase, architecture, or dependency questions, when `graphify-out/graph.json` exists, first run `graphify query ""` (or `graphify path "" ""` / `graphify explain ""`). These return a scoped subgraph, usually much smaller than `GRAPH_REPORT.md` or raw grep output. Read `GRAPH_REPORT.md` only for broad architecture review or when those commands do not surface enough context. Before modifying a symbol, run `graphify affected ""` for its blast radius (reverse dependencies). diff --git a/tools/skillgen/fragments/always-on/vscode-instructions.md b/tools/skillgen/fragments/always-on/vscode-instructions.md index 9cb983c950..7f6c6f5121 100644 --- a/tools/skillgen/fragments/always-on/vscode-instructions.md +++ b/tools/skillgen/fragments/always-on/vscode-instructions.md @@ -4,7 +4,8 @@ For any question about this repo's architecture, structure, components, or how t code, your first action should be `graphify query ""` when `graphify-out/graph.json` exists. Use `graphify path "" ""` for relationship questions and `graphify explain ""` for focused-concept questions. These return a scoped subgraph, usually much smaller than the full -report or raw grep output. +report or raw grep output. Before modifying a symbol or assessing a change's impact, run +`graphify affected ""` for its blast radius (reverse dependencies). Triggers: "how do I…", "where is…", "what does … do", "add/modify a ", "explain the architecture", or anything that depends on how files or classes relate. diff --git a/tools/skillgen/gen.py b/tools/skillgen/gen.py index 09e19ede00..784a3ee845 100644 --- a/tools/skillgen/gen.py +++ b/tools/skillgen/gen.py @@ -110,6 +110,37 @@ def _v8_baseline_ref(platform_key: str) -> str: "When the user types `/graphify`, use the installed graphify skill or instructions " "before doing anything else.", ), + # #3177: none of the always-on blocks named `affected`, and in 262 + # measured sessions it went uncalled while query/explain (the verbs + # the block names) were used daily. The block is what the agent + # actually reaches for; name the blast-radius verb there. + ('- For codebase questions, first run `graphify query ""` when graphify-out/graph.json exists. Use `graphify path "" ""` for relationships and `graphify explain ""` for focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output.', + '- For codebase questions, first run `graphify query ""` when graphify-out/graph.json exists. Use `graphify path "" ""` for relationships and `graphify explain ""` for focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output.\n- Before modifying a symbol or judging a change\'s impact, run `graphify affected ""` — the blast radius (reverse dependencies), which query/path/explain do not show.'), + ), + # #3177 (see _AGENTS_MD_SECTION note above) + "_CLAUDE_MD_SECTION": ( + ('- For codebase questions, first run `graphify query ""` when graphify-out/graph.json exists. Use `graphify path "" ""` for relationships and `graphify explain ""` for focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output.', + '- For codebase questions, first run `graphify query ""` when graphify-out/graph.json exists. Use `graphify path "" ""` for relationships and `graphify explain ""` for focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output.\n- Before modifying a symbol or judging a change\'s impact, run `graphify affected ""` — the blast radius (reverse dependencies), which query/path/explain do not show.'), + ), + # #3177 (see _AGENTS_MD_SECTION note above) + "_GEMINI_MD_SECTION": ( + ('- For codebase questions, first run `graphify query ""` when graphify-out/graph.json exists. Use `graphify path "" ""` for relationships and `graphify explain ""` for focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output.', + '- For codebase questions, first run `graphify query ""` when graphify-out/graph.json exists. Use `graphify path "" ""` for relationships and `graphify explain ""` for focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output.\n- Before modifying a symbol or judging a change\'s impact, run `graphify affected ""` — the blast radius (reverse dependencies), which query/path/explain do not show.'), + ), + # #3177 (see _AGENTS_MD_SECTION note above) + "_ANTIGRAVITY_RULES": ( + ('- For codebase or architecture questions, when `graphify-out/graph.json` exists, first run `graphify query ""` (CLI) or `query_graph` (MCP). Use `graphify path "" ""` / `shortest_path` for relationships and `graphify explain ""` / `get_node` for focused concepts. These return a scoped subgraph, usually much smaller than `GRAPH_REPORT.md` or raw grep output.', + '- For codebase or architecture questions, when `graphify-out/graph.json` exists, first run `graphify query ""` (CLI) or `query_graph` (MCP). Use `graphify path "" ""` / `shortest_path` for relationships and `graphify explain ""` / `get_node` for focused concepts. These return a scoped subgraph, usually much smaller than `GRAPH_REPORT.md` or raw grep output.\n- Before modifying a symbol or judging a change\'s impact, run `graphify affected ""` — the blast radius (reverse dependencies), which query/path/explain do not show.'), + ), + # #3177 (see _AGENTS_MD_SECTION note above) + "_KIRO_STEERING": ( + ('These return a scoped subgraph, usually much smaller than `GRAPH_REPORT.md` or raw grep output. Read `GRAPH_REPORT.md` only for broad architecture review or when those commands do not surface enough context.', + 'These return a scoped subgraph, usually much smaller than `GRAPH_REPORT.md` or raw grep output. Read `GRAPH_REPORT.md` only for broad architecture review or when those commands do not surface enough context. Before modifying a symbol, run `graphify affected ""` for its blast radius (reverse dependencies).'), + ), + # #3177 (see _AGENTS_MD_SECTION note above) + "_VSCODE_INSTRUCTIONS_SECTION": ( + ('These return a scoped subgraph, usually much smaller than the full\nreport or raw grep output.\n', + 'These return a scoped subgraph, usually much smaller than the full\nreport or raw grep output. Before modifying a symbol or assessing a change\'s impact, run\n`graphify affected ""` for its blast radius (reverse dependencies).\n'), ), }