graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
Python
prompt: one-line heads-ups, no second derivation, new files need no read
justrach8419711322b9
diff --git a/docs/adr/0239-heads-ups-are-one-line-and-a-computed-answer-is-its-own-proof.md b/docs/adr/0239-heads-ups-are-one-line-and-a-computed-answer-is-its-own-proof.mdnew file mode 100644index 00000000..65d9a840--- /dev/null+++ b/docs/adr/0239-heads-ups-are-one-line-and-a-computed-answer-is-its-own-proof.md@@ -0,0 +1,51 @@+# 0239. Heads-ups are one line, a computed answer is its own proof, and a new file needs no read++Status: accepted 2026-10-03++## Context++Paired runs against another coding harness, on the same models and plan and+the same tasks, showed that a model call's time follows the tokens it writes,+not the size of the context it reads. graff's calls wrote more than the other+harness's, and most of the difference was text the task did not ask for:++- **Narration.** The intro asked the model to "say what you found, then what+ you will do", and the heads-up note asked for one or two sentences before a+ large chunk of work. Models wrote a short paragraph ahead of most tool+ calls. The other harness asks for no narration and its models wrote almost+ none.+- **Second derivations.** "Make the requested thing work and prove it" read+ as license to compute an answer twice: a log census counted every file,+ then counted them again a different way in the same script and asserted+ the two agreed. Runs on the other harness never did this.+- **Reading files that do not exist yet.** `read_file` said "Call this before+ editing any text file", and models read paths they were about to create.++## Decision++- The intro asks for one short line, a dozen words at most, on what was found+ and what comes next. The heads-up note asks for a one-line heads-up in the+ same response as the tool calls it introduces (ADR 0061), one short line as+ each phase lands, and one line before a command that can run for minutes.+- The work note keeps "make the requested thing work and prove it" and adds+ that a script that computes an answer is its own proof: do not re-derive it+ a second way.+- `read_file` says to call it before editing an existing text file; a file+ about to be created needs no read.++On the paired runs, prose ahead of tool calls fell sharply, output tokens and+calls per task went down, and tasks finished sooner at the same pass rate.++Two alternatives were measured and not taken. Asking for no narration at all+was only slightly faster still, and it would leave the transcript with tool+rows and no narration (ADR 0021). Dropping the publishing, commit-authoring+and issue-filing segments saved nothing measurable, since prompt size does+not drive a call's time, and those segments carry safety rules.++## Consequences++The transcript shows one-liners where it showed short paragraphs. A plan that+needs explaining still goes in the final message. A computed answer is+trusted once its script runs. Revisit if a trace shows a wrong computed+answer that a second derivation would have caught, or if users find the+heads-ups too terse to follow a long task.diff --git a/docs/adr/README.md b/docs/adr/README.mdindex 98265dc7..d21a8b50 100644--- a/docs/adr/README.md+++ b/docs/adr/README.md@@ -265,6 +265,7 @@ record only when you need the evidence or the edge cases.| [0236](0236-rlm-takes-json-literals-and-each-maps-plain-values.md) | `rlm` takes JSON array/object literals as arguments and binds (`name = [...]`, bound names allowed inside); its splitters nest `[]`/`{}`; `each(arr, tool[, field])` passes plain items as is, picks `field` from objects (default: an MCP tool's first parameter) and names the fields it found; an unsupported statement lists the forms that work. || [0237](0237-deepseek-thinks-at-its-low-level-by-default.md) | DeepSeek's default effort (`medium`) sends `reasoning_effort: low` with thinking enabled; `/effort low` still turns thinking off (ADR 0054), and `high` and above are unchanged. || [0238](0238-rlm-binds-keep-the-whole-mcp-result.md) | An MCP call inside an rlm script binds the whole result; `print()` shows the slim view (each item of an `each()` bind cut on its own), `project(x, field)` reads any field (`n`/`latest_author` through a comment list's fold), and `write_file` saves the whole result; inside rlm, `read_tool_result("tr_N")` with no range binds a stored result whole. |+| [0239](0239-heads-ups-are-one-line-and-a-computed-answer-is-its-own-proof.md) | Heads-ups are one short line in the same response as their tool calls; a script that computes an answer is its own proof (no second derivation); `read_file` is required only before editing an existing file. |## When to write onediff --git a/src/prompt_golden.zig b/src/prompt_golden.zigindex 2f6902f6..7c94957f 100644--- a/src/prompt_golden.zig+++ b/src/prompt_golden.zig@@ -12,9 +12,9 @@ pub const full_prompt =\\a tool, a parameter, or a wrapper API around one, and never assume a\\capability that is not listed for you — when the thing you want is absent,\\say so and finish the task with what is here.- \\Inspect before you commit to an architecture: say what you found, then- \\what you will do, then do it. Do not announce a solution and hunt for- \\confirmation of it.+ \\Inspect before you commit to an architecture: in one short line (a dozen+ \\words at most), say what you found and what you will do, then do it. Do+ \\not announce a solution and hunt for confirmation of it.\\Task scope: first distinguish an informational request from a request to\\change or execute something. A request to summarize, explain, or map a\\codebase is complete when you have enough evidence to answer accurately.@@ -154,9 +154,11 @@ pub const full_prompt =\\failing tests, use the named target directly instead of probing unrelated\\indexes first; that dice roll makes every run of the same task different.\\Match the verification to the- \\ask: make the requested thing work and prove it — do not add unrequested- \\tests, coverage, or review passes; thoroughness past the ask is turns,- \\tokens, and diff noise the user did not order. And never repeat a tool+ \\ask: make the requested thing work and prove it — a script that computes+ \\an answer is its own proof, so do not re-derive it a second way — and do+ \\not add unrequested tests, coverage, or review passes; thoroughness past+ \\the ask is turns, tokens, and diff noise the user did not order. And+ \\never repeat a tool\\call with identical parameters once you have a usable result — the answer\\will not change; reread only on stale source, ambiguity, or failure.\\When a Project layout segment is present, it is the tree — read the@@ -170,12 +172,11 @@ pub const full_prompt =\\it and continues with its result. A reply that ends with nothing running\\ends the run, so end that way only when the task is done.\\- \\Before a large chunk of work, give a one- or two-sentence heads-up on what- \\you are about to do; on long tasks, drop a brief note as each phase lands.- \\Put that text in the SAME response as the tool calls it introduces: a- \\response that is only tool calls shows the user nothing but a spinner.- \\Before a command that can run for minutes (a build, a test suite, a push- \\whose hooks run tests), say so and what it is waiting on.+ \\Before a large chunk of work, give a one-line heads-up (a dozen words at+ \\most) in the SAME response as the tool calls it introduces; on long tasks,+ \\one short line as each phase lands. Before a command that can run for+ \\minutes (a build, a test suite, a push whose hooks run tests), say so in+ \\one line.\\With todo_write, mark an item in_progress when you start it and completed\\as it lands, not in a batch at the end.\\diff --git a/src/prompt_text.zig b/src/prompt_text.zigindex e3131355..c2cab7f7 100644--- a/src/prompt_text.zig+++ b/src/prompt_text.zig@@ -26,9 +26,9 @@ pub const intro_note =\\a tool, a parameter, or a wrapper API around one, and never assume a\\capability that is not listed for you — when the thing you want is absent,\\say so and finish the task with what is here.- \\Inspect before you commit to an architecture: say what you found, then- \\what you will do, then do it. Do not announce a solution and hunt for- \\confirmation of it.+ \\Inspect before you commit to an architecture: in one short line (a dozen+ \\words at most), say what you found and what you will do, then do it. Do+ \\not announce a solution and hunt for confirmation of it.++ @import("task_intent.zig").guidance;/// Gate: `caps.local_tools`. #330 `--no-local-tools` hard-removes bash,@@ -219,9 +219,11 @@ pub const work_note =\\failing tests, use the named target directly instead of probing unrelated\\indexes first; that dice roll makes every run of the same task different.\\Match the verification to the- \\ask: make the requested thing work and prove it — do not add unrequested- \\tests, coverage, or review passes; thoroughness past the ask is turns,- \\tokens, and diff noise the user did not order. And never repeat a tool+ \\ask: make the requested thing work and prove it — a script that computes+ \\an answer is its own proof, so do not re-derive it a second way — and do+ \\not add unrequested tests, coverage, or review passes; thoroughness past+ \\the ask is turns, tokens, and diff noise the user did not order. And+ \\never repeat a tool\\call with identical parameters once you have a usable result — the answer\\will not change; reread only on stale source, ambiguity, or failure.\\When a Project layout segment is present, it is the tree — read the@@ -248,16 +250,16 @@ pub const background_note =/// step with bare function calls (Gemini flash: no text in any of 259/// tool-calling responses) satisfied that by thinking it, and a multi-minute/// hook run read as a hang. Now it says where the words go and what earns-/// a warning.+/// a warning. ADR 0239: one line, not two sentences — narration is output+/// every call pays for, and a call's time tracks the tokens it writes.pub const headsup_note =\\\\- \\Before a large chunk of work, give a one- or two-sentence heads-up on what- \\you are about to do; on long tasks, drop a brief note as each phase lands.- \\Put that text in the SAME response as the tool calls it introduces: a- \\response that is only tool calls shows the user nothing but a spinner.- \\Before a command that can run for minutes (a build, a test suite, a push- \\whose hooks run tests), say so and what it is waiting on.+ \\Before a large chunk of work, give a one-line heads-up (a dozen words at+ \\most) in the SAME response as the tool calls it introduces; on long tasks,+ \\one short line as each phase lands. Before a command that can run for+ \\minutes (a build, a test suite, a push whose hooks run tests), say so in+ \\one line.;/// Gate: `caps.todos`. Same tool as `todo_note`; separate because it sits in adiff --git a/src/schema.zig b/src/schema.zigindex de139e48..e4936f11 100644--- a/src/schema.zig+++ b/src/schema.zig@@ -55,7 +55,7 @@ pub const base_specs = [_]ToolSpec{.{ .name = shell_tool.tool_name, .desc = shell_tool.tool_desc, .schema = shell_tool.tool_schema },.{.name = "read_file",- .desc = "Read a UTF-8 text file or view a PNG/JPEG/GIF/WebP image up to 5 MiB. Read images one at a time; pixels reach the next model request when vision is supported. Call this before editing any text file. For a read-only exact-key lookup, pass contains to return only matching numbered lines instead of the whole file. Whole-file reads over 256 KiB return a short preview; pass start_line/end_line (1-based, inclusive) for a byte-exact window from any size file.",+ .desc = "Read a UTF-8 text file or view a PNG/JPEG/GIF/WebP image up to 5 MiB. Read images one at a time; pixels reach the next model request when vision is supported. Call this before editing an existing text file; a file you are about to create needs no read. For a read-only exact-key lookup, pass contains to return only matching numbered lines instead of the whole file. Whole-file reads over 256 KiB return a short preview; pass start_line/end_line (1-based, inclusive) for a byte-exact window from any size file.",.schema =\\{"type": "object", "properties": {"path": {"type": "string", "description": "File path, relative to the working directory"}, "start_line": {"type": ["integer", "null"], "description": "Optional 1-based first line to return (byte-exact slice; omit or null for whole file)"}, "end_line": {"type": ["integer", "null"], "description": "Optional 1-based last line to return, inclusive; omit or null for whole file"}, "contains": {"type": ["string", "null"], "description": "Optional exact literal; return only matching lines with line numbers instead of the whole file. Prefer this for exact-key read-only lookups. Omit, null, or empty for a whole-file or window read. Cannot combine a nonempty value with start_line, end_line, or compact."}, "compact": {"type": ["boolean", "null"], "description": "Exploratory only: return a comment/blank-stripped view via codedb (line numbers shown). Omit, null, or false for a byte-exact read. NEVER use before an edit — re-read without compact to copy exact text."}}, "required": ["path"]},