From f764a54bdf9fe36bb01ca64b451cdc655d12913d Mon Sep 17 00:00:00 2001 From: Andre Brait Date: Sun, 11 Oct 2026 10:25:42 +0000 Subject: [PATCH] docs(always-on): carry the query-first rule into subagents and narrow raw reads The always-on blocks now tell the assistant to pass the rule to every subagent that explores code (a fresh subagent may never see a nudge before it starts reading) and to read raw files only for lines the graph or an earlier read already located, matching the hook's narrowed wording. (cherry picked from commit 3127ccdcbda046b158aeeb6102344d1faadf5cf2) --- graphify/always_on/agents-md.md | 2 +- graphify/always_on/claude-md.md | 2 +- graphify/always_on/gemini-md.md | 2 +- tools/skillgen/expected/graphify__always_on__agents-md.md | 2 +- tools/skillgen/expected/graphify__always_on__claude-md.md | 2 +- tools/skillgen/expected/graphify__always_on__gemini-md.md | 2 +- tools/skillgen/fragments/always-on/agents-md.md | 2 +- tools/skillgen/fragments/always-on/claude-md.md | 2 +- tools/skillgen/fragments/always-on/gemini-md.md | 2 +- tools/skillgen/gen.py | 4 +++- 10 files changed, 12 insertions(+), 10 deletions(-) diff --git a/graphify/always_on/agents-md.md b/graphify/always_on/agents-md.md index 98b8b44df..1cbef9e90 100644 --- a/graphify/always_on/agents-md.md +++ b/graphify/always_on/agents-md.md @@ -5,7 +5,7 @@ This project has a knowledge graph at graphify-out/ with god nodes, community st When the user types `/graphify`, use the installed graphify skill or instructions before doing anything else. Rules: -- When graphify-out/graph.json exists, run `graphify query ""` before your first grep, search or source-file read for a codebase question. 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. +- When graphify-out/graph.json exists, run `graphify query ""` before your first grep, search or source-file read for a codebase question, and put this rule in every subagent prompt that explores code. Read raw files only for lines the graph or an earlier read already located. 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. - 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/claude-md.md b/graphify/always_on/claude-md.md index 5a3252d27..d5a885bff 100644 --- a/graphify/always_on/claude-md.md +++ b/graphify/always_on/claude-md.md @@ -3,7 +3,7 @@ This project has a knowledge graph at graphify-out/ with god nodes, community structure, and cross-file relationships. Rules: -- When graphify-out/graph.json exists, run `graphify query ""` before your first grep, search or source-file read for a codebase question. 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. +- When graphify-out/graph.json exists, run `graphify query ""` before your first grep, search or source-file read for a codebase question, and put this rule in every subagent prompt that explores code. Read raw files only for lines the graph or an earlier read already located. 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. - 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 5a3252d27..d5a885bff 100644 --- a/graphify/always_on/gemini-md.md +++ b/graphify/always_on/gemini-md.md @@ -3,7 +3,7 @@ This project has a knowledge graph at graphify-out/ with god nodes, community structure, and cross-file relationships. Rules: -- When graphify-out/graph.json exists, run `graphify query ""` before your first grep, search or source-file read for a codebase question. 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. +- When graphify-out/graph.json exists, run `graphify query ""` before your first grep, search or source-file read for a codebase question, and put this rule in every subagent prompt that explores code. Read raw files only for lines the graph or an earlier read already located. 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. - 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__agents-md.md b/tools/skillgen/expected/graphify__always_on__agents-md.md index 98b8b44df..1cbef9e90 100644 --- a/tools/skillgen/expected/graphify__always_on__agents-md.md +++ b/tools/skillgen/expected/graphify__always_on__agents-md.md @@ -5,7 +5,7 @@ This project has a knowledge graph at graphify-out/ with god nodes, community st When the user types `/graphify`, use the installed graphify skill or instructions before doing anything else. Rules: -- When graphify-out/graph.json exists, run `graphify query ""` before your first grep, search or source-file read for a codebase question. 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. +- When graphify-out/graph.json exists, run `graphify query ""` before your first grep, search or source-file read for a codebase question, and put this rule in every subagent prompt that explores code. Read raw files only for lines the graph or an earlier read already located. 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. - 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__claude-md.md b/tools/skillgen/expected/graphify__always_on__claude-md.md index 5a3252d27..d5a885bff 100644 --- a/tools/skillgen/expected/graphify__always_on__claude-md.md +++ b/tools/skillgen/expected/graphify__always_on__claude-md.md @@ -3,7 +3,7 @@ This project has a knowledge graph at graphify-out/ with god nodes, community structure, and cross-file relationships. Rules: -- When graphify-out/graph.json exists, run `graphify query ""` before your first grep, search or source-file read for a codebase question. 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. +- When graphify-out/graph.json exists, run `graphify query ""` before your first grep, search or source-file read for a codebase question, and put this rule in every subagent prompt that explores code. Read raw files only for lines the graph or an earlier read already located. 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. - 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 5a3252d27..d5a885bff 100644 --- a/tools/skillgen/expected/graphify__always_on__gemini-md.md +++ b/tools/skillgen/expected/graphify__always_on__gemini-md.md @@ -3,7 +3,7 @@ This project has a knowledge graph at graphify-out/ with god nodes, community structure, and cross-file relationships. Rules: -- When graphify-out/graph.json exists, run `graphify query ""` before your first grep, search or source-file read for a codebase question. 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. +- When graphify-out/graph.json exists, run `graphify query ""` before your first grep, search or source-file read for a codebase question, and put this rule in every subagent prompt that explores code. Read raw files only for lines the graph or an earlier read already located. 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. - 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/agents-md.md b/tools/skillgen/fragments/always-on/agents-md.md index 98b8b44df..1cbef9e90 100644 --- a/tools/skillgen/fragments/always-on/agents-md.md +++ b/tools/skillgen/fragments/always-on/agents-md.md @@ -5,7 +5,7 @@ This project has a knowledge graph at graphify-out/ with god nodes, community st When the user types `/graphify`, use the installed graphify skill or instructions before doing anything else. Rules: -- When graphify-out/graph.json exists, run `graphify query ""` before your first grep, search or source-file read for a codebase question. 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. +- When graphify-out/graph.json exists, run `graphify query ""` before your first grep, search or source-file read for a codebase question, and put this rule in every subagent prompt that explores code. Read raw files only for lines the graph or an earlier read already located. 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. - 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/claude-md.md b/tools/skillgen/fragments/always-on/claude-md.md index 5a3252d27..d5a885bff 100644 --- a/tools/skillgen/fragments/always-on/claude-md.md +++ b/tools/skillgen/fragments/always-on/claude-md.md @@ -3,7 +3,7 @@ This project has a knowledge graph at graphify-out/ with god nodes, community structure, and cross-file relationships. Rules: -- When graphify-out/graph.json exists, run `graphify query ""` before your first grep, search or source-file read for a codebase question. 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. +- When graphify-out/graph.json exists, run `graphify query ""` before your first grep, search or source-file read for a codebase question, and put this rule in every subagent prompt that explores code. Read raw files only for lines the graph or an earlier read already located. 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. - 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 5a3252d27..d5a885bff 100644 --- a/tools/skillgen/fragments/always-on/gemini-md.md +++ b/tools/skillgen/fragments/always-on/gemini-md.md @@ -3,7 +3,7 @@ This project has a knowledge graph at graphify-out/ with god nodes, community structure, and cross-file relationships. Rules: -- When graphify-out/graph.json exists, run `graphify query ""` before your first grep, search or source-file read for a codebase question. 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. +- When graphify-out/graph.json exists, run `graphify query ""` before your first grep, search or source-file read for a codebase question, and put this rule in every subagent prompt that explores code. Read raw files only for lines the graph or an earlier read already located. 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. - 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/gen.py b/tools/skillgen/gen.py index c63a369c8..303f267b3 100644 --- a/tools/skillgen/gen.py +++ b/tools/skillgen/gen.py @@ -99,7 +99,9 @@ _QUERY_FIRST_EDIT = ( 'For codebase questions, first run `graphify query ""` when ' "graphify-out/graph.json exists.", 'When graphify-out/graph.json exists, run `graphify query ""` before ' - "your first grep, search or source-file read for a codebase question.", + "your first grep, search or source-file read for a codebase question, and put " + "this rule in every subagent prompt that explores code. Read raw files only for " + "lines the graph or an earlier read already located.", ) # Sanctioned divergences from the frozen always-on baseline above. The roundtrip