Grey.ooo/agent-standards
Watch
2
0
Fork
You've already forked agent-standards
 0
Code Issues 2 Pull requests Projects Releases Packages Wiki Activity Actions

Put a pre-commit checklist at the top of the section that describes it #18

Merged
geusebio merged 1 commit from docs/pre-commit-checklist into main 2026-08-13 12:42:59 +00:00
Conversation 0 Commits 1 Files changed 1 +30
geusebio commented 2026-08-12 22:06:49 +00:00
Owner
Copy link

"Before you commit" is the longest section in this file and the one most likely to be consulted mid-task, when what a reader needs is the sequence rather than the argument for it. This puts an eleven-item checklist at the top; everything below stays exactly as it was and becomes the expansion.

The order is the order the work happens: branch name, scope of the diff, classify, run what the diff earns, lint what was touched, reproduce the pipeline, say what was skipped, no secrets, the message, permission.

Two items that are not restatements

  • "A linter passing is not the standard being met." The written conventions cover what a linter has no opinion about — how issues and pull requests are referenced, what a docs-only change may contain, whether prose should have been a table. That is what a reviewer raises, and nothing automated will catch it.
  • "Classify the diff before deciding what to run." Already the rule further down, but it reads as advice there and is easy to skip; as a step it is harder to skip.

Verified

markdownlint (v0.45.0, the pinned image the consuming repo uses) on the file before and after: the 30 added lines introduce no findings.

It does report two that are pre-existing and untouched by this change, at what are lines 116 and 144 before the insertion:

MD040/fenced-code-language  fenced code block with no language
MD051/link-fragments        [Work in progress](#work-in-progress--mark-wip-until-all-green)

Neither is this PR's to fix, but they are worth knowing about: this repository ships no markdownlint config and no workflows, and the consuming repository's linter deliberately excludes submodule content — so nothing has ever linted these files. Worth a follow-up decision about whether this repo should lint itself.

Follow-up in the consuming repo

The pointer bump lands separately, per this file's own rule that a standards change is two pull requests.

"Before you commit" is the longest section in this file and the one most likely to be consulted mid-task, when what a reader needs is the sequence rather than the argument for it. This puts an eleven-item checklist at the top; everything below stays exactly as it was and becomes the expansion. The order is the order the work happens: branch name, scope of the diff, classify, run what the diff earns, lint what was touched, reproduce the pipeline, say what was skipped, no secrets, the message, permission. ## Two items that are not restatements - **"A linter passing is not the standard being met."** The written conventions cover what a linter has no opinion about — how issues and pull requests are referenced, what a docs-only change may contain, whether prose should have been a table. That is what a reviewer raises, and nothing automated will catch it. - **"Classify the diff before deciding what to run."** Already the rule further down, but it reads as advice there and is easy to skip; as a step it is harder to skip. ## Verified `markdownlint` (v0.45.0, the pinned image the consuming repo uses) on the file before and after: **the 30 added lines introduce no findings**. It does report two that are **pre-existing and untouched by this change**, at what are lines 116 and 144 before the insertion: ``` MD040/fenced-code-language fenced code block with no language MD051/link-fragments [Work in progress](#work-in-progress--mark-wip-until-all-green) ``` Neither is this PR's to fix, but they are worth knowing about: this repository ships no markdownlint config and no workflows, and the consuming repository's linter deliberately excludes submodule content — so nothing has ever linted these files. Worth a follow-up decision about whether this repo should lint itself. ## Follow-up in the consuming repo The pointer bump lands separately, per this file's own rule that a standards change is two pull requests.
"Before you commit" is a long section, and its detail is worth having — but a
reader about to commit needs the sequence, not the argument for it. The checklist
goes first and everything below it stays as the expansion.

Two items are not restatements of what follows. One: a linter passing is not the
standard being met — the written conventions cover what a linter has no opinion
about, like how issues are referenced or whether prose should have been a table,
and that is what a reviewer raises. The other: classify the diff with the repo's
own classifier rather than by eye, which is already the rule further down but is
easy to skip when it reads as advice rather than a step.

The rest is a summary in the order the work actually happens: branch name, scope
of the diff, classify, run what the diff earns, lint what was touched, reproduce
the pipeline, say what was skipped, no secrets, the message, and permission.
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
Grey.ooo/agent-standards!18
No description provided.