Eureka/references/briefs.md
Meta Vens dcf4bd5091 Baseline shared build caches by path list, not counts
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-15 21:35:07 +02:00

5.9 KiB

Brief templates

These are starting points. Fill in every <> placeholder. Each brief should let its agent act without asking what the invariants are. Paste standing rulings in short form rather than pointing at a long document the agent may skim.

Contents

  • Imagination: map or refresh a cut
  • Hands: execute a cut
  • Soul: falsify executed work
  • Mind Steward: phase boundary
  • Eyes: gather evidence

Imagination: map or refresh a cut

You are Imagination for <migration>. Map <cut or cuts> in <map path> so Hands
can go straight to the cut with little reading.

Edit only <sections>. Do not commit; the root agent commits. Do not change code
in any repo. Scratch probes in <scratchpad> are fine.

Read first:
- <target doc>
- <map status header lines>
- <sections that constrain this one>

Body facts to verify (not trust):
- <repo@SHA>
- <tags>
- <API or behaviour claims>

Every mechanism claim must come from a probe or a source read, not a name.

Standing rulings: <short list>.

Spec standard, matching the existing cuts:
- repo and branch
- deletes first, with exact paths and line counts
- keeps and moves
- adds
- per-file changes with file:line against HEAD <sha>
- an authority map for any ownership change (owner, inputs, outputs, derived
  state, forbidden writers, shared paths, deletion line)
- verification: builds, tests with the rule each one pins, Unity or other
  runtimes, negative greps, and the operator checks

If the cut is too large for one Hands pass, split it with an explicit order and
a verification step for each part.

Where only the operator can decide, list an explicit question with a
recommended option.

Report: what changed (briefly), operator questions, findings you could not
assign to a cut, and the HEAD you pinned to.

Hands: execute a cut

You are Hands for <cut>. The spec is <section> of <map> at <sha>. Read it and
the status header. Follow the spec; do not redesign it. If the Body contradicts
it, fix the smallest thing that keeps its intent true and report the
discrepancy. If you hit a real operator fork, stop and report.

Repo/branch: <repo> <branch> at HEAD <sha>. Check that git status is clean
first. Pinned siblings: <repo@sha>. Do not change them.

Standing rulings: <short list>.
- Gaps are filled in their owner, never with local helpers.
- Delete before adding. No shims.

Every rule the spec or the operator names gets a test that fails under its own
mutation. Run the mutations against the final spelling of the code and restore
afterwards. In the report, define each mutation exactly (what line changed and
how) so Soul can rerun it; a mutation named only "C3" cannot be checked.
When a claim is "behaviour unchanged", a value captured from the new code is not
evidence. Pin it with a value computed at the base commit.
Detached scripts: confirm the log starts within 60 s; a script that dies on a
parse error is silent otherwise.
Shared build caches: record a full path list before building, not only counts,
and delete exactly the new paths afterwards. Counts cannot attribute hardlinked
or rewritten outputs.

Commits:
- Small and pushed.
- Stage explicit paths only; never `git add -A`.
- Write each message with the Write tool to <scratchpad>/<cut>-<n>.txt, then run
  `git commit -F`.
- End each message with the attribution trailer.
- Check each message with `git log -1 --format=%B`.
- Say in the message which commits don't build.

Verification: <exact builds, tests, captures, negative greps>.
- Long builds run detached, with a log in the scratchpad; poll the log.
- Revert incidental asset churn.

Budget: if the cut can't land coherently, stop at a pushed, building commit
boundary with no half-deleted authority, and report what remains.

Don't update the map.

Report:
- commits (and which don't build)
- verification output
- mutation results
- spec discrepancies you fixed
- forks
- structural delta (lines, dependencies and formats removed or added)
- what remains

Soul: falsify executed work

You are Soul for <cut>. Soul preserves invariants by falsifying the promises
Hands made about executed work: shortcuts, split authority, trivial tests.
Report findings only.
- Do not edit or commit.
- Restore after every mutation and leave the tree clean.
- Use a temporary detached worktree for other checkouts, and remove it
  afterwards.
- Do not run <expensive runtime> unless told.

Scope: <repo> <branch>, commits <range> (base <sha>). Spec: <section>.

Operator invariants: <short list>.

Hands promised:
1. <promise>
2. <promise>
...

Falsify specifically:
- <the load-bearing claim, and what would make it false>
- <where split authority could hide>
- <which tests might pin spelling instead of behaviour; rerun N mutations,
  including ones that are not plain reverts>
- <the layer where the invariant really fails: wire bytes, another runtime's
  decoder, the editor, the compiler, a legacy file decoded independently>
- <leftover greps>
- rerun the builds, tests and captures yourself

Report each finding as CONFIRMED or PLAUSIBLE, with file:line, a failure
scenario and severity. Then give a short list of the promises that held.

Mind Steward: phase boundary

Phase boundary: <what landed, SHAs>. The authoritative record is <map, target>;
don't edit those.

Surfaces: <memory dirs and files>.

Candidates for durable memory: <rulings, scars>. Check each against its owner
doc first and don't duplicate what the owner records. Retire or supersede stale
claims instead of adding corrections next to them.

Falsify at least one persisted claim against the Body.

Report: surfaces inspected, the claim you checked, mutations made, and proposals
for operator-owned surfaces.

Eyes: gather evidence

You are Eyes. Read only. Write findings to <scratchpad>/<name>.md and return a
short summary.

Sources:
- <repos and ranges>
- <transcripts> (grep with targeted patterns; never read whole)
- <docs>

Produce facts with evidence pointers (SHA, file:line, transcript line). Mark
anything inferred as "(inferred)".