Bugfix 8 ACTIVITIES 5 STAGES
About The short path: a report becomes a reproduction, a cause, a guarded fix, and a release. No spec, no planning — the bug is the spec.
The bug is the spec, which is why this path has no Define stage and no
acceptance criteria. Somebody has already told you what the software should
have done; the whole question is whether you can make it do that without
breaking something else.
What it assumes
Reproduce before diagnosing. ① sits on reproduction because everything
downstream is cheap once the bug reproduces on demand and guesswork until it
does. A team that skips this ships fixes to hypotheses.The regression test is written from the reproduction, before the fix.
Written after, it only proves the fix compiles.Urgency is not an exemption. ship-fix runs the same release gate as
Feature does.
Why the ends are thin
reproduce-bug is open and review-fix carries nothing at all, and the
difference between those two is the whole point of the notation. The first is
work this team wants to hand over and has not found the tool for. The second is
work they intend to keep doing themselves — one reviewer, one question, no
tooling wanted.
Source reference/processes/bugfix.yaml
One file is one process. The page has no write path — the editor is the editor.
Triage Report Triage Product Lead
An untriaged report is a rumour; triage decides whether it is work at all.
Consumes Nothing — this is a source activity.
Produces Bug Report
→ Reproduce , Review Fix Recommended tooling here Mention on the Thread GitHub Actions · DELEGATED + REVIEW Standing advice. When the report arrived on a thread, answer it there rather than in a tool nobody reading the history will open. The answer then sits beside the question for whoever asks about this a year from now.
Reproduce Diagnose Engineer
A bug you cannot reproduce on demand is a hypothesis, and fixes to hypotheses do not hold.
Consumes Bug Report
← Triage Report · handoff Produces Reproduction
→ Locate Cause , Write Regression Test ① Tooling OPEN SLOT Something that turns a report into a runnable case — the environment, the data and the steps, standing up on demand. Today every reproduction is rebuilt by hand from whatever the reporter remembered.
Recommended tooling here /bisect Claude Code Let history say when the behaviour changed — the first good build is a reproduction recipe when the report is not one.
Locate Cause Diagnose Engineer
The first place the symptom appears is rarely the place the defect lives.
Consumes Reproduction
← Reproduce ①
Write Regression Test Fix Engineer
The test is written from the reproduction, before the fix, or it only proves the fix compiles.
Consumes Reproduction
← Reproduce ① Produces Regression Test
→ Apply Fix , Assemble Evidence
Apply Fix Fix Engineer
The narrowest change that turns the regression test green.
Consumes Root Cause
← Locate Cause Regression Test
← Write Regression Test Produces Change Set
→ Assemble Evidence , Ship Fix Recommended tooling here Session Reset Claude Code · MANUAL After the second failed correction, stop and start over with an opening that includes what the failures taught. A third correction is read against both earlier ones, which is why the third rarely works.
Plan Mode Claude Code · ASSISTED Drop out of writing and re-read the ground. A loop is usually a wrong model of the code rather than a wrong edit, and no number of edits fixes that.
Assemble Evidence Verify Engineer
The proof a bugfix needs is narrow — the test failed before and passes after.
Consumes Change Set
← Apply Fix Regression Test
← Write Regression Test Produces Evidence Pack
→ Review Fix
Review Fix Verify Reviewer
The review asks one question — does this close the reported bug without widening the blast radius.
Consumes Evidence Pack
← Assemble Evidence · handoff Bug Report
← Triage Report · handoff Produces Review Verdict
→ Ship Fix
Ship Fix Ship Release Operator
A bugfix ships on the same gate as anything else; urgency is not an exemption.
Consumes Review Verdict
← Review Fix · handoff Change Set
← Apply Fix · handoff Produces Release → leaves the process
Plan Mode Claude Code Engineer
built-in mode
Reads and reasons without writing — the cheap place to be wrong.
Reads the repository and reasons about the change while edits stay
blocked. The session produces a plan, and nothing is written until someone
approves it.
The value is where the mistake lands. A wrong plan costs a conversation; a
wrong change costs a review cycle, and sometimes a revert.
Reach for it when
the change touches code nobody on the call has read recently
there is more than one defensible approach and the choice matters
the work will be handed to an unattended run afterwards
Where the human stands
delegated-review when planning the work: the agent drafts, and the
approval is a real gate — editing stays blocked until it is given.
assisted when the question is how to cut the work up rather than how to
do it, because that answer depends on the team, not on the code.
Reached for · recommended in Apply Fix Drop out of writing and re-read the ground. A loop is usually a wrong model of the code rather than a wrong edit, and no number of edits fixes that.
Agent Session Claude Code Engineer
agentic edit loop
The default working loop — explore, edit, run, repeat, under review.
The ordinary working loop: the agent reads, edits, runs the tests, reads
the failure, and goes again — with an engineer reading every diff.
What holds it
The loop is only as good as the check at the end of it. A session with a
test suite that actually fails on a wrong change can run a long way; a
session whose only oracle is the agent's own reading of its work cannot,
and should be kept short and reviewed closely.
Where the human stands
delegated-review, and this is the ceiling until verification is
mechanical. Running with permissions disabled is not a higher rung — it is
the same loop with nothing holding it.
Reached for fills the slot in Apply Fix
Explore Subagent Claude Code Engineer
read-only search agent
Sweeps the codebase and returns the conclusion, not the file dumps.
Answers a question about the codebase in a separate context , and
returns the answer rather than the files it read. Write and Edit are
denied to it, so the worst outcome of a wrong answer is a wasted read.
Reach for it when
the question spans more directories than one reading will cover
the answer is one paragraph but finding it means opening thirty files
the main session's context is better spent on the change itself
Where the human stands
delegated-review. Read-only by construction, so the delegation is
genuinely cheap — but the conclusion is still a claim, and a claim that
decides the shape of a change deserves one file opened to confirm it.
Reached for fills the slot in Locate Cause
/test-from-repro Claude Code Engineer
test authoring skill
Turns a reproduction into a regression test that fails before the fix.
Turns a reproduction into a test, written before the fix, that fails
on the current code.
The order is the whole point. A test written after the fix proves the fix
compiles. A test that failed first, and passes now, proves the fix
addressed the bug that was reported.
Where the human stands
delegated-review. The check is mechanical and the agent cannot argue
past it: red before, green after, or the work is not done.
Reached for fills the slot in Write Regression Test
/evidence-block Claude Code Engineer
evidence assembly skill
Collects the proof a reviewer needs into one block they can read.
Gathers what a reviewer would otherwise reconstruct — what was run, what it
returned, which criteria it maps to — into one block at the top of the
change.
Reach for it when
the change is larger than a reviewer will re-run themselves
the interesting part of the work is a behaviour, not a diff
the review is asynchronous and the author will not be there to answer
Where the human stands
delegated-review. Assembling the evidence is clerical; judging whether
it is sufficient is the review, and the review stays human here on
purpose.
Reached for fills the slot in Assemble Evidence
/bisect Claude Code Engineer
history search skill
Searches history for the change that introduced the behaviour.
Searches the history for the commit where the behaviour changed, by
running the reproduction against successive revisions.
It needs a reliable reproduction to be worth anything. Against an
intermittent failure it finds the commit where the failure happened to
show up, which is not the same claim and is more convincing than it should
be.
Where the human stands
assisted. The search is mechanical, but reading the guilty commit and
deciding whether it is the cause or merely the trigger is the diagnosis,
and that is the work.
Reached for · recommended in Reproduce Let history say when the behaviour changed — the first good build is a reproduction recipe when the report is not one.
Session Reset Claude Code Engineer
session hygiene
Ends a session that has become mostly a record of what did not work.
Ends the session and starts again, carrying forward what was learned rather
than the history of learning it.
Why starting over beats pushing on
A session that has failed twice at the same thing is now mostly failed
approaches, and each new attempt is read against all of them. The rule of
thumb is blunt on purpose: after the second failed correction, stop, and
write a better opening prompt using what the failures taught.
Where the human stands
manual, honestly. Deciding what mattered out of a long session is the
whole job, and it is the part no summary does for you.
Reached for · recommended in Apply Fix After the second failed correction, stop and start over with an opening that includes what the failures taught. A third correction is read against both earlier ones, which is why the third rarely works.
Mention on the Thread GitHub Actions Product Lead
event-triggered agent
Answers on the issue or pull request where the work is already discussed.
Answers where the conversation is already happening: mentioned on an issue
or a pull request, it replies on that thread and can push changes to it.
The value is placement as much as capability. The answer lands next to the
question, in the record someone will read in a year when they ask why the
change looks like this.
Where the human stands
delegated-review. It can answer a report; deciding the report is work
remains a triage decision.
Reached for recommended in Triage Report Standing advice. When the report arrived on a thread, answer it there rather than in a tool nobody reading the history will open. The answer then sits beside the question for whoever asks about this a year from now.
Backlog Triage Agent Jira + Rovo Product Lead
rovo agent
Reads the backlog for what is already known about this work.
Searches the backlog and the issue history for what has already been said
about this work: the duplicate, the earlier attempt, the decision that
closed it last time.
Reach for it when
the request sounds familiar and nobody can name the ticket
the area has been changed before by someone who has since left
triage is about to estimate work that was already estimated once
Where the human stands
assisted. It surfaces what exists. Whether a prior ticket makes this one
a duplicate, a regression, or a genuinely new request is a triage
decision.
Reached for fills the slot in Triage Report
Release Gate CI Pipeline Release Operator
pipeline gate
Releases on green; a human can always hold the gate.
The pipeline builds, runs the suite, and proceeds unless someone holds it.
No model is in the loop: the checks are the checks the team wrote.
Where the human stands
gated-autonomous — the top rung, honestly earned. The release happens
without anyone approving it, and a human can stop it at any point. Both
halves have to be true; a gate nobody can hold is not this rung, and a
release that waits for approval is not either.
Reached for fills the slot in Ship Fix
Spec ARTIFACT
What the change is for and what it must do, written before anyone builds it.
A spec is done when a reader who was not in the conversation can say what
is in scope and what is not.
Produced by Nothing in this process — it arrives from outside.
Consumed by Nobody — it leaves the process here.
Work Plan ARTIFACT
The route from spec to change: the order of the work, what it touches, and
what has to be true before it starts.
Produced by Nothing in this process — it arrives from outside.
Consumed by Nobody — it leaves the process here.
Acceptance Criteria ARTIFACT
The checks the change is measured against, agreed before the work begins.
Written as observable outcomes, not as instructions — a criterion that
describes how the work is done cannot fail honestly.
Produced by Nothing in this process — it arrives from outside.
Consumed by Nobody — it leaves the process here.
Task List ARTIFACT
The spec cut into pieces small enough that one of them can be finished,
reviewed, and shipped without holding the rest in your head.
Produced by Nothing in this process — it arrives from outside.
Consumed by Nobody — it leaves the process here.
Context Notes ARTIFACT
What the code and the history already say about the area being changed:
constraints, prior decisions, and the traps a reader would otherwise walk into.
Produced by Nothing in this process — it arrives from outside.
Consumed by Nobody — it leaves the process here.
Draft Change ARTIFACT
The change while it is still being argued with — compiling, incomplete, and
not yet asking anyone for judgment.
Produced by Nothing in this process — it arrives from outside.
Consumed by Nobody — it leaves the process here.
Change Set ARTIFACT
The change offered for review: the diff, its tests, and nothing left in it
that its author would not defend.
Consumed by Assemble Evidence Verify · Engineer Ship Fix Ship · Release Operator
Test Suite ARTIFACT
The executable statement of what must keep working. It is the evidence the
rest of the process quotes.
Produced by Nothing in this process — it arrives from outside.
Consumed by Nobody — it leaves the process here.
Evidence Pack ARTIFACT
What proves the change does what it claims: test runs, checks, and the
output a reviewer would otherwise have to reproduce by hand.
Produced by Assemble Evidence Verify · Engineer Consumed by Review Fix Verify · Reviewer
Review Verdict ARTIFACT
The reviewer's decision on conformance — the change matches the intent, or
it does not and here is where.
Produced by Review Fix Verify · Reviewer Consumed by Ship Fix Ship · Release Operator
Release Candidate ARTIFACT
A change set that has passed review and is packaged for production, waiting
only on the decision to go.
Produced by Nothing in this process — it arrives from outside.
Consumed by Nobody — it leaves the process here.
Release ARTIFACT
The change in production, with the record of when it went and what it
contained.
Produced by Ship Fix Ship · Release Operator Consumed by Nobody — it leaves the process here.
Bug Report ARTIFACT
The claim that something is wrong, as it arrived — from a user, an alert, or
a colleague. It is a report, not yet a fact.
Produced by Triage Report Triage · Product Lead Consumed by Reproduce Diagnose · Engineer Review Fix Verify · Reviewer
Reproduction ARTIFACT ① THE CONSTRAINT
The steps that make the bug happen on demand. Until this exists, the root
cause is a hypothesis and any fix is a guess.
Everything downstream is cheap once the bug reproduces on demand, and guesswork until it does. The reproduction is where this path is won or lost.
Produced by Reproduce Diagnose · Engineer Consumed by Locate Cause Diagnose · Engineer Write Regression Test Fix · Engineer
Root Cause ARTIFACT
The mechanism that produced the bug, stated deeply enough that the fix is
obvious and the class of bug — not the instance — is closed.
Produced by Locate Cause Diagnose · Engineer
Regression Test ARTIFACT
The test that fails on the old code and passes on the new one. It is what
turns a fix into a guarantee.
Produced by Write Regression Test Fix · Engineer Consumed by Apply Fix Fix · Engineer Assemble Evidence Verify · Engineer
Incident Record ARTIFACT
The live account of an open incident: what is known, what was tried, and
when. Written while it is happening, because memory rewrites it afterwards.
Produced by Nothing in this process — it arrives from outside.
Consumed by Nobody — it leaves the process here.
Impact Assessment ARTIFACT
Who is affected and how badly. Severity is set from this, and every
communication downstream quotes it.
Produced by Nothing in this process — it arrives from outside.
Consumed by Nobody — it leaves the process here.
Status Update ARTIFACT
What people outside the response need to know right now: current state,
what is being done, and when the next update comes.
Produced by Nothing in this process — it arrives from outside.
Consumed by Nobody — it leaves the process here.
Mitigation ARTIFACT
The action that stops the harm. It is not the fix — a mitigation that is
mistaken for one leaves the cause in place.
Produced by Nothing in this process — it arrives from outside.
Consumed by Nobody — it leaves the process here.
Postmortem ARTIFACT
The account written after the incident closes: what happened, why the system
allowed it, and what changes so the next one is smaller.
Produced by Nothing in this process — it arrives from outside.
Consumed by Nobody — it leaves the process here.
Follow-Up Work ARTIFACT
The commitments a postmortem makes, handed back to the delivery process as
real work rather than as good intentions.
Produced by Nothing in this process — it arrives from outside.
Consumed by Nobody — it leaves the process here.
Product Lead ROLE 1 ACTIVITIES 1 FILLED
Owns intent — what to build and why.
Decides what the team builds next and why it is worth building. Holds the
spec and the acceptance criteria, and is the one who can say a change is
out of scope .
Owns
The spec — what the change must do, in the team's own words.Acceptance criteria — the list a reviewer later reads the change against.Scope — the standing authority to say "not in this change".
Delegation posture
Mostly assisted . Intent is the one thing the team cannot hand to a tool,
so the leverage is in drafting and pressure-testing it — grill-me against
the criteria, not a generated spec.
A spec a tool wrote is a spec nobody decided. The ladder tops out here on
purpose.
Owns Triage Report Triage · DELEGATED + REVIEW
Engineer ROLE 5 ACTIVITIES 4 FILLED
Owns the change and its proof.
Turns a spec into a change set and the evidence that it works. Owns the
code, its tests, and the honesty of both.
A change, end to end
Read the spec and the acceptance criteria — one test per criterion.
Decompose before building; re-decompose when the task turns out bigger.
Implement, run the suite, and hand back the change with its evidence.
Delegation posture
Work Level Implementation delegated-reviewTest writing delegated-reviewDecomposition assisted
This is where delegation runs highest — implementation and test writing are
the work most safely handed over, provided the proof comes back with it .
See Layer 3 — Capability fills for
what each rung claims.
Owns Reproduce Diagnose · open slot Locate Cause Diagnose · DELEGATED + REVIEW Write Regression Test Fix · DELEGATED + REVIEW Apply Fix Fix · DELEGATED + REVIEW Assemble Evidence Verify · DELEGATED + REVIEW
Reviewer ROLE 1 ACTIVITIES 0 FILLED
Owns conformance — the change matches the intent.
Judges whether the change does what the spec asked, and says so in a
verdict. Reviews conformance and risk , not taste.
Reads
The acceptance criteria — the only thing the change is measured against.
The change set and its evidence pack.
What the change touches that the spec never mentioned.
Does not read
Style. A formatter has an opinion; a reviewer does not need one.
A tool can find defects here, but the verdict stays human: it is a decision
about intent, and intent is not in the diff .
Release Operator ROLE 1 ACTIVITIES 1 FILLED
Owns the path to production.
Owns everything between an approved change and a release: packaging,
promotion, the go decision, and the way back if it goes wrong.
The gate
Release runs gated-autonomous — the pipeline builds, tests, and proceeds
unless someone holds the gate. The operator is the one who can hold it.
Always ready to answer
What is in this release?
What breaks if it is wrong?
How do we get back to the previous state, and how long does that take?
Autonomy at the gate is not the absence of a human. It is a human who has
decided not to intervene yet .
Owns Ship Fix Ship · GATED AUTO
Claude Code HARNESS 7 TOOLS
Agentic CLI — skills, plan mode, subagents.
An agentic CLI that works in the repository: reads the code, runs commands,
and edits files under review. Skills, plan mode, and subagents are how a
team encodes its own practice into it.
Its reach is the reason most of the delivery process can be delegated at
all — and the reason review stays the gate.
What lives on this shelf
Kind Examples Encoded practice skills, CLAUDE.md, scoped rule files Bounded delegation plan mode, read-only subagents Deterministic gates lifecycle hooks, permission rules Unattended runs batch scripts, machine-readable results
The last row runs with nobody there to answer a question, so the judgment
moves out of the session and into what is written before it starts — the
prompt, the permitted actions, the exit condition. Same agent, same shelf;
what changes is when the thinking happens, not where it runs.
The row above it is the one that changes the ladder. Instructions to the agent
are advisory and a long session forgets them; a hook is a script at a fixed
point that does not negotiate. Where this team runs gated-autonomous
inside a session, it is a hook doing the holding.
Tools Plan Mode built-in mode · 1 uses Agent Session agentic edit loop · 1 uses Explore Subagent read-only search agent · 1 uses /test-from-repro test authoring skill · 1 uses /evidence-block evidence assembly skill · 1 uses /bisect history search skill · 1 uses Session Reset session hygiene · 1 uses
GitHub Actions HARNESS 1 TOOLS
Agent work triggered by what happens on the repository.
Runs the agent in response to repository events — an issue opened, a pull
request raised, a mention in a comment — inside a runner, under the app's
own permissions. Nobody's laptop is involved and no one has to remember to
start it.
What it changes
Work arrives where the conversation already is. A question asked on an
issue gets answered on that issue, and the answer is visible to everyone
who will later ask why the change looks like this.
Where the human stands
Deliberately low on the ladder here. An automated comment on every pull
request is a second pair of eyes, never a verdict — this team keeps the
verdict human, and an agent that posts on every change is not the thing
that should be allowed to approve one.
Tools Mention on the Thread event-triggered agent · 1 uses
Jira + Rovo HARNESS 1 TOOLS
Work tracking with Rovo agents.
Where work is tracked and where the team's written history lives. Rovo
agents act inside that record rather than beside it, which is what makes
planning and decomposition delegable.
Tools Backlog Triage Agent rovo agent · 1 uses
CI Pipeline HARNESS 1 TOOLS
Build, test, and release automation.
The automation that builds, tests, and ships. It is the only harness that
routinely runs gated-autonomous : it proceeds on its own and a human
holds the stop.
Tools Release Gate pipeline gate · 1 uses
Observability Stack HARNESS 0 TOOLS
Metrics, logs, traces, and alert routing.
Metrics, logs, traces, and the alert routing on top of them. It is what
turns "something is wrong" into an impact assessment, and what the incident
process reads from throughout.
Tools Nothing on the shelf runs in it yet.
Task bigger than planned EVENT 0 RECOMMENDATIONS
Mid-task the work turns out larger than its plan — stop and re-decompose before pushing on.
Reached for when it happens Defined, but nothing is bound to it yet.
Spec is ambiguous EVENT 0 RECOMMENDATIONS
Two readings of the spec survive contact with the work.
Reached for when it happens Defined, but nothing is bound to it yet.
Rework requested EVENT 0 RECOMMENDATIONS
The review verdict comes back with required changes.
Reached for when it happens Defined, but nothing is bound to it yet.
Cannot reproduce EVENT 1 RECOMMENDATIONS
The report does not reproduce on demand — the bug is a hypothesis until it does.
Reached for when it happens
Blast radius unknown EVENT 0 RECOMMENDATIONS
The signals do not yet say who is affected or how badly — severity cannot be set.
Reached for when it happens Defined, but nothing is bound to it yet.
Mitigation does not hold EVENT 0 RECOMMENDATIONS
The service recovers and degrades again — the mitigation treated a symptom.
Reached for when it happens Defined, but nothing is bound to it yet.
Context is full EVENT 0 RECOMMENDATIONS
The session has read more than it can hold, and decisions made earlier stop being honoured.
Reached for when it happens Defined, but nothing is bound to it yet.
Same failure survives correction EVENT 2 RECOMMENDATIONS
Two corrections in, the same thing is still wrong, and the history is now mostly failed approaches.
Reached for when it happens Session Reset in Apply Fix Plan Mode in Apply Fix
No check to run EVENT 0 RECOMMENDATIONS
The work looks done and nothing in the repository produces a pass or a fail on it.
Reached for when it happens Defined, but nothing is bound to it yet.
Question has no edges EVENT 0 RECOMMENDATIONS
A question was asked without a boundary, and the reading it needs has no natural end.
Reached for when it happens Defined, but nothing is bound to it yet.
Verdict is about a class, not a change EVENT 0 RECOMMENDATIONS
The finding would apply to the next change too — it is a rule, not a defect.
Reached for when it happens Defined, but nothing is bound to it yet.
Work splits into independent units EVENT 0 RECOMMENDATIONS
The task is many similar pieces that do not depend on each other.
Reached for when it happens Defined, but nothing is bound to it yet.
Approving without reading EVENT 0 RECOMMENDATIONS
Enough permission prompts have gone by that clicking has replaced reading.
Reached for when it happens Defined, but nothing is bound to it yet.