Problem
RESEARCH.md's "How to use this document" section prescribes this format for an
Implementations entry:
**Implementations.**
- PR #N (one-line summary): shipped YYYY-MM-DD. Observed effect: pending — needs N cycles of data.
CLAUDE.md requires that entry to be added in the same PR that implements the
finding ("also add (or update) an Implementations entry under that finding with
the PR number, the date shipped"). Those two requirements are in tension: the date
a PR ships is not knowable while that PR is still being written. The only value
available at authoring time is the current date, which is correct only if the PR
merges the same day.
Nothing catches the entry when it does not. scripts/check_docs.py does not
inspect Implementations entries at all, so a wrong ship date passes CI silently,
and the error is self-concealing: once merged, the entry looks exactly like a
correct one.
Observed instance
PR #119 was opened on 2026-08-16 and its entry was dated shipped 2026-08-16. The
PR was still open on 2026-08-22, at which point RESEARCH.md on that branch
recorded a ship date for a change that had not shipped. The date was corrected to
2026-08-22 during that cycle, which is itself only an approximation — the PR is
gated on a human able to run the manual /create-dev-loop anchor, so it may well
merge later still.
The same tension applies to every entry, not just this one; entries whose PR
happened to merge on the day it was authored are accurate by coincidence rather
than by construction.
Suggested directions
Offered as options rather than a decision, since this is a convention choice for
the maintainer:
- Record what is actually known. Change the format to name the date as the
date the entry was authored (e.g. entry added YYYY-MM-DD), which is always
true at write time, and drop the claim about shipping.
- Defer the date. Write
shipped: pending in the implementing PR and fill in
the real date in a follow-up, the way "Observed effect: pending" is already
handled. This has the advantage of matching an existing convention in the same
entry, at the cost of a second edit per finding.
- Keep the current format and add a mechanical check. Have
check_docs.py
compare each entry's date against the merge date of the PR it names. This is
the only option that would have caught the observed instance automatically, but
it requires network access from a check that is currently offline and purely
textual — likely a poor trade.
Option 1 or 2 appears preferable to 3. Whichever is chosen, CLAUDE.md's
"Grounding work in research" section and RESEARCH.md's "How to use this
document" section both restate the format and would need to be updated together;
note that editing CLAUDE.md requires separate authorization, so that half may
need to be handled by the maintainer directly.
Existing entries do not need retroactive correction under options 1 or 2 unless
one is found to be wrong, which is out of scope here.
This issue body was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).
drafted by Claude on behalf of Daniel Stephenson
Problem
RESEARCH.md's "How to use this document" section prescribes this format for anImplementations entry:
CLAUDE.mdrequires that entry to be added in the same PR that implements thefinding ("also add (or update) an Implementations entry under that finding with
the PR number, the date shipped"). Those two requirements are in tension: the date
a PR ships is not knowable while that PR is still being written. The only value
available at authoring time is the current date, which is correct only if the PR
merges the same day.
Nothing catches the entry when it does not.
scripts/check_docs.pydoes notinspect Implementations entries at all, so a wrong ship date passes CI silently,
and the error is self-concealing: once merged, the entry looks exactly like a
correct one.
Observed instance
PR #119 was opened on 2026-08-16 and its entry was dated
shipped 2026-08-16. ThePR was still open on 2026-08-22, at which point
RESEARCH.mdon that branchrecorded a ship date for a change that had not shipped. The date was corrected to
2026-08-22 during that cycle, which is itself only an approximation — the PR is
gated on a human able to run the manual
/create-dev-loopanchor, so it may wellmerge later still.
The same tension applies to every entry, not just this one; entries whose PR
happened to merge on the day it was authored are accurate by coincidence rather
than by construction.
Suggested directions
Offered as options rather than a decision, since this is a convention choice for
the maintainer:
date the entry was authored (e.g.
entry added YYYY-MM-DD), which is alwaystrue at write time, and drop the claim about shipping.
shipped: pendingin the implementing PR and fill inthe real date in a follow-up, the way "Observed effect: pending" is already
handled. This has the advantage of matching an existing convention in the same
entry, at the cost of a second edit per finding.
check_docs.pycompare each entry's date against the merge date of the PR it names. This is
the only option that would have caught the observed instance automatically, but
it requires network access from a check that is currently offline and purely
textual — likely a poor trade.
Option 1 or 2 appears preferable to 3. Whichever is chosen,
CLAUDE.md's"Grounding work in research" section and
RESEARCH.md's "How to use thisdocument" section both restate the format and would need to be updated together;
note that editing
CLAUDE.mdrequires separate authorization, so that half mayneed to be handled by the maintainer directly.
Existing entries do not need retroactive correction under options 1 or 2 unless
one is found to be wrong, which is out of scope here.
This issue body was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).
drafted by Claude on behalf of Daniel Stephenson