Fold the onboarding-feedback pass into the backlog - #576
Merged
Conversation
Two days of onboarding more repositories to the hub produced seventeen recorded observations. Each was checked against `develop` at `b82c1a3`, the committed `TODO.md`, and the eleven open issues before being written down, because the value of the pass is in what is genuinely uncovered rather than in the count. Ten are new entries. Three amend an entry that had already reasoned about the same surface from one example and needed the second. One was already covered and is left alone. Two are rules that already exist and already state the common case, where what recurs is the case the rule leaves unstated. ## The three amendments, each adding the example the entry was missing | Entry | What it gains | | --- | --- | | Reduce the copied surface | The wanted end state, and that the fleet already runs both models without either having been chosen | | Name hub-only machinery | The measured cost, agents rebuilding worse versions of gates that already exist | | The `hugo` type | That the theme carry mechanism is undecided, as a question about the type rather than about one repository | ## Two already-documented rules, where the wording is the defect `Closes #N` is stated and carried, so agents re-deriving it are missing it rather than lacking it. What is genuinely absent is the case that produces the confusion: work complete on `develop` with no promotion imminent, which the current text does not license closing. The clickable-link rule gets the hard part right, that a prompt renders no link, so the reference inside it is bare and the link goes in the message that accompanies it. It says accompanying rather than preceding, and a message emitted after the prompt is not read before the question is answered, which is the whole outcome the rule exists to produce. Reading both recurrences as underspecified wording rather than as the rule being ignored is what makes them fixable. ## One entry records a live defect rather than a preference The README intro spec and the `HISTORY.md` mirror rule together forbid a second paragraph, and `spec/audit.py` measures the first non-empty line, so a legitimate second paragraph is reported. That is the same axis as declaring the description in the registry, so the two are noted as wanting one decision rather than two. Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
This was referenced Aug 6, 2026
Contributor
There was a problem hiding this comment.
Pull request overview
Updates TODO.md to incorporate results from a recent onboarding-feedback pass, expanding and refining backlog entries so the recorded observations are captured as actionable items in the hub’s running backlog.
Changes:
- Records the onboarding-feedback verification baseline (
developatb82c1a3) alongside the previously noteddevelopcheckpoint. - Adds new backlog entries (and expands existing ones) covering carried-content propagation, gate/automation ergonomics, and fleet workflow/process clarifications.
- Extends the reference-link definitions to support the newly added cross-references.
`TODO.md` states in its own preamble that where an open issue covers the same ground it is named on the entry, so the two are read together rather than worked twice. Seven entries from the onboarding-feedback pass now have an issue and were carrying no reference to it. | Issue | Entries | | --- | --- | | #577 | The README intro above the tagline | | #578 | Hand-closing an issue, the link before the prompt, and the operational pull request, numbered by their position in the issue | | #579 | The fleet vocabulary and its entry point | | #580 | Naming hub-only machinery, and the helper functions that depend on reaching it | The three that share #578 name their item number within it, because the issue bundles three edits to the same carried file and an unqualified reference would not say which one an entry is waiting on. Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
The previous commit rewrote the file through a Python helper that reads with universal newlines and writes back plain LF, so every line in the file changed ending while eight lines changed content. `.editorconfig` declares CRLF the default and lists TODO.md in none of the LF exceptions, so the file was correct before and is correct again. The content is byte-identical to the previous commit: ```console $ git diff --ignore-cr-at-eol HEAD --stat $ ``` Neither local gate catches this, and their scopes say why. `repo_gate.py --check eol` compares the `.gitattributes` LF pins against the `.editorconfig` overrides and reads no file content at all, so a whole-file ending flip is outside what it measures. `prose_lint.py` reads lines rather than terminators. CI would have caught it, since editorconfig-checker enforces the `[*] end_of_line = crlf` default, so the gap is in the pre-push loop rather than in the defenses. Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
ptr727
added a commit
that referenced
this pull request
Aug 6, 2026
…e onboarding-feedback backlog (#582) Promotes the two commits `develop` has carried since the previous promotion (#574) to `main`. Merge commit only, no squash, and `develop` is not deleted. ## What lands - **#575** Require an explicit `--repo` on `scripts/pr_review.py`, since the old default silently digested a pull request in the hub when a run in another repository omitted it, and lead the digest summary with the repository it read so a misdirected run is visible in its own output. - **#576** Fold the two-day onboarding-feedback pass into `TODO.md`: ten new entries, three amendments that each supply the second example their entry was reasoning from one instance without, and two recurring cases traced to underspecified wording in rules that already exist. ## Issues closed None. Neither constituent pull request carried a closing keyword, and the four issues #576 filed (#577, #578, #579, #580) record work that is still open rather than work this promotion completes. ## Verification `git merge-tree --write-tree origin/main origin/develop` reports no conflict, so this promotion needs no throwaway resolution branch, and the tree diff against `main` is exactly the five files the two commits touch. Both constituent pull requests merged green with their review loops closed.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Two days of onboarding more repositories to the hub produced seventeen recorded observations. Each was checked against
developatb82c1a3, the committedTODO.md, and the eleven open issues before being written down, because the value of a feedback pass is in what it genuinely uncovers rather than in the count of what it recorded.Ten are new entries. Three amend an entry that had already reasoned about the same surface from a single example and needed the second. One was already fully covered and is left untouched. Two are rules that already exist, already state the common case, and leave unstated exactly the case that keeps recurring.
Disposition
pr_review.py --repodefaulthugorepository carries its themehugotype entryThe three amendments each add the example their entry was missing
Every one of the three had already reasoned correctly from one instance. What each lacked was the second instance that shows the reasoning generalizes, which is what turns a worked example into a decision worth making.
The copied-surface entry argued the case for
repo-config/configure.shalone. It now states the wanted end state, that a script identical everywhere lives in the hub once and a downstream repository calls it, and that the fleet already runs both models without either having been chosen against the other. It also separates out the half that needs no decision to start on, which is deleting a downstream config script whose content is only ever the hub's.The hub-only-machinery entry had the reader-follows-a-dead-pointer problem and no evidence that anyone had. It now carries the measured cost: several sessions had to be redirected by hand to
scripts/pr_review.pyandscripts/prose_lint.pyafter building worse versions of them, and none of those agents did anything wrong, since the tool they were pointed at is absent from their tree and nothing they can read says how to reach it.The
hugoentry recorded that Blog's theme is vendored with no upstream ref and never asked whether that is what the type should require. The question is framed as one about the type rather than about Blog, because whatever is decided becomes the type's contract and the second generator inherits it.Two rules already exist, and the wording is the defect
Closes #Nis stated atGOVERNANCE.md"Git and Commit Rules" and is carried fleet-wide, so downstream agents re-deriving it and reporting it as a discovery are missing it rather than lacking it. What is genuinely absent is the case that produces the confusion, which is work complete ondevelopwhile a promotion is not imminent, leaving the issue open with nothing recording that it is done. The current text licenses a hand-close only once a promotion has merged without the keyword, which is the narrower case.The clickable-link rule gets the hard part right, that an interactive prompt renders neither a Markdown link nor a bare URL, so the reference inside it is a bare number and the link goes in the message that accompanies it. It says accompanying rather than preceding, and a message emitted after the prompt is not read before the question is answered, which is the entire outcome the rule exists to produce.
Reading both recurrences as underspecified wording rather than as the rule being ignored is what makes either of them fixable, and it is the same diagnosis in both cases.
One entry records a live defect rather than a preference
spec/readme-structure.mditem 1 reads as though the canonical description is the paragraph after the H1, andCODESTYLE.mdthen hasHISTORY.mdcopy "the same intro paragraph" verbatim. Together they forbid a README from saying anything further about itself above the fold, andspec/audit.pymeasures the first non-empty line, so a legitimate second paragraph is reported as a finding. That is the same axis as declaring the description inregistry/repos.json, so the entry says the two want one decision rather than two taken in sequence.Verification
prose_lint.py --diff,repo_gate.py, andmarkdownlint-cli2are clean over the change.