Skip to content

docs(#8971): keep code-pinned links out of ADR bodies - #8972

Merged
waynesun09 merged 2 commits into
mainfrom
agent/8971-adr-code-links-guidance
Nov 2, 2026
Merged

waynesun09 merged 2 commits into
mainfrom
agent/8971-adr-code-links-guidance

Conversation

@fullsend-ai-coder

@fullsend-ai-coder fullsend-ai-coder Bot commented Oct 31, 2026 •

Copy link
Copy Markdown
Contributor

Summary

This updates the ADR authoring guidance in this repo: the writing-adrs skill, the ADR template, docs/contributing/adrs.md, and the ADR row in AGENTS.md. Claims about current behaviour are still checked against the code at a commit SHA. The file or function evidence now goes in the PR description. The ADR body describes the behaviour in plain prose and links the PR, issue, or ADR that introduced it. The PR also adds the other lessons from reviewing recent ADRs (0144, 0147–0149, 0151, 0152).

This revises the citation rule from #8490

#8491 (for #8490, approved by ifireball and rh-hemartin) told ADR authors to cite the implementing file or function at a commit SHA, and the template showed a blob/<SHA>/... permalink as the example. This PR changes where that citation goes. It does not drop the check.

  • Kept from ADR guidance: require an explicit forge scope and code-cited descriptions of current behavior, and tell reviewers to verify both #8490: every claim about current behaviour is verified against the code at a commit SHA, not main, and reviewers check it.
  • Changed: the file/function evidence moves from the ADR body to the PR description. Context and Decision describe the behaviour in plain language and link the PR, issue, or ADR that introduced it. Line-pinned blob/<sha>/path#L… permalinks are no longer allowed there.
  • Why: authors met the rule by turning Context into a code tour. One accepted ADR had 11 line-pinned links across three different commits in its Context, plus two in its Decision. Rewriting it in plain prose cut it from 240 to 95 lines without losing a claim. Mixed SHAs describe no single current state, and the links go stale as the code moves. The PR description is where reviewers check evidence anyway, and it stays attached to the decision.

Because this revises guidance that #8491's reviewers approved, it needs their call before it merges.

Changes

  • skills/writing-adrs/SKILL.md
    • Checklist step 6: verify each claim at a SHA, describe it in plain language, put the evidence in the PR description, and keep blob/<sha>/path#L… permalinks out of Context and Decision.
    • "Link, don't repeat": when a sibling ADR or docs/normative/ contract (often in the same PR) defines a rule, link it in one line instead of restating it.
    • Red Flags: a limit, timeout, or size with no stated basis; re-check sibling and contract-version references after any ADR in a series merges.
    • Common Mistakes: replaced the old citation row with an evidence-in-PR-description row. Added rows for code permalinks, a file slug that names a rejected option, and "Planned:" status blocks in Context.
  • docs/ADRs/0000-adr-template.md: the Context prompt now matches step 6.
  • docs/contributing/adrs.md: reviewers check claims against the evidence in the PR description and flag code permalinks in the ADR body.
  • AGENTS.md: the ADR row now matches the new rule.

Edits stay within step 6, "Link, don't repeat", Red Flags, and Common Mistakes. #7428 merges cleanly with this branch. #7356 and #7676 already conflict with main; this PR adds lines next to theirs in docs/contributing/adrs.md and AGENTS.md, so their rebase gets one more small hunk.

Testing

  • pre-commit run --from-ref origin/main --to-ref HEAD (what make lint runs, over the whole branch diff): every applicable hook passed, including lint ADR statuses, lint ADR numbers, lint ADR frontmatter, lint docs link scope, lint markdown links, lint broken symlinks and Detect hardcoded secrets.
  • Tests added/updated for new or modified logic. Not applicable: this is a docs-only change.

Checklist

  • PR title follows Conventional Commits (correct type, ! for breaking changes)
  • Commits are signed off (DCO): the agent commit is exempt from DCO; the follow-up commit is signed off
  • I wrote this contribution myself and can explain all changes in it: authored by the fullsend code agent, then tightened by a maintainer takeover

🤖 Generated with Claude Code


Closes #8971

Post-script verification

  • Branch is not main/master (agent/8971-adr-code-links-guidance)
  • Secret scan passed (gitleaks — 12a09ace3e26b1e52442ee628ac570f794f856f6..HEAD)
  • PR body secret scan passed (gitleaks — no-git)
  • Final PR description secret scan passed (gitleaks — no-git)

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 #7356, #7428, #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 #8971

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@waynesun09

Copy link
Copy Markdown
Member

/fs-fix-stop

@github-actions github-actions Bot added the fullsend-no-fix Skip bot-triggered fix agent runs label Oct 31, 2026
@github-actions

Copy link
Copy Markdown

Fix agent disabled for this PR. Remove the fullsend-no-fix label or use /fs-fix to re-engage.

Step 6, the template's Context prompt and the reviewer bullets each grew
to four or five sentences; fold them back to two with the same rule.
Ban every blob/<sha>/ code permalink in the ADR body, not only #L ones,
since the old template's whole-file example had the same staleness
problem. Restore that reading main is fine once its SHA is recorded.

Assisted-by: Claude (fix), Claude (review)
Signed-off-by: Wayne Sun <gsun@redhat.com>
@github-actions

github-actions Bot commented Oct 31, 2026 •

Copy link
Copy Markdown

Site preview

Preview: https://0c393361-site.fullsend-ai.workers.dev

Commit: 891e81e4d41f8fa439b4d4d349941e6e7b9fd54a

@fullsend-ai-review

fullsend-ai-review Bot commented Oct 31, 2026 •

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 4:51 PM UTC · Completed 5:04 PM UTC

Commit: 891e81e · View workflow run →

Runtime: pi · Model: sonnet → claude-sonnet-5-5 · Effort: high · Cost: $1.60

@fullsend-ai-review

Copy link
Copy Markdown

<!-- fullsend:risk-assessment -->
Risk Assessment: moderate (2/5)

Details

Small documentation update aligning closely with the linked issue, elevated to moderate risk due to touching two protected paths (AGENTS.md and skills/) and moderate git churn on AGENTS.md.

@fullsend-ai-review

Copy link
Copy Markdown

Review

Findings

Medium


Labels: PR updates the writing-adrs skill and ADR contributing guidance.

@codecov

codecov Bot commented Oct 31, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

@waynesun09
waynesun09 added this pull request to the merge queue Nov 2, 2026
Merged via the queue into main with commit f6e35de Nov 2, 2026
80 of 82 checks passed
@waynesun09
waynesun09 deleted the agent/8971-adr-code-links-guidance branch November 2, 2026 18:09
jwm4 added a commit that referenced this pull request Nov 2, 2026
…n rule

The ADR guidance that merged in #8972 keeps file and function evidence out
of ADR bodies: describe current behaviour in plain language, link the
issue that records it, and put the code evidence at a commit SHA in the
pull request description. Rewrite ADR 0156's Context paragraph that way.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Signed-off-by: Bill Murdock <bmurdock@redhat.com>

This branch was successfully deployed

1 active and 1 inactive deployments
site-preview — 891e81e4 Deployed Oct 31, 2026 by github-actions[bot]
dev — 891e81e4 Deployed Oct 31, 2026 by waynesun09 via behaviour #18462
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

component/skills documentation fullsend-no-fix Skip bot-triggered fix agent runs ready-for-review Triggers review agent dispatch requires-manual-review Review requires human judgment risk/moderate PR risk: moderate

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs(adrs): keep code-pinned links out of ADR bodies and other review lessons

2 participants