DEV Community

Cover image for Quick Win Card #03 — Your sub-agent never read your MEMORY.md (the 5-line brief header that fixes it)
Michel Faure
Michel Faure

Posted on • Originally published at dev.to

Quick Win Card #03 — Your sub-agent never read your MEMORY.md (the 5-line brief header that fixes it)

Quick Win Card #03 strip — Michel writes a brief to his sub-agent, sub-agent codes, Niran reads git log: commit on main, Michel adds a Load-bearing feedbacks section at the top of the brief.

The hook

QW-01 said: your status file lies. QW-02 said: your counter lies. Here's the third layer: your sub-agent doesn't know what you know. Not out of malice — by construction. The context it receives is your brief, full stop. Not your MEMORY.md, not your user-scope feedbacks, not the doctrine you've accumulated over 70 days. You talk to it like a colleague who's read the wiki, when it has just walked in and never opened the page.

What broke

May 18, late afternoon. I delegate six files to my ERP sub-agent — first-contact autosend, ADR-0072. Three-paragraph brief: context, deliverables, phase-0 grep audit before any INSERT. Short, clean, what I'd give a human who knows the project.

Forty-five minutes later, the report lands. I grep my git log out of reflex: commit 3756e63 went straight to main, six files, seven hundred thirty insertions, no feature branch, no pull request. Thirty minutes of cherry-pick to recover. And the rule that should have prevented this — feedback_git_branch_check_avant_commit — was indeed in ~/.claude/agent-memory/, user scope, indexed in my MEMORY.md. I consult it mechanically before every non-trivial commit since the May 14 incident. It didn't betray me. It just never reached the delegate.

The lesson is more uncomfortable than the first two cards. You can build the most rigorous doctrine in the world, index it, version it, backport it across projects — if the brief you send to the sub-agent doesn't cite it explicitly, it is effectively absent. User-scope memory doesn't transmit by inheritance. The sub-agent isn't an heir, it's a subcontractor who hasn't read your wiki.

Fair objection here: GitHub branch protection at the repo level would also catch the commit-on-main case. True for that one example. But the doctrine has to hold even in repos where you haven't wired the protection — and more importantly, the other two feedbacks in the example below (DB probe before DELETE, inscriptions.source audit) have no equivalent server-side guardrail. That's precisely the category the brief needs to cover, because no other layer will.

The brief header that closes the class

Paste this at the top of any sub-agent brief that touches application code, runs longer than thirty minutes, or delegates a decision that could break a silent rule. Three to five load-bearing feedbacks (in Counterpart vocabulary, a feedback = a codified rule extracted from a past incident, stored in MEMORY.md, named with a stable slug).

# Sub-agent brief — <task name>

## Load-bearing feedbacks (apply BEFORE any code)
- `feedback_git_branch_check_avant_commit``git branch --show-current`
  before every non-trivial commit; feature branch + PR for any new feature.
- `feedback_audit_db_pre_flight_canonique``SELECT … GROUP BY` probe
  before any bulk DELETE/UPDATE.
- `feedback_source_audit_inscriptions` — never touch `inscriptions.source`
  rows where source ∉ {NULL, 'migration_notes'}.

## Context
<the brief itself>
Enter fullscreen mode Exit fullscreen mode

Three named feedbacks at the top of the brief. Not the content — just the slug plus one operative sentence. If the sub-agent wants the detail, it opens the file. But the explicit invocation is enough to bring the rule back into its active context. A rule cited by name is a rule considered. A rule that lives in your MEMORY.md and nowhere else is a rule that doesn't exist for your delegate.

ROI

Not time saved on the delegation itself — the brief grows by a few lines, which is neutral. The gain is downstream. Thirty minutes of cherry-pick avoided per commit-on-main mishap. Half a day of DB audit avoided per bulk-DELETE-without-probe. An entire category of silent fail-modes drops out of incident scope because it's named in the brief before code is written. The header doesn't replace the doctrine — it makes it operative for the delegate who has no direct read access to it.

Apply now

Open the next brief you're about to send to a sub-agent. At the top of the file, before the context, paste the ## Load-bearing feedbacks block with three feedbacks relevant to the task. Picking the three is the exercise — it's what makes visible which part of your memory is load-bearing for this specific delegation. If you can't decide which three to cite, your brief is probably too vague to be delegated. In which case the pattern's benefit lands before the sub-agent even starts working: it forced you to re-clarify your intent.

Your quick win takes five minutes — the time to identify the three feedbacks to inline. The doctrine doesn't follow you into delegation on its own. You have to carry it.


Quick Win Card series, episode 03. Counterpart Toolkit v0.7, amendment R9 promoted 20/05/2026. Doctrine repo: github.com/michelfaure/doctrine-counterpart. Triptych QW-01 → QW-02 → QW-03: status file lies, counter lies, delegate's context lies. Three layers of observability that lie by default, three hooks that force them to speak.

Top comments (1)

Collapse
 
bickov profile image
Alex @Bickov

The brief-header idea maps to something I keep relearning: agents act on what's structured, not what's implied. A 5-line header beats a long MEMORY.md the agent skims, the same way structured context beats a wall of prose it has to interpret. Do you version the header per task, or keep one canonical block?