Session State

File location and format

One file per task: docs/state/<task-slug>.md. Four sections, always in this order, always present even if empty (write "none yet"):

# <task-slug>

## Decisions
- <date/turn> — <decision> — <one-line why>

## Files touched
- <path> — <what changed, one line>

## Next step
<the single next action, stated so a fresh session with no other context
could execute it. Not "continue the refactor" — "run
`npm test -- billing.spec.ts`, fix the 2 failing assertions listed in
Decisions, then move to the pricing module.">

## Open questions
- <question> — <who/what resolves it>

Update triggers (write to the file, don't just hold it in context)

1. Before proposing or executing /clear.
2. When session-hygiene flags the context is near compaction.
3. At each natural checkpoint: a phase transition (Explore→Plan, Plan→Code), a passing test run, a merged/committed chunk of work.
4. Immediately before spawning a subagent for a related piece of work — write the handoff artifact (below) referencing this file.
5. On session end for any task not fully closed out.

Handoff artifact (agent-to-agent, via the Task tool)

When spawning a subagent to continue or take a slice of this task, pass a self-contained brief — the subagent has no memory of this session:

## Objective
<what this subagent must accomplish, one or two sentences>

## Constraints
- Allowed paths: <explicit list, not "the codebase">
- Must not: <hard bans carried over from this task, e.g. "do not modify
  the test file", "read-only, report only">

## Prior decisions (from docs/state/<task-slug>.md)
<paste the Decisions section verbatim — don't summarize away specifics>

## Definition of done
<machine-checkable: the exact command(s) that must pass>

Resume procedure (start of a session that has a matching state file)

1. Read docs/state/<task-slug>.md in full before touching any code.
2. Treat "Next step" as the literal starting instruction, not a suggestion to re-derive from scratch.
3. If Decisions and current code disagree (code changed since last write), say so before proceeding — don't silently trust a stale file.

Anti-patterns

• Writing "Next step: continue" — if it can't be executed by a reader with zero other context, it isn't done.
• Letting the file grow unbounded: prune resolved Open questions and superseded Decisions on each update rather than only appending.