> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tiny-brain.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Fixes

> The bug-tracking document: reproduction, root cause, test plan, resolution

A fix is a tracked bug with its own document and tasks. Created with:

```bash theme={null}
tiny-brain work add fix login-timeout "Login times out on slow networks"
```

The frontmatter (CLI-owned at creation) carries `id`, `uuid`, `title`,
`status`, `severity`, and `reported`. Two fields are **added by you at
resolution time**: `resolved:` (ISO timestamp) and a `resolution:` block.

## Status lifecycle

Fixes have four statuses:

```
not_started → in_progress → completed
                          ↘ superseded
```

`completed` has a hard rule: **every** task must be either `completed` (with
a `commitSha`) or `superseded`. Three completed + two superseded = a
completed fix; one task still open = the fix stays `in_progress`.

## Body sections

The CLI scaffolds Issue Summary, Reproduction, and a Tasks placeholder. The
sections worth adding:

* **Reproduction Steps / Expected / Actual** — the bug, pinned precisely.
* **Root Cause Analysis** — the code path and the logic error, plus affected
  files. (Remember the parser rule: no `### N.` numbered headings outside
  `## Tasks`.)
* **Test Plan** — three tables: 🔒 regression tests that must pass
  unchanged, ✏️ amended tests whose expectations change, and 🆕 new tests
  the fix adds.
* **Tasks** — same [task-block syntax](/markdown-format/features) as
  features; commits reference them with `Fix:` + `Task:` headers instead of
  `PRD:`/`Feature:`.

## The resolution block

When the last task closes, the frontmatter gets the outcome:

```yaml theme={null}
status: completed
resolved: 2026-07-12T16:40:00.000Z
resolution:
  rootCause: Session token refresh raced the request retry
  fix:
    - Serialised refresh behind a mutex
    - Added regression test for the race
  filesModified:
    - src/auth/session.ts
    - src/auth/session.test.ts
```

Then re-sync (`tiny-brain task sync docs/fixes/login-timeout.md`). The fix
document ends its life as a complete record: what broke, why, how it was
proven fixed, and which commits did it.