# Context Hygiene and Agent Handover

## Purpose

Prevent context rot from moving between agents. A handover should help the next agent resume work, not transmit every prior thought, assumption, or mistake.

## Core Rule

Handovers are evidence indexes, not memory dumps.

A new agent should trust durable artifacts only after verification against source files, git status/diff, logs, command output, tickets, specs, or live system state.

## Failure Modes to Avoid

- Over-contexted agents writing long narrative handovers full of stale assumptions
- New agents accepting prior conclusions without verification
- Dirty working trees with no owner or intent
- Partial infrastructure changes with no rollback notes
- Large documentation blobs that must be reread entirely
- Mixing unrelated projects in one repo/worktree
- Software and DevOps state described in the same vague summary

## Progressive Disclosure Model

Use layered documentation so agents load only what they need.

### Layer 0: Startup Instructions

Small durable rules loaded automatically:

- `AGENTS.md`
- current ticket
- current phase artifact

### Layer 1: Indexes

Short files that point to deeper docs:

- `README.md`
- `docs/operating-system.md`
- `projects/index.md`
- `systems/inventory.md`
- `tickets/README.md`

### Layer 2: Task Artifacts

Scoped artifacts for one ticket/task:

- ticket file
- `tickets/artifacts/<ticket-id>/00-context.md`
- `01-questions.md`
- `02-research.md`
- `03-design.md`
- `04-structure.md`
- `05-plan.md`
- `06-review.md`

### Layer 3: Deep References

Only load when needed:

- runbooks
- full specs
- service configs
- logs
- historical session summaries
- external documentation

## Clean Handover Requirements

A handover must be short, factual, and source-linked.

It should include:

1. Task/ticket ID
2. Current status: planned / in progress / blocked / done / failed
3. Exact files changed
4. Exact commands run, if important
5. Verification performed
6. Verification not performed
7. Known risks or suspected mistakes
8. Next recommended action
9. Rollback notes
10. Links to artifacts, logs, or diffs

It should not include:

- Long reasoning transcripts
- Unverified claims stated as facts
- Broad unrelated context
- Hidden assumptions
- Attempts to solve future phases prematurely

## Prior-Agent Trust Policy

Treat prior handovers as leads, not truth.

Before continuing work, the new agent should run a bounded recovery preflight:

```sh
git status --short
git diff --stat
```

Then inspect only files related to the ticket or dirty changes.

If dirty files unrelated to the requested task already exist, do **not** add new implementation work to the same tree by default. Choose one of:

1. stop and triage the dirty work;
2. create/use an isolated branch or worktree;
3. use a separate clone/repo for the new task;
4. proceed in-place only with explicit user approval or for narrow recovery/documentation work.

For infrastructure work, verify live state separately before acting.

## Terminated-Agent Recovery Checklist

When an agent terminates mid-task:

- [ ] Identify the intended ticket/task
- [ ] Record current git status
- [ ] List changed/untracked files
- [ ] Inspect diffs for only relevant files
- [ ] Identify whether live infrastructure was changed
- [ ] Check relevant logs or service status if live systems may have been touched
- [ ] Classify each change: keep / revert / move / unknown
- [ ] Update the ticket with recovery notes
- [ ] Do not continue implementation until scope and next action are clear

## Context Budget Rules

Conserving context intelligently is mission critical.

- Prefer locator/researcher/reviewer subagents over loading large context into the main agent.
- Use subagents proactively for context-heavy discovery, diff review, and summarization; the parent should receive concise, cited findings rather than raw dumps.
- When subagent prompts/templates are used repeatedly, improve the subagent instructions themselves so context-conservation behavior becomes durable rather than manually re-prompted each time.
- Ask subagents narrow questions and require source paths/commands, not broad reasoning transcripts.
- Use `rg`, `find`, scripts, indexes, artifact paths, and command filters before reading whole directories or large files.
- Avoid filling the main context with long shell outputs; redirect large outputs to files or ask subagents to summarize.
- Read files by targeted ranges when possible.
- Keep handovers under roughly one screen unless the task is incident-level.
- Put detailed evidence in artifacts; put summaries in tickets.
- Use linked markdown notes as the first knowledge system; consider vector/RAG only after documents are structured and indexed.

## Subagent Use Pattern

For recovery or messy work:

1. Locator subagent: identify relevant files/artifacts only.
2. Researcher subagent: gather facts from those files and command outputs.
3. Reviewer subagent: assess diffs against the ticket/spec.
4. Main agent: decide next action with the user.

Write-capable subagents should be avoided during recovery unless there is a clear plan and clean git state.

## Scripting / Retrieval Direction

Prefer a staged approach:

1. Markdown index pages and backlinks
2. `rg`/scripted search helpers
3. Generated inventories, e.g. tickets/services/hosts indexes
4. SQLite or JSON metadata index
5. Vector database/RAG for semantic retrieval, with citations back to markdown files

RAG should retrieve sources; it should not replace source-of-truth docs.