File Paths, Line Numbers, and Scaling Factors

"Rebalance the scoring" is a ticket, not a spec. "Change grok_feed.py line 274 from deviation * 30.0 * multiplier to deviation * 35.0 * multiplier" is a spec. The difference is between three attempts and one — and the difference compounds across every sub-agent dispatch.

The Three Precision Fields

Every mechanical code change in a spec needs three pieces of information:

1. File path — relative or absolute, but unambiguous. src/scoring/grok_feed.py beats grok_feed.py which beats the Grok file.
2. Line number — the specific line where the change happens. Include surrounding context (function name, section header) in case the line has shifted.
3. Exact value — the literal before and after. Not "increase Grok," not "bump it up." The exact constant or expression.

With all three, the agent executes. Without any of them, the agent interprets. Interpretation is where drift happens.

Inline Diagram — Precision vs Vagueness

The Anchor Strategy

Line numbers are fragile. The line where a bug lives today may shift by the time the agent reads the file. The mitigation is to provide anchors — surrounding context that lets the agent re-locate the target even if the exact line has moved.

Good anchor:

Change line 274 in grok_feed.py, inside calculate_grok_contribution(), where the return statement is return deviation * 30.0 * multiplier.

The function name and the exact source of the line let the agent grep if line 274 has shifted to 277. Anchors are cheap to add and buy robustness against file drift.

Exact Values Are the Author's Job

The author of the spec has the context to decide what the new value should be. They have seen the data, built the ceiling analysis, run the backtest. The sub-agent has none of that context and no cheap way to acquire it. Asking the agent to "pick a reasonable value" is asking it to guess — and guessing is how divergent PRs happen.

What This Eliminates

A precision spec eliminates:

• Clarification round-trips — the agent does not ask "which file?" or "by how much?" because those questions are already answered.
• Divergent interpretation — there is no room for the agent to choose a different value than what the author intended.
• Wasted backtests — the agent does not spend time exploring alternative weights when the author already knows the right ones.
• Stale line drift — the anchor strategy provides a re-anchoring path if the file has changed.

The result is the Hermes PR #28 experience: one dispatch, one PR, one merge.

The Rule

File path, line number, exact value. Every mechanical change includes all three. Every numerical value is the one the author has already decided is correct. The agent applies the diff — nothing more.