sneak/sfdupes
1
0
Fork 0
Code Issues 23 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

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

New Issue
Open
opened 2026-08-10 15:46:09 +02:00 by clawbot · 0 comments
clawbot commented 2026-08-10 15:46:09 +02:00
Collaborator
Copy Link
Copy Source

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.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
merge-ready
Review passed; ready to merge
 needs-checks
CI checks failing or not yet green
 needs-rebase
Branch conflicts with main; rebase required
 needs-review
PR awaiting independent adversarial review
 needs-rework
Review found blocking problems; author must rework
No labels
Milestone
No items
No Milestone 1.0.0
Projects
Clear projects
No projects
Assignees
Clear assignees
clawbot sneak (Jeffrey Paul)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: sneak/sfdupes#49