change-log

You changed something in this repository. Before you report the task finished, walk this checklist top to bottom. Every step names the exact file to touch.

The chain

1. docs/STATE.md -- always, if a track's status changed

Open docs/STATE.md. Find the row for the track you touched (DATA, REPORTING, RECONCILIATION, TASKS, or a new one you're adding). Update its Next action cell and its Last touched date. Do not leave a stale next action after finishing it.

git diff -- docs/STATE.md

confirms the row actually changed before you move on -- an empty diff here means you forgot this step, not that nothing needed updating.

2. docs/CHANGELOG.md -- always, when something shipped

Prepend a new entry at the top of docs/CHANGELOG.md, directly under the file's header, above every existing entry (newest-first):

## [YYYY-MM-DD HH:MM] - <one-line title>
### Changed
- <item -- with a path>
### Fixed
- <item -- with a path>
### Added
- <item -- with a path>

Use only the subsections you need. The title should say what changed in plain words.

2a. The task: <ID> field -- reserved for task-completion entries only

If this entry is the one that closes out a tasks/*.md brief (T1, T2, ...), add a literal line directly under the header, before any ### subsection:

## [YYYY-MM-DD HH:MM] - <one-line title>
task: T1
### Changed
- <item -- with a path>

tools/check_task.py's governance gates look for an exact line reading task: T1 (or task: T2) -- not for the word T1 anywhere in the entry. That distinction is load-bearing: an entry that merely describes a fix or a review round naturally contains those tokens in prose, and a substring match would let that prose silently satisfy the gate without the task ever actually being logged as done. It happened once in this repo -- see the CHANGELOG entry titled "Round 2" for the fix.

Reserve this field strictly. An entry that is not closing out a task -- a doc fix, a build phase, a review round, a dependency bump, even one whose prose discusses T1 or T2 at length -- must not include a task: <ID> line. The field means one thing only: an agent is claiming, right now, that this specific task is done. Do not use it for anything else, even when it would be convenient.

3. Learnings -- whenever you learn something reusable

If the change taught a durable lesson -- a gotcha, a root cause, a "check this first next time" -- write it to docs/memory/learnings/<slug>.md as its own file. Do not bury a reusable lesson inside a CHANGELOG entry where the next agent will never find it by searching a topic.

A learning that turns out to be consulted by a later task's checker (see tools/check_task.py T2, which requires docs/memory/learnings/reconciliation-check-batches-first.md to exist and be non-empty) is not decorative -- it is load-bearing. Extend an existing learning file rather than duplicating it when the lesson is the same one, restated.

4. Verify before you claim done

Run the repo's own checkers, bare, never through a pipe (a pipe swaps the exit code you're checking for the exit code of whatever it was piped into):

python tools/check_task.py <TASK>
echo $?

Read the printed exit code immediately after -- not the one you expect -- to confirm the code you're about to report is the one that actually happened.

5. Report format

End your message with the same shape every time, so the state of the chain is visible at a glance:

LOG chain: 1(STATE.md)✓ 2(CHANGELOG.md)✓ 3(learnings)— 4(verified: exit 0)✓

✓ = done. — = not applicable, with the reason stated inline. If a step is neither ✓ nor a stated —, the task is not done -- say what's missing instead of reporting completion.

Decision table