renumber-adr

name	renumber-adr
description	Check whether ADR numbers in the current branch conflict with ADRs already on the PR's target branch, and renumber if needed. Use before merging a PR that adds new ADRs, to avoid number collisions with concurrently merged ADRs.

Renumber ADR

Overview

When multiple PRs add ADRs concurrently, they may pick the same four-digit number. This skill detects collisions against the target branch and against ADR numbers introduced by other open PRs, then renumbers the ADR file, its internal title/heading, and every reference to it across the repository.

When to Use

• Before merging a PR that introduces one or more new ADR files.
• When the user asks to check or fix ADR numbering.
• When invoked via /renumber-adr.

Process

Follow these steps in order. Do not skip steps.

1. Identify new ADR files in this branch

Determine the target branch for the PR. If the user provides it as an argument, use that. Otherwise:

gh pr view --json baseRefName --jq '.baseRefName' 2>/dev/null || echo main

Then find ADR files that are new in this branch (not present on the target):

git diff --name-only --diff-filter=A <target-branch>...HEAD -- docs/ADRs/

If no new ADR files are found, report that there is nothing to renumber and stop.

2. Check for number collisions

List existing ADR files on the target branch:

git ls-tree --name-only <target-branch> docs/ADRs/

For each new ADR file, extract its four-digit number from the filename (NNNN-short-description.md). Check whether any file with the same NNNN prefix exists on the target branch.

If there are no collisions with the target branch, continue to step 3 anyway — there may still be collisions with numbers claimed by other open PRs.

3. Collect in-flight ADR numbers and check for collisions

Collect all taken ADR numbers from these three sources:

1. Target branch ADR files (from step 2).
2. Other new ADR files in this branch (to avoid collisions among the branch's own ADRs).
3. ADR files introduced by other open PRs. This is critical — multiple PRs may be adding ADRs concurrently. Run the helper script to collect every ADR number from open PRs targeting the same base branch:

bash skills/renumber-adr/scripts/inflight-adr-numbers.sh <target-branch> <current-pr-number>

Pass the current PR number so the script excludes it (avoiding self-collision). The script prints one four-digit number per line. If it produces no output, there are no in-flight ADR numbers to worry about.

Combine all three sets of taken numbers. For each new ADR in this branch, check whether its number appears in the combined set. If none of the new ADR numbers collide with any taken number, report that all numbers are clear and stop.

For each colliding ADR, pick the lowest unused four-digit number.

4. Rename the file

git mv docs/ADRs/NNNN-old-slug.md docs/ADRs/MMMM-old-slug.md

5. Update references inside the ADR

The ADR file itself contains the number in several places. Update all of them:

• Frontmatter title: e.g. title: "2. Initial Fullsend Design" — uses the number without leading zeros.
• Markdown heading: e.g. # 2. Initial Fullsend Design — same format.

Read the file and update these occurrences. The number in the title and heading uses the integer form (no leading zeros), not the four-digit padded form.

6. Update references across the repository

Search the entire repository for references to the old ADR and update them. There are several patterns to find:

1. Filename references (in markdown links): NNNN-slug.md — update the four-digit prefix to the new number.
2. Display text references: ADR NNNN — update the four-digit number in link text and plain text.
3. Section heading references in prose (e.g. ## Reference workflow components (ADR NNNN)) — update the number.

Search broadly:

# Find all files referencing the old filename
grep -rl "NNNN-slug" .

# Find all files referencing "ADR NNNN" (display text or plain text)
grep -rl "ADR NNNN" .

For each file found, read it and update all occurrences. Be careful to match the exact old filename and number — do not accidentally rename unrelated four-digit sequences.

7. Verify and report

After all renames and reference updates:

• List the changes made: old filename -> new filename, and the count of files with updated references.
• Run pre-commit run --files <all-changed-files> to verify nothing is broken.
• Report the result to the user.

Constraints

• Only renumber ADRs that are new in this branch. Never renumber ADRs that already exist on the target branch.
• Preserve the slug. Only the four-digit number prefix changes; the descriptive slug (short-description) stays the same.
• Update every reference. A missed reference is a broken link. Search thoroughly.
• Handle multiple ADRs. If the branch adds several ADRs and more than one collides, renumber all of them before updating references (so cross-references among the new ADRs are correct).
• Check open PRs. Always check ADR numbers introduced by other open PRs targeting the same base branch. A number that is clear on the target branch today may collide with another PR that merges first.
• Do not modify ADR content beyond the number in the title and heading. Substantial ADR content is not rewritten once accepted; this skill only fixes numbering.