docs(#7355): specify canonical ADR References entry format - #7356
fullsend-ai-coder[bot] wants to merge 1 commit into
Conversation
PR #7115 needed four review-fix rounds because no written rule specified how ADR References-section entries should be labeled. Existing ADRs already disagree on em-dash vs colon, trailing descriptions, and truncated titles. Document the canonical form in docs/contributing/adrs.md and skills/writing-adrs/SKILL.md: [ADR NNNN — <verbatim frontmatter title minus the N. prefix>](path) with no trailing text. Extend lint-adr-frontmatter to reject em-dash labels that do not match the target title, and correct the three existing mismatches so the hook is green on main. Note: `pre-commit run` could not fetch hook repos (git fetch origin --tags returned HTTP 403). Equivalent hooks were run directly (ruff 0.15.7, ty, bandit 1.9.4, ADR linters, lychee, lint-docs-links) and passed. Closes #7355
|
🤖 Finished Review · ✅ Success · Started 10:22 AM UTC · Completed 10:39 AM UTC Commit: Runtime: pi · Model: sonnet → claude-sonnet-5 · Effort: high · Cost: $4.42 |
Site previewPreview: https://ca670def-site.fullsend-ai.workers.dev Commit: |
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
ReviewFindingsMedium
Low
|
![fullsend-ai-review[bot]](https://avatars.githubusercontent.com/in/3478501?s=60&v=4){kind=small}
| **When reviewing PRs:** Flag substantial rewrites to Context, Decision, or Consequences on Accepted ADRs already on `main` as a policy violation. Allow minor annotations (cross-references, short notes, typo fixes), status updates, and supersession links. For brand-new ADR files on the PR branch, evaluate whether the recorded decision matches the diff — do not treat **Accepted** on a new file as a mistake if the ADR is ready for human review at merge. For new or edited `## References` entries that point at another ADR, require the canonical format below. Do not flag neighboring older entries that use another style, and do not require rewriting them. | ||
|
|
||
| ## References section format | ||
|
|
There was a problem hiding this comment.
[low] design-justification
The canonical References-entry format standardizes new/edited entries on a bare-link, no-trailing-text style. The doc text specifies the rule but does not explain why this form was chosen, and does not address how it relates to differently-styled entries already in the ADR corpus (colon-form, unlinked, or trailing-rationale entries), beyond stating existing entries should not be rewritten.
Suggested fix: Optionally add one sentence in docs/contributing/adrs.md explaining the rationale for the bare-link form (e.g., it is the only style compatible with the new title-verbatim-match lint rule), so future readers understand why this form was picked over other existing styles. Not required for merge.
fullsend-ai-review
Bot
added
the
requires-manual-review
Summary
Specify a canonical ADR
## Referencesentry format so agents adding cross-references stop guessing (PR #7115 needed four review-fix rounds for label wording and punctuation).Related Issue
#7355
Changes
docs/contributing/adrs.mdandskills/writing-adrs/SKILL.md:- [ADR NNNN — <verbatim frontmatter title minus the N. prefix>](path)with no trailing description text.hack/lint-adr-frontmatterto reject[ADR NNNN — Title]labels whose title does not match the target ADR's frontmattertitle. Colon-form, number-only, and unlinked existing entries are left alone.main.make script-test.Testing
python3 hack/lint_adr_frontmatter_test.py(10 tests)python3 hack/lint-adr-frontmatteragainst the full ADR treepre-commit runfailed to fetch hook repos (HTTP 403)Checklist
Closes #7355
Post-script verification
agent/7355-adr-references-format)b108ba60479e4513e73b01adb4c48eb3c0a22c6c..HEAD)