Skip to main content
A fix is a tracked bug with its own document and tasks. Created with: 
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 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: 
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.