Bugfix

/bugfix — Bug Fix Workflow

You are fixing a bug using a streamlined workflow that skips the full spec ceremony but follows the same deployment strategy as a feature: changes land via PR, ride the project's CI/CD pipeline (staging-first if the project has one), and aren't marked resolved until every declared deploy target is confirmed.

Ethos

!test -s .adlc/ETHOS.md && cat .adlc/ETHOS.md || echo No ethos found — run /init to vendor .adlc/ETHOS.md

Context

• Project config: !test -s .adlc/config.yml && echo present — read .adlc/config.yml before Step 1 || echo none — single-repo legacy mode
• Bug template: !cat .adlc/templates/bug-template.md || echo No bug template found — run /init to vendor .adlc/templates
• Conventions: !cat .adlc/context/conventions.md || echo No conventions found
• Existing bugs: !ls .adlc/bugs/ || echo No bugs directory found

Input

Bug report: $ARGUMENTS

Prerequisites

Before proceeding, verify that .adlc/bugs/ exists. If it doesn't, stop and tell the user: "The .adlc/ structure hasn't been initialized. Run /init first."

Instructions

Phase 1: Report

1. If given a bug description (not a BUG ID), create a bug report:
   • Determine the next BUG ID using the global atomic counter file ~/.claude/.global-next-bug (shared across all repos for unique IDs, mirroring the REQ counter — see LESSON-004). The counter is now a cache, not the authority — the remote is the source of truth (REQ-518): allocation derives the remote high-water, takes max(remote, local) + 1, and fast-forwards the local counter, all inside the existing mkdir lock. Allocate via the shared partials/id-alloc.sh helper (BR-5 — the lock block + its REQ-416/LESSON-014 rationale live in the partial). Source it and call adlc_alloc_id in the same fenced block (the cross-fence-fn rule — see conventions.md "Bash in skills"):

     if [ -f .adlc/partials/id-alloc.sh ]; then . .adlc/partials/id-alloc.sh; else . ~/.claude/skills/partials/id-alloc.sh; fi
     BUG_NUM=$(adlc_alloc_id bug)
     # `exit 1` inside adlc_alloc_id's subshell terminates only the subshell — BUG_NUM
     # would be silently empty. Guard the parent context (REQ-416 verify D-pass).
     [ -n "$BUG_NUM" ] || { echo "ERROR: failed to allocate BUG number — aborting before writing malformed bug report" >&2; exit 1; }
     # If ADLC_ALLOC_DEGRADED=1 (remote unreachable), the helper warned on stderr — note
     # "id allocated without remote verification — verify before PR" (BR-3). Never block.

     adlc_alloc_id bug handles the absent-counter bootstrap scan internally (highest BUG-xxx under $ADLC_REPOS_ROOT; bug reports are .md files so the scan uses -type f), the mkdir lock that serializes concurrent sessions, and the remote high-water max. Single-machine behavior is unchanged when the remote has no higher allocation (BR-7). Note: the legacy per-repo .adlc/.next-bug counter is deprecated and no longer consulted — existing files can be left in place but should not be read or written.
   • Pre-push recheck (BR-4, BR-8). Before the bug file is committed on a branch for push, re-verify BUG-<id> against the remote — a colleague on another machine may have pushed the same id since allocation. Source partials/id-recheck.sh and call adlc_recheck_id in the same fenced block; a collision halts with the renumber instruction rather than pushing a duplicate:

     if [ -f .adlc/partials/id-recheck.sh ]; then . .adlc/partials/id-recheck.sh; else . ~/.claude/skills/partials/id-recheck.sh; fi
     BUG_ID=$(printf 'BUG-%03d' "$BUG_NUM")
     if ! adlc_recheck_id bug "$BUG_ID"; then
       echo "Halting: $BUG_ID collides on the remote — renumber before pushing (see message above)." >&2
       exit 1
     fi

   • Create .adlc/bugs/BUG-xxx-slug.md (always in the current repo — this becomes the "primary" for the bug) using the template from .adlc/templates/bug-template.md
   • Fill in: description, reproduction steps (if known), expected vs actual behavior, environment
   • Set status to open, severity based on impact
   • Cross-repo: if .adlc/config.yml declares siblings AND the bug's fix likely lives in a sibling (e.g., a frontend symptom whose root cause is in a backend repo), add a repo: <sibling-id> field to the bug frontmatter. If the fix spans multiple repos, add a touched_repos: [<id>, <id>] field. The repo: field determines where Phase 3's commit and Phase 4's PR land.
2. If given a BUG ID, read the existing bug report — note any repo: or touched_repos: field for routing.

Phase 2: Analyze

1. Launch Explore agents to trace the bug:

   • Search for relevant code paths based on the bug description
   • Trace the execution flow that triggers the bug
   • Identify the root cause (not just symptoms)

2. Read the identified files to understand the context

3. Document the root cause in the bug report's "Root Cause" section

4. Validate the analysis:

   • Re-read the affected code paths to confirm the root cause is correct
   • Check for secondary issues or edge cases related to the bug
   • Adjust the root cause and fix approach if validation reveals inaccuracies

5. Update the bug report with the validated findings

6. Attribute the incident to the REQ that shipped its cause (REQ-593). Root-cause analysis has just produced a file/line set; that set is exactly what git blame needs to name the change that introduced the behavior. Derive the candidates, then record or refuse — never guess.

   Derivation is per-repo (BR-8), keyed off the bug's repo: / touched_repos: frontmatter: blame each repo against its own history, but validate every id against the primary repo, because in cross-repo mode spec directories exist only there (BR-5). Source the partial and call it in the same fenced block (the cross-fence-fn rule — see conventions.md "Bash in skills"):

   if [ -f .adlc/partials/attribution.sh ]; then . .adlc/partials/attribution.sh; else . ~/.claude/skills/partials/attribution.sh; fi
   # <repo> = the repo whose history to blame (this repo, or a sibling's path from
   # .adlc/config.yml). <primary> = the repo holding .adlc/specs — always the current repo.
   # <file> <start> <end> = one root-cause range from step 4. Repeat per range, per repo.
   adlc_attr_blame_reqs "<repo>" "<primary>" "<file>" "<start>" "<end>"

   Union the output across every range and repo, then act on the distinct id count:

   • 0 candidates — write attribution: none and leave introduced_by: []. Emit exactly one stderr line naming the reason (no trailer in the blamed commits / the lines pre-date the trailer convention / the file is untracked), then continue to Phase 3. A bug with no derivable REQ is a normal outcome, not a failure: never halt, and never fabricate an id (BR-7).
   • 1 candidate — write introduced_by: [REQ-xxx] and attribution: derived.
   • 2+ candidates — present all of them and write nothing. Ask the operator to select one or more; selecting several is legitimate when a defect genuinely emerges from the interaction of multiple merged REQs, and is what makes introduced_by an array. Record the selection with attribution: derived. Do not auto-union and do not pick the lowest id or the most recent commit — a detected-but-unresolvable attribution refuses rather than guessing (BR-3, LESSON-483).

   Never write an id the partial did not return: it has already enforced the strict ^REQ-[0-9]{3,6}$ pattern and confirmed the spec directory exists (BR-5). A trailer citing a REQ with no spec directory is dropped on purpose.

   The reverse edge is not written anywhere. REQ → its incidents is derived at read time by scanning .adlc/bugs/ frontmatter (/status does this); storing it in the REQ spec would rot the moment an artifact is moved or renumbered (BR-4, LESSON-019).

Phase 3: Fix

1. Determine target repo: if the bug's frontmatter has repo: and it names a sibling (not this repo), cd into that sibling's path from .adlc/config.yml and do all fix work there. For touched_repos: [...], cd into each in turn — one commit per repo, on a shared branch name. Otherwise fix in the current repo.
2. Proceed directly with the validated fix approach — do not pause for user confirmation
3. Implement the fix following project conventions
4. Ensure the fix addresses the root cause, not just symptoms
5. Update related test files if the fix changes behavior
6. Track progress with TodoWrite

Phase 4: Verify

1. Run the test suite: npm test (or appropriate test command)
2. If tests fail, fix and re-run
3. Update the bug report (do NOT mark resolved yet — that happens in Phase 6 after the fix is merged and deployed):
   • Leave status as open (or set to in-review if your project uses that value)
   • Fill in "Resolution" section with what was changed and why
   • Fill in "Files Changed" section with specific file paths
   • Update the updated date
4. Present an interim summary:
   • Root cause
   • What was fixed
   • Files changed
   • Test results
   • Then continue to Phase 5

Phase 5: Ship — Create Pull Request(s)

For each touched repo (just the current repo in single-repo mode; each entry in touched_repos: in cross-repo mode):

1. Push the fix branch: git -C <worktree> push -u origin fix/bug-xxx-slug
2. Create the PR with adlc_forge_pr_create (source partials/forge.sh with the guarded spelling from conventions.md "Bash in skills" in the same fence; run from inside the worktree, or pass -R <owner/repo>). All PR ops route through the forge adapter, never direct gh (REQ-520 BR-1). In cross-repo mode, create the primary repo's PR last so its body can link every sibling.
   • Title: fix(BUG-xxx): short description — when cross-repo, scope to the repo (e.g., fix(api): null deref in user serializer [BUG-042]).
   • Body:

     ## Summary
     [1-2 lines describing what broke and what was fixed in THIS repo]
     
     ## Bug
     BUG-xxx: [bug title]
     Severity: [critical | high | medium | low]
     Primary repo: <primary-repo-id>
     
     ## Root Cause
     [Pulled from the bug report's Root Cause section]
     
     ## Files Changed (this repo)
     - `path/to/file.ts` — what changed and why
     
     ## Related PRs (cross-repo)
     [Omit in single-repo mode. Otherwise list each sibling PR URL — back-fill
      sibling bodies via `adlc_forge_pr_edit` once every URL is known.]
     
     ## Test Plan
     - [ ] Unit/integration tests pass locally
     - [ ] CI green on this PR
     - [ ] Staging deploy succeeded (verified in Phase 6)
     - [ ] Production deploy succeeded (verified in Phase 6)

3. After all sibling PRs exist, edit each one (adlc_forge_pr_edit <prUrl> --body ...) to fill in the Related PRs section.
4. Wait for CI to pass on every PR: gh pr checks <prUrl>. If CI fails, diagnose and re-push — never bypass with --no-verify or admin-merge.
5. Report all PR URLs to the user, grouped by repo.