Skip to content

docs(agents): an ADR request in an issue or plan is still held to the bar - #122

Merged
bomly-guy merged 1 commit into
mainfrom
claude/adr-bar-precedence
Oct 27, 2026
Merged

bomly-guy merged 1 commit into
mainfrom
claude/adr-bar-precedence

Conversation

@bomly-guy

@bomly-guy bomly-guy commented Oct 25, 2026 •

Copy link
Copy Markdown
Contributor

Adds one rule to the shared ADR section of AGENTS.md: an issue, plan or acceptance checklist that asks for an ADR is asking for the decision to be recorded, not for a new file. The three-part bar still decides.

  • Fails the bar: the reasoning goes in a doc comment (or this repository's narrative doc) and the pull request says so.
  • Passes the bar: revise the live record that owns the topic, and start a new one only when none does.

Why: the issues for planning#51 were written before the ADR cleanup and asked for ADRs in their acceptance lists. Following them produced bomly-cli ADR-0050 and ADR-0051, which failed the bar and were folded back into ADR-0020 and dev-docs/ARCHITECTURE.md in bomly-dev/bomly-cli#531.

The section appears in both repositories and changes in both together: companion PR bomly-dev/bomly-cli#534.

🤖 Generated with Claude Code

Summary by CodeRabbit

  • Documentation
    • Updated contribution guidance to clarify how architectural decisions should be recorded. Decisions that meet the ADR criteria should update the existing record for that topic, or create one if no record exists. Other reasoning should be documented in a code comment or the guidance file, with the pull request noting when the ADR criteria are not met. No public declarations changed.

… bar

Issues written before the ADR cleanup ask for "an ADR under dev-docs/adr"
in their acceptance lists, and an agent following them wrote two records
(bomly-cli ADR-0050 and ADR-0051) that failed the bar and were folded
back into ADR-0020 and ARCHITECTURE.md in bomly-cli#531. The rule now
says such a request asks for the decision to be recorded, not for a new
file: the bar still decides, and a passing decision revises the live
record that owns the topic first. The same section appears in both
repositories and changes in both.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 25, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-25T19:54:40.133740Z 9f1a2fd PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@coderabbitai

coderabbitai Bot commented Oct 25, 2026 •

Copy link
Copy Markdown

Review in Change Stack →

No actionable comments were generated in the recent review.

Recent review info
Run configuration
  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: ASSERTIVE
  • Plan: Advanced
  • Run ID: e5b473b0-959b-4f08-8bbf-0f32a28966d4
Commits

Reviewing files that changed from the base of the PR and between 9eae00b and 9f1a2fd.

Files selected for processing: 1
  • AGENTS.md

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

Walkthrough

AGENTS.md now explains where to document a decision when it does not meet the ADR criteria. When the criteria are met, it directs maintainers to revise an existing ADR or create one if none exists.

Changes: ADR guidance

Layer / File(s) Summary
Documenting ADR decisions
AGENTS.md
The guidance says an ADR request alone does not require a new file. It directs contributors to document reasoning in a doc comment or AGENTS.md when the criteria are not met, and to state this in the pull request. When the criteria are met, it directs maintainers to revise the existing ADR or create one if none exists.

Priority: Low

Estimated code review effort: 1 (Trivial) | ~3 minutes

Change: Other

Possibly related issues

Possibly related PRs

Merge Risk: Minimal · up to 9f1a2

No merge-blocking issues were identified in the updated ADR guidance.

Pre-merge checks: Passed 5
Check name Status Explanation
Description Check Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check Passed The title names the main change: an ADR request raised in an issue or plan is still held to the existing three-part ADR bar. The AGENTS.md summary and PR objectives confirm that the change clarifies t…
Docstring Coverage Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Full details: Title check

Explanation

The title names the main change: an ADR request raised in an issue or plan is still held to the existing three-part ADR bar. The AGENTS.md summary and PR objectives confirm that the change clarifies this point and does not create a new file by default. The title uses the conventional docs(scope) prefix and is specific enough for a teammate scanning history to understand the change.

Full details: Docstring Coverage

Explanation

No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0 files. (1 skipped: 1 unsupported.)

Finishing Touches
🧪 Generate unit tests (beta)
  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

A rabbit reads the ADR guide,
No new file just for the ask.
If criteria fit, revise or add;
If not, record the reasoning.
Then hop along, with notes in hand.

Comment @coderabbitai help to get the list of available commands.

@github-actions

Copy link
Copy Markdown

Bomly Diff Summary

Compared 9eae00b2c2805125b1dab844b0c33e24b6cbfd3e to 9f1a2fd067326263771da212074777ffc4291a59.

Overview

Status Manifests Dependencies Findings Duration
✅ Pass +0 / ~0 / -0 0 added / 0 version changed / 0 detail changes / 0 removed 0 introduced / 0 persisted / 0 resolved 56.4s

Dependency Changes

✅ No dependency changes.

Vulnerabilities

✅ No vulnerability changes.

License Changes

✅ No license changes.

Project Posture

✅ No project posture changes (--matchers +scorecard was not selected).

Policy Findings

✅ No policy differences were identified.

@bomly-guy
bomly-guy merged commit 43ec79f into main Oct 27, 2026
11 checks passed
@bomly-guy
bomly-guy deleted the claude/adr-bar-precedence branch October 27, 2026 06:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant