# Bugs Flow

> Explicitly selected analyze/fix/review lifecycle around one canonical bug document. Use when the user chooses $bugs-flow or binding task instructions require it. Symptoms, logs, crashes, Sentry issues, failed tests, and ordinary bug investigations do not select this lifecycle.

- Skill: `aelaguiz/bugs-flow` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds@latest add aelaguiz/bugs-flow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aelaguiz/bugs-flow/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: aelaguiz (https://skillmd.com/u/aelaguiz)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/aelaguiz/bugs-flow

---


# Bugs Flow

Use this workflow only after explicit selection as `$bugs-flow` or a
binding task instruction requiring it.

## When to use

- The ask is a bug report, regression, crash, incident, or Sentry investigation.
- The user has symptoms, logs, traces, QA notes, or a bug doc and wants the issue analyzed or fixed.
- The work should be driven by evidence and a single bug doc rather than by a feature plan.

## When not to use

- The task is a repo-wide audit, feature delivery, or open-ended optimization.
  Follow the user's selected scope without activating a replacement lifecycle.

## Non-negotiables

- Keep one canonical bug doc under `docs/bugs/`.
- Analyze first. Do not modify code in analyze mode.
- Prefer first-party evidence: Sentry, logs, traces, QA notes, repro steps, and code anchors.
- Only move into fix mode when the bug doc is fix-ready.
- Keep fixes minimal and localized. No runtime fallbacks, silent swallowing, or compatibility shims unless explicitly approved.
- The human-authorized outcome is the corrected behavior for the documented
  bug. During analyze/initial planning only, include the smallest evidenced
  directly competing same-contract path needed to fix the shared cause; record
  the closure or `none` and sign it off before fix mode. Apply
  `../_shared/scope-and-convergence.md`.
- Fix and review cannot widen that approved closure. A newly discovered adjacent
  improvement or owner path needs a human decision; review never reopens generic
  architecture planning.
- Review side work happens only if the user explicitly asks for review or code
  review. Once authorized, prefer a new clean same-host native critic; external
  review remains available when its concrete provider, model, lifecycle,
  isolation, automation, receipt, or other benefit is worth the added process
  and integration cost under the shared agent policy.
- Apply `$prompt-authoring` to every actual populated implementer or critic
  brief. The human-authorized corrected behavior, approved closure, safety
  constraints, and proof obligations are binding. The bug doc's ranked
  hypotheses, most likely cause, investigation narrative, and candidate fix
  plan remain challengeable evidence unless a human explicitly selected them.
- Do not let "review" become an excuse to reopen generic architecture planning.

## First move

1. Read `references/bug-doc-contract.md`.
2. Read `references/shared-doctrine.md`.
3. Read `../_shared/scope-and-convergence.md`.
4. Read `../_shared/agent-orchestration-policy.md` before dispatching an
   implementer or critic.
5. Resolve the mode:
   - analyze
   - fix
   - review
6. Resolve `DOC_PATH` and read it fully if it already exists.
7. If the user asked for fix or review but the doc is not ready, step back and repair the investigation first.
8. Read the mode reference and `references/quality-bar.md`.

## Parent And Child Roles

- The active parent owns the human-authorized bug scope, approved convergence
  closure, bug-doc writes, decomposition, result accounting, synthesis,
  accepted findings, and final review verdict. Capture current git status and
  the relevant diff before a read-only critic runs, then compare current state
  before accepting its evidence.
- If implementation is delegated, start the implementer as a new clean
  same-host native child by default and preserve its exact handle. In Codex set
  `fork_turns: "none"`; in Claude use a clean named or custom subagent, not a
  bare conversation fork or skill `context: fork` shorthand. Use bounded or
  full inherited context only for a named dependency that exists solely in
  chat; ordinary context travels through the bug doc, exact paths, and a
  bounded brief.
- Each independent review or recheck starts as a different new clean critic
  with the strongest read-only capability available and an explicit no-edit,
  no-write contract. Send every accepted repair finding back to the exact
  implementer that owns the fix; never resume a critic as an implementer and
  never reuse a prior critic for the next independent gate.
- Implementers and critics may use their own native sub-agents on their own
  host at will; they may not start external agents. If multiple independent
  review lenses genuinely help, bound the parent's own fanout by host slots,
  shared-file or shared-state collision risk, and the parent's capacity to
  inspect and integrate every return.
- External review is a transport choice, not a freshness requirement or a
  prohibited lane. Use it when a concrete benefit is worth its added cost; the
  same clean critic, read-only, return, parent-state-check, and independent
  recheck contracts still apply.

## Workflow

### 1) Analyze mode

- Create or repair the bug doc.
- Ingest evidence and write ranked hypotheses.
- Mark the issue fix-ready only when the likely root cause is concrete enough to act on.

### 2) Fix mode

- Read the bug doc as the canonical evidence and scope record. Treat its
  human-authorized corrected behavior, approved closure, constraints, and proof
  obligations as the implementation contract; do not treat its hypotheses,
  likely cause, or candidate fix plan as unquestionable.
- Write or tighten the candidate fix plan in the doc without making it the
  only permissible implementation path.
- Implement the smallest credible fix locally.
- If an implementer child owns the fix, preserve its exact handle so accepted
  review repairs resume that same role and scope.
- Update verification, risk level, and outcome in the doc.

### 3) Review mode

- Only when explicitly requested by the user.
- Start a new clean independent critic and audit the implementation against the
  human-authorized bug contract and current code without letting the critic
  write files or anchoring it on the bug doc's diagnosis.
- The parent integrates only accepted feedback. Resume the exact implementer
  for those repairs, allowing it to rebut the finding or proposed direction
  with code evidence, then use another new clean critic for every independent
  recheck.
- If no explicit review ask exists, do not launch review side work.

## Output expectations

- Update `DOC_PATH` in every mode.
- Keep console output short:
  - Bug North Star reminder
  - punchline
  - what changed
  - tests or evidence gathered
  - risks or blockers
  - next action

## Reference map

- `references/bug-doc-contract.md` - bug doc structure, evidence rules, Sentry handling, and status transitions
- `references/shared-doctrine.md` - evidence discipline, anti-fallback rules, and escalation boundaries
- `references/analyze.md` - create or repair the bug doc and make the issue fix-ready
- `references/fix.md` - implement the smallest credible fix and keep the doc truthful
- `references/review.md` - explicit-review-only audit behavior
- `references/quality-bar.md` - strong vs weak bars for evidence, fix-ready state, and verification