About the decision log
Heatwave records staged work and architectural decisions as dated task plans
under doc/tasks/ (filename convention YYYYMMDDHHMM_NAME.md). That directory
is a decision-log archive, not day-to-day reference — it stays in the repo
and in git history, and is deliberately excluded from this portal as a whole.
This section surfaces a small, curated set of those records that read as
durable architecture decision records (ADRs) — the kind of “why is it like
this?” context worth keeping a click away. The rest of the archive lives in
doc/tasks/ in the repository; browse it there (or via
git log -- doc/tasks/) when you need the full history.
What belongs here
Section titled “What belongs here”A task doc is worth promoting into this curated list when it:
- explains a decision that still governs the system today (not a one-off chore),
- documents a trade-off, rejected alternative, or migration strategy, and
- is unlikely to be superseded within a release cycle.
To add one, register it in the Decision Log section of
docs-site/scripts/docs-manifest.mjs with a slug and nav label, exactly
like the curated records already listed there. Operational runbooks rescued
from doc/tasks/ (DB failover, HAProxy routing, …) instead live under
Managing Production → Runbooks / Database.
How task docs are created
Section titled “How task docs are created”When starting non-trivial work, scan doc/tasks/ for the most recent files to
understand what is queued, and file new staged plans there rather than in long
chat threads. See the toolchain and conventions sections of this portal, and
AGENTS.md, for the full workflow.