# Root-Cause Improvement Template

Use this template when a recurring failure is discovered — the user has had to repeat information, an agent made the same mistake twice, or a process gap caused observable harm.

## 1. Capture the Failure

- Date:
- Operator/agent:
- Ticket/task reference:
- Summary:
- Symptom(s):

## 2. Classify

The failure is primarily a problem of:

- [ ] **Missing memory** — a fact existed but was not recorded anywhere durable
- [ ] **Bad retrieval** — the fact was recorded but the agent did not know where to look
- [ ] **Stale fact** — the fact was recorded but had changed since recording
- [ ] **Poor handover** — an agent terminated mid-task without leaving actionable handoff
- [ ] **Tool gap** — no script, command, or automation existed to find or verify the fact
- [ ] **Unclear policy** — the agent did not know the rule or procedure for this situation
- [ ] **Bad verification** — the agent checked but accepted stale or incorrect evidence
- [ ] **User-preference mismatch** — the agent assumed a default that does not match the user's intent
- [ ] **Other**:

## 3. Root Cause

Why did the agent not know, not verify, or not act correctly?

Trace back from the symptom to the system gap:

```text
Symptom: ...
  → Agent did X (or failed to do X)
    → Because Y was missing/stale/unclear/unreachable
      → The root cause is Z
```

## 4. Patch the System

Target one or more of:

- [ ] `AGENTS.md` — update startup routing, add/update a retrieval-map entry
- [ ] An index file — `systems/`, `infra/`, `projects/`, or a new quick-reference doc
- [ ] A runbook — add missing verification steps or references
- [ ] A template — fix the template that produced the gap
- [ ] A script/retrieval helper — add a targeted search alias or command
- [ ] A ticket/spec process — close a process gap that allowed the failure
- [ ] A subagent prompt — improve a reusable agent instruction

Patch applied:

```text
<Describe exactly what was changed and why>
```

## 5. Add Verification

Future agents should be able to confirm this gap is closed:

```sh
<concrete check commands>
```

Verification of the patch:

```text
<Expected output or behavior>
```

## 6. Keep Entrypoint Light

- Did the patch add a full doc or a pointer? Prefer a pointer unless the doc is essential routing.

## 7. Log

- Logged in: `docs/server-change-log.md` (if operational) / ticket / weekly review