todo-triage

The backlog lives in TODOs.md files, one per area. This skill is the procedure for putting things into them and keeping them honest.

Read the root TODOs.md first. It owns the item format and the placement rule. This skill assumes both. It is the contract. This file is only the process.

Never invent structure. If a job here seems to need a new field, section, or file, change the root TODOs.md and say so. Do not improvise it into one area's file.

The weekly pass

The weekly automation runs the whole job in one go. The order matters. The backlog is the source of truth, and the report is written from it, so the report comes last.

1. Drain INBOX.md — see below.
2. Re-verify the open backlog, area file by area file. Close what shipped, correct line numbers that have moved, drop claims that are no longer true. This is the bulk of the work.
3. Review the week's new surface — the commits and merged PRs landed since the last audit's header date — and file what you find, tagged (audit <date>).
4. Rewrite MODULE_AUDIT.md from what the backlog now says — see below.
5. Update the docs the week invalidated: a module's README.md / AGENTS.md when its architecture, public API, or a documented behavior changed. The root AGENTS.md when a global rule, a target, or the build/test flow did. Run ./sync-agents afterwards if any AGENTS.md changed.
6. Push the branch and open a PR ready-for-review. Follow the github-workflow skill. Describe the end state: what moved in the backlog, what the audit now says, and what you verified rather than assumed.

An ad-hoc run — someone asking you to triage the inbox or file a finding — is just the relevant section below, not the whole pass.

Draining the inbox

INBOX.md holds raw human notes: terse, uncited, unverified, sometimes already fixed. Take each entry under # Open in turn.

1. Understand what's being claimed. An entry like "Raw data browser (similar to SD browser)" is a feature ask. "why do we delete all the DB entries on logout?" is a question that can or cannot hide a bug. Resolve which before going further.
2. Verify it against current source. Find the code. Make sure that the behavior is really what the note says, and that it hasn't already been fixed or already been filed. This is the step that earns the promotion. An entry that reaches a TODOs.md unverified is worse than one still sitting in the inbox, because it now reads as established.
3. Expand it. Write the body the root format asks for: the File.swift:123 sites, why it matters (user-visible consequence, not just tidiness), and a concrete suggested fix. Preserve the human's intent. If the note asks a question you now know the answer to, answer it in the body rather than restating the question.
4. Route it by the placement rule: the lowest TODOs.md spanning every area it touches. Create that area's file if it doesn't exist yet (copy the header shape from a sibling; link to the root format, don't restate it).
5. Bucket and tag it. PX/P0/P1/P2, plus quick-win or needs-design. Tag the origin (human <date the note was written>). Keep the human's date, not today's. The point is to show where the item came from. A new item takes the bucket its severity implies (high → P0, medium → P1, low → P2). An item already in the file keeps the bucket it has. Priority is a decision someone made. A severity opinion from a later pass doesn't get to silently overrule it. Argue for the move in the body instead.
6. Remove it from INBOX.md. The origin tag is the trail. Don't leave a copy behind.