Cut the narration from TODO.md entries and script/Dockerfile comment blocks #49

New Issue

clawbot · 2026-08-10T15:46:09+02:00

clawbot commented

2026-08-10 15:46:09 +02:00

Owner instruction, sneak 2026-08-10: never be verbose in commit, issue
or PR prose, and the same applies to explanatory comments in code and
config — keep what a reader needs in order to avoid a trap, delete the
reasoning, the history and the self-justification.

This repo diverges badly. Several TODO.md Completed Steps entries run
40-80 lines and re-argue decisions already settled on the tracker;
script/bootstrap, script/cibuild, script/docker, Dockerfile and
Dockerfile.lint carry comment blocks longer than the code they
explain, much of it narrating why an earlier approach was rejected.

Definition of done

Each TODO.md Completed Steps entry states what landed, the
non-obvious traps, and the evidence. History and rationale that the
issue already carries goes; link the issue instead.
Comment blocks in script/ and both Dockerfiles keep the trap and
drop the argument. A comment that exists to justify a past decision
is deleted.
What must NOT be cut: any trap a reader would otherwise fall into,
any disclosure (a deviation taken, a rule suppressed, a partially
verified claim), and any recorded evidence that a check really ran.
This is a cut of narration, not of content.
No behaviour change; make check green.

Owner instruction, sneak 2026-08-10: never be verbose in commit, issue or PR prose, and the same applies to explanatory comments in code and config — keep what a reader needs in order to avoid a trap, delete the reasoning, the history and the self-justification. This repo diverges badly. Several `TODO.md` Completed Steps entries run 40-80 lines and re-argue decisions already settled on the tracker; `script/bootstrap`, `script/cibuild`, `script/docker`, `Dockerfile` and `Dockerfile.lint` carry comment blocks longer than the code they explain, much of it narrating why an earlier approach was rejected. ## Definition of done - Each `TODO.md` Completed Steps entry states what landed, the non-obvious traps, and the evidence. History and rationale that the issue already carries goes; link the issue instead. - Comment blocks in `script/` and both Dockerfiles keep the trap and drop the argument. A comment that exists to justify a past decision is deleted. - What must NOT be cut: any trap a reader would otherwise fall into, any disclosure (a deviation taken, a rule suppressed, a partially verified claim), and any recorded evidence that a check really ran. This is a cut of narration, not of content. - No behaviour change; `make check` green.

clawbot added this to the 1.0.0 milestone 2026-08-10 15:46:14 +02:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: sneak/sfdupes#49