Agent session hygiene

A session is the unit of agent work, and its quality is set in the first minute: what context gets loaded, and whether the session is scoped to one task. This playbook is the day-to-day companion to repo context & memory — that standard defines what lives where; this is how a session actually uses it, and how what the session learns gets deposited rather than lost.

What a session loads

At session start, before any work, the agent reads:

• CLAUDE.md (repo root) — the stable facts: what the repo is, key commands, architecture pointers, the standards that apply.
• memory/ — the gotchas. Hard-won traps, one fact per file; the cheapest velocity in RAPID is a mistake not repeated.
• The relevant runbook — for the area being touched, from docs/runbooks/.
• The ADR directory — accepted decisions are respected, never silently reversed; an agent that hasn't read them will eventually undo one.
• The task brief — intent, constraints, acceptance criteria and files in scope, per the director–builder loop.

Loading is selective, not exhaustive: the gotchas and the runbook for the area in scope, not the whole tree. Context an agent doesn't need is token spend and attention dilution.

The session-start checklist

Mirrored from the scaffold's CLAUDE.md, which every RAPID repo inherits — the scaffold copy is the one agents actually load, so if this playbook and the scaffold ever disagree, fix the drift in the same PR:

1. Read CLAUDE.md, memory/, and the runbook for the area you're touching.
2. Confirm the task brief, acceptance criteria and files in scope.
3. Build → run tests/lint → open a PR with the AI-provenance declaration.

Pending — enforcement by hooks

The scaffold pre-wires agent hooks, so parts of this checklist (auto-loading memory/, lint/test on write) can be enforced mechanically rather than by convention. Which steps are hook-enforced per stack is decided when each golden path is built out — a Guild call, not yet made.

One task, one session

• One agent-sized task per session — the same decomposition the build loop demands. A session that spans tasks accumulates reasoning from the last task that quietly contaminates the next.
• Parallel work means parallel sessions — independent tasks run as separate agents in separate worktrees, never interleaved in one session.
• Long sessions decay. Context windows fill with dead ends, superseded plans and stale file states; the agent starts acting on what was true. Cost rises as quality falls — the worst trade available.

Start clean vs continue

Continue the session when you're mid-correction on the same task — the re-prompt loop is cheap and the accumulated context is genuinely relevant.

Start clean when:

• A new task begins — always, even a related one. Fresh context from CLAUDE.md + memory/ beats a long transcript.
• Three corrections have failed — the build loop's three-strikes rule: the task is wrong (too big, ambiguous, ill-posed). Rewrite the brief and start over; don't prompt harder into a polluted context.
• The agent has internalised a wrong assumption — once a falsehood is in the transcript it keeps resurfacing; restarting is cheaper than arguing.
• The PR merged — the loop is done; the next loop starts from the repo, not from the session that produced the last one.

The rule of thumb: reloading sharp context costs seconds; dragging a stale transcript costs correctness.

Depositing what the session learned

A session that ends without depositing its learnings has spent tokens and banked nothing — this is the Flow-state capital-deposit discipline applied at session grain:

• Gotchas — anything that cost more than ~30 minutes goes into memory/ as one file (symptom → root cause → fix → verification), in the same PR, before the ticket closes.
• CLAUDE.md deltas — if the session revealed a stable fact that's missing or wrong (a command that changed, an architecture pointer that misleads), the PR proposes the edit; it's reviewed like code, because it steers every future session.
• Runbook additions — operational lessons become runbook steps, so the next incident is faster.
• Prompt repetition — a prompt pasted for the third time is a candidate for the prompt library, per toolkit governance.

The human reviewing the PR checks the deposit happened — an insurance-domain gotcha (an MTA edge case, a quirk in an ACORD mapping) captured today is a defect an agent doesn't write next quarter.