> ## 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.

# Troubleshooting

> The common failures, what they mean, and the fix for each

## My commit was rejected

The gate hooks reject for a handful of reasons; the error says which. The
common ones:

<AccordionGroup>
  <Accordion title="Unrecognised commit type">
    The prefix must be one of the conventional types the hook knows
    (`test:`, `feat:`, `fix:`, `refactor:`, `spike:`, `chore:`,
    `untracked:`). A bare message or a novel prefix is rejected before
    anything else is checked.
  </Accordion>

  <Accordion title="Missing tracking headers">
    A `test:`/`feat:`/`fix:`/`refactor:` commit needs `PRD:`/`Feature:`/`Task:`
    (or `Fix:`/`Task:`) headers. Add them — or, if the work genuinely belongs
    to no plan, commit it as `chore:` or `untracked:`.
  </Accordion>

  <Accordion title="Task: header doesn't resolve">
    The `Task:` value must match the task description in the markdown
    **exactly** (whitespace trimmed). The usual causes: a paraphrased
    description, or no task block with that description exists in the
    feature/fix file (see [task syntax](/markdown-format/features)). Copy
    the heading text from the markdown verbatim.
  </Accordion>

  <Accordion title="refactor: with no active review">
    `refactor:` commits are only accepted while a review is active for the
    task — they're the response to review findings. If you're restructuring
    outside a review cycle, that's part of a task's GREEN work or a new task,
    not a `refactor:` commit.
  </Accordion>
</AccordionGroup>

## The dashboard isn't showing my task

Almost always: `tiny-brain task start` wasn't run before the work began, so
the hooks had nothing to attribute commits to. Start it now — the commits
you make from here attach normally. (Commits made before the start may need
their task's markdown updated by hand and re-synced.)

## Progress state looks wrong

Don't edit the projections. In order:

1. If you've edited plan markdown, re-sync it:
   `tiny-brain task sync <file>` (add `--force` for a full re-sync).
2. In a fresh or divergent clone, rebuild from history:
   `tiny-brain progress rebuild`.
3. Still wrong? `tiny-brain doctor` — failing checks print copy-pasteable
   `Fix:` lines, and `--migrate` runs any pending source-of-truth
   migrations.

## The full test suite ran on my test: commit

It shouldn't — `test:` commits skip tests by design. Run `tiny-brain hooks
status` and look for a competing hook manager (husky, lefthook): either
tiny-brain's hooks aren't the ones git is executing (`hooks status` reports
misrouting and the fix), or another manager's pre-commit is running tests
alongside them.

## `init` refuses to run

`init` preflights the system doctor. Criticals always abort (fix what it
names); warnings abort unless you pass `--ignore-system-doctor`.

## Something else

`tiny-brain doctor` is the first stop for toolchain problems, and the
[dashboard](/getting-started/dashboard) task detail view shows what the
pipeline recorded for a task — often the fastest way to see where a cycle
stalled.