Review a change

Reviews cost several agent runs. Run them when the owner says the change is ready, or asks. During work, npm run verify is the check.

1. Prepare

1. npm run verify passes.
2. List the untracked files (git ls-files --others --exclude-standard): they reach the reviewers and Doistbot's model providers. Gitignored files (.env, .tmp/) are not listed, and npm run review:worktree never copies them. Check every listed file for credentials, tokens and personal data; send none that holds them, and ask the owner about any file that does or that doesn't belong to the change. Never git add -A to tidy up.
3. Write the brief from references/reviewer-brief.md: the task in the owner's words, what done means, the decisions made. Never your own opinion of the change, or your reasoning.

Done when the brief is written and the tree holds only the change, with no secrets or personal data in it.

2. Run the reviews in parallel

• Task review, always: a fresh subagent with the brief and the diff. It looks for missing pieces, unrequested changes, unhandled cases, tests that would pass with the feature broken, and, in a refactor, any changed test input or assertion. Doistbot can't do this: it never sees the task.
• Blast-radius review, when the change alters code others rely on: src/lib/, command registration, global flags or argv handling in src/index.ts, the @doist/cli-core or @doist/todoist-sdk version, other package.json dependencies, build or CI config. It names the one fact that makes the change safe and proves it by running code. It looks where text search stops: library versions in package-lock.json, the shape of API responses, scripts and installed skills reading --json output, extensions receiving TD_* variables.
• Code review: Doistbot if it is set up (below). Otherwise one subagent per relevant check in .agents/checks/, each with the brief and that check.

Every brief says: the shared working tree is read-only. A reviewer that needs to run or break code makes its own copy with npm run review:worktree -- <dir>, then npm ci in it, and removes it after.

3. Doistbot locally

Use it when doistbot --version prints 1.0.12 or newer and doistbot doctor succeeds. Otherwise use the per-check subagents and tell the owner Doistbot was skipped.

• Off the default branch: doistbot review --json. In a stack: doistbot review --base <branch below> --json. Both cover commits, staged and unstaged edits, and untracked files. Nothing needs staging.
• Not doistbot review staged: it skips the branch's commits and still reports verified.
• Read status, verified and providerFailures first. An unverified review, or one with a failed provider, is partial: say so, and cover that gap with a subagent.
• It runs before the Doistbot review on the pull request, not instead of it.

4. Confirm each finding

Reviewers rate findings on the verify ladder. Take each to the rung its claim needs: the cited line for what the diff shows, a failing test or command for a behaviour claim. Then:

• fix it,
• dismiss it with evidence at that rung (the line, the test output), never an argument, or
• leave it open for the owner, saying what would settle it.

Look again when new evidence appears. Done when every finding has one of the three.

5. Fix, verify, re-review

Fix, then npm run verify. A large fix gets its own task review. Report the findings with what happened to each, in the verify report format.