Repository navigation
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
|
| **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.
|
This pull request has been automatically marked as stale because it has not had any activity in the last month. It will be closed in 2 weeks if no further activity occurs. Remove the |
ADR reviews (0144, 0147-0149, 0151, 0152) kept flagging the same problems. Authors met the "cite current behavior" rule with line-pinned blob/<sha>#L links in Context and Decision, which turned ADRs into code tours that went stale. Decisions repeated sibling ADRs or normative contracts. Numbers had no stated basis. Series of ADRs landed out of step with each other. Claims about current behavior still have to be checked against the code at a commit SHA. The file/function evidence now goes in the PR description, and the ADR body describes the behavior in plain prose and links the PR, issue, or ADR that introduced it. - skills/writing-adrs/SKILL.md: reword checklist step 6; extend "Link, don't repeat" to cover sibling ADRs and docs/normative/ contracts; add Red Flags for numbers with no basis and for re-checking a series after a sibling merges; add Common Mistakes rows for line-pinned links, slugs that name a rejected option, and "Planned:" status blocks in Context. - docs/ADRs/0000-adr-template.md: update the Context prompt to match. - docs/contributing/adrs.md: reviewers check claims against the evidence in the PR description and flag line-pinned links in the ADR body. - AGENTS.md: reword the ADR row to match. Edits stay within step 6, "Link, don't repeat", Red Flags, and Common Mistakes, to keep conflicts small with open PRs fullsend-ai#7356, fullsend-ai#7428, fullsend-ai#7676. Note: pre-commit could not fetch remote hook repos (TLS failure in the sandbox). The applicable hooks ran directly instead (pre-commit-hooks 6.0.0 fixers/checks, lint-adr-*, lint-docs-links, lint-broken-symlinks, lychee) and all passed. gitleaks was covered by scan-secrets. Closes fullsend-ai#8971 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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)