Repository navigation
docs(#7427): check in-flight ADRs for decision duplication - #7428
fullsend-ai-coder[bot] wants to merge 2 commits into
Conversation
Checklist step 1 only avoided numeric collisions, so authors could write a new ADR that restates a decision already in an open PR (as happened with #7419 duplicating #6603). After listing in-flight ADR files, read each Decision section (not just the filename or title) and stop if it already covers the same question. Add a matching red-flag bullet. Note: pre-commit could not fetch remote hook repos (HTTP 403). Applicable hooks were run directly (whitespace, gitleaks, lychee). Closes #7427
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
|
🤖 Finished Review · ✅ Success · Started 10:29 PM UTC · Completed 10:39 PM UTC Commit: Runtime: pi · Model: sonnet → claude-sonnet-5 · Effort: high · Cost: $1.58 |
|
Risk Assessment: low (1/5) DetailsSingle-file, 23-line docs-only skill update by a bot author with low git churn (1 commit/30d, 1 author/90d, no fix/revert history) and a linked issue whose scope, labels, and acceptance criteria align cleanly with the PR; the only elevating signal remains the single protected-path hit (skills/); score preserved at 1 (low) per re-review anchoring since Tier 1/2/3 characteristics are unchanged in kind from the prior review. Previous runRisk Assessment: low (1/5) DetailsSingle-file, 12-line docs-only skill update by a bot author with low git churn and a linked issue whose scope, labels, and acceptance criteria align cleanly with the PR; the sole elevating signal is that the touched path (skills/) is on the protected-paths list, which the risk model treats as a single-count protected-path signal within an otherwise low-risk profile. |
ReviewFindingsMedium
Low
Not observed in current diff: the two low-severity findings from the prior review ( Previous runReviewFindingsMedium
Low
Next steps:
|
|
🤖 Finished Fix · ✅ Success · Started 10:41 PM UTC · Completed 10:47 PM UTC Commit: Runtime: claude · Model: sonnet → claude-sonnet-5 · Effort: high · Cost: $0.80 |
…ed flag Address review feedback on PR #7428: - Split the in-flight-PR vs recently-merged-ADR remediation paths in checklist step 1 -- a merged ADR has no PR to co-author or comment on, so route it to "don't duplicate" / "write a superseding ADR" instead, and give the merged-ADR check a concrete discovery step (git log on docs/ADRs/ within a bounded window). - Extend the Red Flags bullet to also cover skipping the recently-merged-ADR check, with the same discovery step. The protected-path finding is the mandatory merge gate for skills/ changes and requires human approval; it does not prescribe a content change, so no edit was made for it (see structured output). Addresses #7428
🔧 Fix agent — iteration 1 (bot-triggered)Addressed the two actionable review findings on PR #7428 by splitting the in-flight-PR vs recently-merged-ADR remediation paths in the writing-adrs skill's checklist step 1, and by extending the Red Flags list to cover skipping the recently-merged-ADR check with a concrete git-log discovery step. The protected-path finding requires human approval only and was not treated as license to edit further content. Fixed (2):
Disagreed (1):
Tests: passed Decision points
Next steps:
|
|
🤖 Finished Review · ✅ Success · Started 10:49 PM UTC · Completed 11:01 PM UTC Commit: Runtime: pi · Model: sonnet → claude-sonnet-5 · Effort: high · Cost: $1.85 |
Superseded by updated review
| read the Decision section and `relates_to` of any whose title or | ||
| problem docs overlap with your topic -- a different title can still | ||
| record the same decision. If a merged ADR already records the same | ||
| decision, do not write a duplicate -- reference the existing ADR |
There was a problem hiding this comment.
[low] scope-creep
Issue #7427's Proposed change section literally proposes only the in-flight-PR Decision-section check. This PR's diff additionally adds a second, separate check for recently-merged ADRs (git log --since="30 days ago" --name-only -- docs/ADRs/) with its own Red Flag bullet. This is closely related to the same underlying problem (decision duplication under a different title) and the PR body discloses and explains the extension explicitly, so it is not a concerning scope departure.
|
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
Expand the writing-adrs skill so pre-flight scanning of in-flight ADRs
catches topic/decision duplication, not only filename number collisions.
Authors now read each in-flight ADR's Decision section (and overlapping
recently-merged ADRs) before writing a new one.
Related Issue
#7427
Changes
docs/ADRs/NNNN-*.mdfiles on openPRs, open each diff and read its Decision section (not just the
filename or title). If it already addresses the same problem-doc
question or architectural decision, stop and co-author/comment on the
existing PR, or call out why a competing PR is stalled or wrong.
mainwhose titles orrelates_tooverlap, because a different title can still record the same decision.
Testing
gitleaks, lychee markdown links) —
pre-commit runcould notfetch remote hook repos (HTTP 403)
make lintvia pre-commit not run in-sandbox (same fetch failure);post-script will run the authoritative check
Checklist
Closes #7427
Post-script verification
agent/7427-adr-topic-duplication-check)41f0399b8b5a84cf607eedc4ecbe52c297aef76f..HEAD)