docs: prune TODO.md, and correct four claims that were no longer true
TODO.md becomes a TODO again: only work that is actually queued. Five of
its seven sections were finished work, and their reasoning has permanent
homes — the rules moved to AGENTS.md (the baked rates seed a new dataset
only, never a fallback), the rest is in the commit messages and the
specs. 215 lines to 131.
The four corrections, all of them things a reader would have believed:
- README said the install prompt could not work because the manifest
"only ships an SVG icon". It has shipped 192x192 and 512x512 PNGs since
f50c65b. Now stated as unverified rather than incomplete, which is what
it actually is.
- TODO said no browser had seen the two rule-editing surfaces, while its
own section 5 listed both as seen and confirmed.
- TODO said "merged to main" when the last three commits were on a
branch.
- scripts/screenshot.ts explained its own existence by saying
ARCHITECTURE.md and TODO.md claim no browser can run here. Both now say
the opposite — partly because of that script.
ARCHITECTURE.md's gotchas section now says AGENTS.md holds the
enforceable form of those rules and this holds the mechanism, so a reader
hitting the overlap knows which is canonical.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
1 parent
824c2f5f59
commit
a039176aa3
4 files changed
+117
-180
No files matched your search
+10
-2
@@ -126,6 +126,10 @@ Adding a "missing" guard here is a regression, not a fix:
|
||||
|
||||
## Gotchas paid for with real bugs
|
||||
|
||||
`AGENTS.md` §2 carries the enforceable one-line form of these, with the test
|
||||
that fails when each reappears. What follows is the *mechanism* behind them,
|
||||
which is the part worth reading once.
|
||||
|
||||
- **Never read `event.target.value` inside a `mutate()` callback.** `mutate`
|
||||
defers behind the queue and a write; React resets a controlled input's DOM
|
||||
value long before the callback runs, so you read the *old* value and commit
|
||||
@@ -175,7 +179,11 @@ timing that happy-dom does not reproduce.
|
||||
|
||||
## Where the reasoning lives
|
||||
|
||||
- `AGENTS.md` — the rules, in enforceable one-line form, and which test fails
|
||||
when one is broken. This file holds the reasoning; that one holds the rule.
|
||||
- `docs/PRODUCT.md` — durable product truth: who it is for, what must never break.
|
||||
- `docs/TODO.md` — queued work, with the reasoning behind each decision already made.
|
||||
- `docs/specs/` — design decisions and the alternatives rejected.
|
||||
- `docs/TODO.md` — what is *still* queued, each item carrying the reasoning already
|
||||
settled. Finished work is not kept there; it is in the commit messages.
|
||||
- `docs/specs/` — design decisions and the alternatives rejected, one document
|
||||
per piece of work.
|
||||
- `docs/plans/` — task-by-task implementation plans.
|
||||
Reference in new issue
Block a user