Run a migration across modules without losing intent

The pain

Refactors decay across sessions and across agents. One agent renames a function. Another updates the tests. A third agent comes back two days later to “finish the work” — and silently undoes the architecture decision that triggered the rename in the first place because it never saw the rationale.

The decisions that triggered the refactor are usually in chat scrollback, commit messages, or nowhere. By the time they matter, they’re gone.

The brainclaw move

1. Capture the why before changing surfaces. bclaw_create(entity='decision', data={text: 'rename UserContext → AgentContext because the type now covers both'}) puts the rationale in the project memory, not in a Slack thread.
2. Mark known traps. bclaw_create(entity='trap', data=...) for the patterns the refactor must NOT recreate. Future agents see them in their context before editing.
3. Claim directories, not individual files. A migration touches dozens of files. Claim the whole module: bclaw_work(intent='execute', scope='src/auth/'). The next agent claiming src/auth/ sees yours and waits.
4. Pull the digest before each pass. bclaw_context(kind='memory', path='src/auth/') filters memory to what’s relevant for the current scope — decisions, traps, related plans — so the next agent picks up the intent, not just the diff.

What changes

A refactor stops being a per-session push that one agent might undo on the next session. The intent persists in memory. New agents joining the project read it before touching the code.

When it earns its keep

The bigger the refactor and the more agents involved, the higher the leverage. A 3-line rename doesn’t need this. A 20-file architecture move across 3 sessions does.