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

docs(adr): record check precision defaults in an ADR that amends ADR 0003

Open Beginner friendly
  • Is something wrong?
#8,537 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
73/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
markdown, shell
Domain
documentation

Research direction

Read ADR 0003 and the latest ADR, docs/adr/0079-dispatch-tagged-phase-reviews-to-quality-gate-at-the-phase-boundary.md, to follow the project’s format and decision context. Create the next numbered ADR under docs/adr/, add the specified amendment and decision details, then run scripts/check-adr-numbers.sh --check after editing. Done means the ADR records the precision and exception rules, names the enforcement ladder criterion and #3756, and passes the number check.

Written by the indexing model from the issue text.

Description

status: ready

Refs: #7572

Agent Brief

Type: Task
Summary: Write one new ADR that amends ADR 0003 with the precision defaults for checks: zero effective false positives for a blocking check, under 10% for an advisory one, plus the exception rules.

Current behavior:

  • docs/adr/0003-verification-guards-earn-default-on-by-measured-precision.md says a guard earns default-on by measured precision but states no number; its reference guard shipped at 57% precision (docs/adr/0003-verification-guards-earn-default-on-by-measured-precision.md:48-49).
  • No ADR carries an Amends: line for ADR 0003 (rg -l 'Amends: \[?ADR 0003' docs/adr prints nothing on main). The newest ADR is docs/adr/0079-dispatch-tagged-phase-reviews-to-quality-gate-at-the-phase-boundary.md.
  • House style for the line is - Amends: [ADR 0049](0049-run-ci-lanes-on-github-hosted-runners-under-trigger-and-token-hardening.md), in the header list (docs/adr/0074-review-risky-dependabot-updates-in-a-model-job-and-act-in-a-scripted-job.md:7).
  • feedback.disable_not_useful_ratio and exceptions.max_days exist only in the decision record, not in any tracked file (rg -n 'disable_not_useful|max_days' docs plugins scripts prints nothing).

Desired behavior:

  • A new docs/adr/NNNN-<kebab-title>.md, numbered one above the highest on main when the lane runs, in the shape of docs/adr/0079-dispatch-tagged-phase-reviews-to-quality-gate-at-the-phase-boundary.md (title, - Status: accepted, - Date:, Context, Decision, Consequences), written the way /architecture:record-decision writes one.
  • Its header list carries - Amends: [ADR 0003](0003-verification-guards-earn-default-on-by-measured-precision.md).
  • Decision text:
    • A blocking check ships with 0 effective false positives on its corpus.
    • An advisory check stays under 10% false positives; the 10% is named as a corpus-precision proxy, not a measured per-guard rate.
    • feedback.disable_not_useful_ratio is not adopted until #3756 produces a per-guard signal.
    • Exceptions expire after 90 days by default, as a team setting.
    • Break glass is an inline exception that carries a reason, an expiry and a person's approval.
    • Existing guards keep their recorded justification; nothing is re-graded by this ADR.
  • Consequences name the enforcement ladder's guardrail criterion (docs/conventions/enforcement-ladder/README.md) as the reader of these numbers, and #3756 as the open work that grades guards.

Key interfaces:

  • docs/adr/0003-verification-guards-earn-default-on-by-measured-precision.md (read; not edited).
  • scripts/check-adr-numbers.sh (the number must not collide).

Acceptance criteria:

  • rg -l 'Amends: \[?ADR 0003' docs/adr lists exactly one file, the new ADR.
  • The new ADR contains 0 effective false positives, 10%, 90 days and #3756 (rg -c '0 effective false positives|10%|90 days|#3756' <new file> is at least 4).
  • scripts/check-adr-numbers.sh --check exits 0.
  • The diff touches only docs/adr/. scripts/check-changelog-fragments.sh --check-required origin/main passes with no fragment, because no plugin's shipped files change.
  • CI's lint-repo job (which runs check-adr-numbers.sh and the markdown lint) passes. In the lane, run scripts/check-adr-numbers.sh --check at most once, after the last edit.

Out of scope:

  • Editing ADR 0003 itself or any guard.
  • Adding the 90-day exception setting to a plugin; this ADR records the default only.
  • The ladder's guardrail criterion text (sibling slice ladder-v2).

Origin:

  • 0 effective false positives blocking, under 10% advisory: ours, from Google's published bar, D31, Q199, D84.
  • 10% named as a corpus-precision proxy: ours, D116, Q559.
  • Drop feedback.disable_not_useful_ratio until #3756: owner's, D84.
  • Exception expiry 90 days as judgment inside the team setting: owner's, D84.
  • Break glass inline exception with reason, expiry and approval: hers (Lauren's), D64.

Do not run with: none. No other open slice edits docs/adr/ for ADR 0003; two ADR-writing PRs racing for one number is caught by check-adr-numbers.sh.

Slice of #7572, drafted by the Issue Triage session from the thread's recorded decisions.

Dominant language
Shell
Stars
22
Forks
2
Avg merge
8h 44m
Merged PRs (30d)
926

Getting set up

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 melodic-software/claude-code-plugins

All issues in melodic-software/claude-code-plugins

Similar issues

More Shell/Bash issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.