From 3127ccdcbda046b158aeeb6102344d1faadf5cf2 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. --- 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