Skip to content

docs: clarify document ownership and what durable prose leaves out - #162

Merged
Azganoth merged 2 commits into
mainfrom
docs/authoring-guidance
Aug 2, 2026
Merged

docs: clarify document ownership and what durable prose leaves out#162
Azganoth merged 2 commits into
mainfrom
docs/authoring-guidance

Conversation

@Azganoth

@Azganoth Azganoth commented Aug 2, 2026

Copy link
Copy Markdown
Owner

Summary

Two guidance gaps that #161 walked into, both fixed where the guidance is read rather than where the symptom appeared.

  • What each document owns. Reference's description lists "shortcuts", so a surface's keyboard behavior reads as though it belongs there, and the context popup's arrow keys were written into both Reference and Specification before the split was settled. docs/README.md now states the distinction it already implied: Reference lists what exists, Specification states how it behaves, and keyboard behavior is Specification's even though Reference inventories the shortcuts.
  • What a commit body and other durable prose leave out. CONTRIBUTING.md bans verification evidence, commands run, and per-file summaries from commit bodies, but not the account of how the work unfolded, which is what fix: reach and operate the editor context popup by keyboard #161's documentation commits carried: references to sibling commits and to what an earlier attempt got wrong. The new rule names that, ties it to the squash merge that discards the sequence, and goes after the cause — a commit that exists only because documentation was held back until its code landed will produce such a body, so the documentation should land with the change it describes.

AGENTS.md gains the matching checkpoint under verification, since an agent writes with a whole session in context and the same habit reaches code comments and pull request text. It draws the line at recoverability: rationale a reader cannot reconstruct from the diff stays, the account of how it was reached goes.

Related Issue

Not applicable. Small, self-contained correction, per CONTRIBUTING.md. Refs #161, which is where both gaps surfaced.

Verification

pnpm exec oxfmt --check AGENTS.md CONTRIBUTING.md docs/README.md passes, and the pre-commit hook ran the same check on each commit. Documentation-only with no executable configuration touched, so no application suite, per the documentation-only rule in CONTRIBUTING.md and AGENTS.md.

Nothing here is mechanically enforced, and that is deliberate: no linter separates a comment that explains a workaround from one that narrates the afternoon, and a gate that cannot make that call would either pass everything or block correct prose.

Notes

  • The Pull Requests section gets no duplicate rule. The AGENTS.md line already covers pull request text, and a second enumeration invites matching the list rather than the principle, which is how the original rule was obeyed to the letter and missed anyway.
  • The document bullets at the top of docs/README.md are unchanged. Removing "shortcuts" from Reference's description would be wrong, since Reference does inventory them; the ambiguity is about behavior versus inventory, which is where the sentence was added.

Reference inventories shortcuts, so a surface's keyboard behavior reads as
though it belongs there. It does not, and the context popup's arrow keys
were written up in both documents before the split was settled.
The commit rule binds every contributor. The verification step repeats it
for an agent, which writes with a whole session in context, and extends it
to comments and pull request text.
@Azganoth Azganoth added the Documentation Improvements or additions to documentation label Aug 2, 2026
@Azganoth Azganoth self-assigned this Aug 2, 2026
@Azganoth
Azganoth enabled auto-merge (squash) August 2, 2026 01:40
@Azganoth
Azganoth merged commit 5c86dd4 into main Aug 2, 2026
2 checks passed
@Azganoth
Azganoth deleted the docs/authoring-guidance branch August 2, 2026 01:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant