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