Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Codify ADR amendment convention in AGENTS.md and pre-commit checks to prevent in-place modification of accepted decisions

Open
  • Is something wrong?
#288 2 comments 1 reaction 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
55/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
markdown, python
Domain
documentation, tooling

Research direction

Start with the 'Rules for creating or modifying specification documents' section in AGENTS.md, where the proposed ADR amendment rule would go, and with the existing linters in scripts/lint.py and .pre-commit-config.yaml. Read docs/decisions/0001-requirements-storage-format.md to see the amendment format and what counts as a historical section. Done means the AGENTS.md rule is added and an offline check fails when an accepted ADR's existing lines are deleted or changed, while amendment blocks still pass. The check's exact rules for what counts as a historical section are not settled in the issue, so confirm them with maintainers first.

Written by the indexing model from the issue text.

Description

enhancement feature infra ready-for-triage triaged

What happened

On PR #250 (https://github.com/redhat-et/ProtoBot/pull/250), commit 6e2ed1b modified docs/decisions/0001-requirements-storage-format.md by rewriting the accepted decision prose in place (lines 152–156) instead of appending a dated amendment section. Across automated review runs (including run 37943172659 on 6e2ed1b), the review agent reported zero findings on the ADR diff, raising only a generic [protected-path] finding on .github/workflows/ci-workflow.yaml. During subsequent human review, Lukas Kellerstein identified this in review comment A8 (https://github.com/redhat-et/ProtoBot/pull/250#pullrequestreview-2947118128): "Accepted ADR text rewritten in place: Mutated historical accepted ADR text rather than following the repo convention of appending a dated amendment section." Author John Strunk had to manually restore the historical decision text and append an **[Amended October 2026]** block in commit dc2d157.

What could go better

AGENTS.md explicitly lists docs/decisions/ as part of the specification document hierarchy and establishes detailed rules for creating and modifying specification documents, including registered artifact governance via ears-manager artifact put and sibling terminology consistency. However, AGENTS.md does not define rules for Architecture Decision Records, nor does it codify the project convention that accepted ADRs are immutable historical records that can only be refined by appending dated amendments (**[Amended Month Year]**). Furthermore, scripts/lint.py and .pre-commit-config.yaml contain linters for Markdown, YAML, and Go, but no deterministic check verifying that existing sections in accepted ADR files remain untouched. Because this convention was undocumented in agent instructions and unenforced by linters, neither the authoring workflow nor the review agent caught the mutation, requiring human reviewer intervention.

Proposed change

  1. In AGENTS.md, add a numbered rule under 'Rules for creating or modifying specification documents':
    "Accepted Architecture Decision Records (docs/decisions/) are immutable historical records. Never rewrite or replace accepted decision text in place. When subsequent design evolution amends or refines an accepted ADR, append a dated amendment block (**[Amended Month Year]**) describing the change, its rationale, and references to updated architecture documents. Review agents must verify that changes to accepted ADRs follow this amendment convention rather than modifying accepted sections in place."
  2. In scripts/lint.py, implement an offline pre-commit check verifying that git diffs touching files under docs/decisions/ with status 'Accepted' do not delete or modify lines in historical sections preceding the amendment blocks.

Validation criteria

The next 5 PRs (agent-generated or human-authored) touching docs/decisions/ adhere to the amendment convention without requiring human review comments or rework cycles, and review agents flag any in-place mutation to historical ADR decision sections as a finding.

Generated by retro agent from https://github.com/redhat-et/ProtoBot/pull/250

Dominant language
Go
Stars
6
Forks
8
Avg merge
1d 2h
Merged PRs (30d)
96

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from redhat-et/ProtoBot

All issues in redhat-et/ProtoBot

Similar issues

More Go issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.