Skip to content

docs(#7427): check in-flight ADRs for decision duplication - #7428

Open
fullsend-ai-coder[bot] wants to merge 2 commits into
mainfrom
agent/7427-adr-topic-duplication-check
Open

fullsend-ai-coder[bot] wants to merge 2 commits into
mainfrom
agent/7427-adr-topic-duplication-check

Conversation

@fullsend-ai-coder

Copy link
Copy Markdown
Contributor

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

  • Checklist step 1: after listing new docs/ADRs/NNNN-*.md files on open
    PRs, 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.
  • Also scan recently-merged ADRs on main whose titles or relates_to
    overlap, because a different title can still record the same decision.
  • Red Flags: add a bullet for skipping that Decision-section check.

Testing

  • Secret scan passed on the changed skill file
  • Direct execution of applicable pre-commit hooks (whitespace,
    gitleaks, lychee markdown links) — pre-commit run could not
    fetch remote hook repos (HTTP 403)
  • make lint via pre-commit not run in-sandbox (same fetch failure);
    post-script will run the authoritative check
  • No production code or tests to update (docs-only skill change)

Checklist

  • PR title follows Conventional Commits
  • Commits are signed off (DCO) — N/A for autonomous agent commits
  • I wrote this contribution myself and can explain all changes in it

Closes #7427

Post-script verification

  • Branch is not main/master (agent/7427-adr-topic-duplication-check)
  • Secret scan passed (gitleaks — 41f0399b8b5a84cf607eedc4ecbe52c297aef76f..HEAD)
  • PR body secret scan passed (gitleaks — no-git)

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
@fullsend-ai-coder
fullsend-ai-coder Bot requested a review from a team September 17, 2026 22:22
@fullsend-ai-coder fullsend-ai-coder Bot added the ready-for-review Triggers review agent dispatch label Sep 17, 2026
@codecov

codecov Bot commented Sep 17, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

@fullsend-ai-review

fullsend-ai-review Bot commented Sep 17, 2026 •

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 10:29 PM UTC · Completed 10:39 PM UTC

Commit: e0b245c · View workflow run →

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

@fullsend-ai-review fullsend-ai-review Bot added the risk/low PR risk: low label Sep 17, 2026
@fullsend-ai-review

fullsend-ai-review Bot commented Sep 17, 2026 •

Copy link
Copy Markdown

Risk Assessment: low (1/5)

Details

Single-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 run

Risk Assessment: low (1/5)

Details

Single-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.

@fullsend-ai-review

fullsend-ai-review Bot commented Sep 17, 2026 •

Copy link
Copy Markdown

Review

Findings

Medium

  • [protected-path] skills/writing-adrs/SKILL.md — This PR modifies a file under a protected path (skills/), which requires human approval regardless of context. The PR links to issue writing-adrs skill's pre-flight check only catches ADR number collisions, not topic/decision duplication #7427 and its description explains the rationale (expanding the writing-adrs skill checklist to catch ADR topic/decision duplication), so context is sufficient — but human approval is still mandatory for any protected-path change.
    Remediation: A human reviewer must approve this change before merge, per the protected-paths policy.

Low

  • [scope-creep] skills/writing-adrs/SKILL.md:138 — Issue writing-adrs skill's pre-flight check only catches ADR number collisions, not topic/decision duplication #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 — noted for completeness.

  • [sub-agent-failure] N/A — The challenger sub-agent returned an empty adjudicated_findings array for a non-empty input set (one finding), which per orchestrator policy is treated as a challenger failure rather than a legitimate full removal. The pre-challenger finding set was used instead.

Not observed in current diff: the two low-severity findings from the prior review (logic-error on the split remediation paths for in-flight vs. recently-merged ADRs, and internal-consistency on the Red Flags coverage) — the current text now splits the two remediation paths and adds a second, dedicated Red Flag bullet with an operational git log discovery step for the recently-merged-ADR check.

Previous run

Review

Findings

Medium

  • [protected-path] skills/writing-adrs/SKILL.md — This PR modifies a file under a protected path (skills/), which requires human approval regardless of context. The PR links to issue writing-adrs skill's pre-flight check only catches ADR number collisions, not topic/decision duplication #7427 and its description explains the rationale (expanding the writing-adrs skill checklist to catch ADR topic/decision duplication), so context is sufficient — but human approval is still mandatory for any protected-path change.
    Remediation: A human reviewer must approve this change before merge, per the protected-paths policy.

Low

  • [logic-error] skills/writing-adrs/SKILL.md:131 — Checklist step 1 gates on both in-flight PRs and recently-merged ADRs, but its single follow-on remediation path ("co-author or comment on the existing PR, or say so in your own PR body") only makes sense for an open PR — a recently-merged ADR has no PR to co-author or comment on. The skill's own supersession rules already cover the "accepted decision turned out wrong" case elsewhere in the file, but this checklist text doesn't route a recently-merged-ADR trigger to that path explicitly.
    Remediation: Split the two cases: for in-flight PRs, keep the co-author/comment/stalled-PR wording; for recently-merged ADRs on main, direct to "do not write a duplicate ADR" (same decision) or "write a superseding ADR and link it" (different/wrong decision).

  • [internal-consistency] skills/writing-adrs/SKILL.md:209 — The new Red Flag bullet only covers skipping the in-flight-PR Decision-section check. It doesn't mention the parallel requirement in the same checklist step to also check recently-merged ADRs on main, and that half of the requirement has no concrete discovery procedure (no window, git range, or command), unlike the "scan open pull requests" instruction it's paired with.
    Remediation: Extend the Red Flag to also cover skipping the recently-merged-ADR check, and give it an operational discovery step (e.g., git log on docs/ADRs/ within a bounded window, then reading Decision/relates_to for overlap).


Next steps:

  • /fs-fix — agent addresses review findings automatically
  • /fs-fix <your instruction> — agent fixes with your specific guidance
  • Push commits directly — review re-runs automatically on push
  • /fs-fix-stop — disable automatic fix runs for this PR

fullsend-ai-review[bot]

This comment was marked as outdated.

@fullsend-ai-coder

fullsend-ai-coder Bot commented Sep 17, 2026 •

Copy link
Copy Markdown
Contributor Author

🤖 Finished Fix · ✅ Success · Started 10:41 PM UTC · Completed 10:47 PM UTC

Commit: e0b245c · View workflow run →

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
@fullsend-ai-coder

Copy link
Copy Markdown
Contributor Author

🔧 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):

  1. [logic-error] SKILL.md:131 — checklist step 1's single remediation path (co-author/comment on the existing PR) only makes sense for an in-flight PR, not a recently-merged ADR which has no PR to comment on (skills/writing-adrs/SKILL.md): Split checklist step 1 into two explicit paths: for an in-flight ADR PR, keep the co-author/comment/stalled-PR wording; for a recently-merged ADR on main, route to 'do not write a duplicate ADR' when it records the same decision, or 'write a new ADR that supersedes it' (linking to the existing supersession guidance) when the recorded decision looks wrong.
  2. [internal-consistency] SKILL.md:209 — the Red Flags bullet only covers skipping the in-flight-PR Decision-section check, not the parallel recently-merged-ADR check, which also lacked a concrete discovery procedure (skills/writing-adrs/SKILL.md): Added a new Red Flags bullet for skipping the recently-merged-ADR check, with a concrete discovery step (git log --since="30 days ago" --name-only -- docs/ADRs/ on main, then reading Decision/relates_to for overlap), matching the operational detail already given for the in-flight-PR check.

Disagreed (1):

  1. [protected-path] skills/writing-adrs/SKILL.md — modifies a protected path and requires human approval: This finding's category is protected-path, the mandatory merge-gate finding: it only requires a human reviewer to approve before merge and does not prescribe any content change. No code edit is authorized or needed for it; the merge gate remains in effect and will be enforced by the post-script/CODEOWNERS process.

Tests: passed

Decision points
  • Did not edit content in response to the protected-path finding (alternatives: Treat the protected-path finding as authorization to make further content edits, Leave the file's protected-path status as a human-approval-only concern; rationale: Per fix-agent policy, a protected-path category finding is the mandatory merge-gate item — it demands human approval and never itself prescribes a content edit. The other two findings did prescribe content changes and were implemented; this one does not, so no additional edit was made on its account.)

Next steps:

  • /fs-review — request a re-review of the changes
  • /fs-fix <your instruction> — run another fix pass with specific guidance
  • Push commits directly — review re-runs automatically on push
    Updated by fullsend fix agent

@fullsend-ai-review

fullsend-ai-review Bot commented Sep 17, 2026 •

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 10:49 PM UTC · Completed 11:01 PM UTC

Commit: 2728529 · View workflow run →

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

@fullsend-ai-review
fullsend-ai-review Bot dismissed their stale review September 17, 2026 23:01

Superseded by updated review

@fullsend-ai-review fullsend-ai-review Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See the review comment for full details.

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

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[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.

@fullsend-ai-review fullsend-ai-review Bot added the requires-manual-review Review requires human judgment label Sep 17, 2026
@github-actions

Copy link
Copy Markdown

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 stale label to reset the inactivity timer.

@github-actions github-actions Bot added the stale label Oct 18, 2026
jflowers pushed a commit to jflowers/fullsend-ai-fullsend that referenced this pull request Nov 2, 2026
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>

This branch was previously deployed

1 inactive deployment
dev — 2728529d Deployed Sep 17, 2026 by fullsend-ai-coder[bot] via behaviour #13161
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ready-for-review Triggers review agent dispatch requires-manual-review Review requires human judgment risk/low PR risk: low stale

Projects

None yet

Development

Successfully merging this pull request may close these issues.

writing-adrs skill's pre-flight check only catches ADR number collisions, not topic/decision duplication

0 participants