Agent Skills: Fixing Small Issues

Fixing Small Issues

Mandatory First Action: Create the Coordinator Plan

Before launch, create:

Step 0: Load instructions, resolve source, and create/resume bugfix branch
Step 1: Initialize phase_1_attempts=0 and phase_2_attempts=0
Step 2: Run and validate Phase 1
Step 3: Post accepted diagnosis comment when an issue exists
Step 4: Run and validate Phase 2
Step 5: Keep or revert the returned commit
Step 6: Loop, block, or complete

Add no other stages. Dispatch agents with the active runtime's native collaboration tools; never launch a nested Codex CLI process. Agents are fresh, sequential, and single-phase. Inspect every final response and checkpoint before trust. Retain checkpoints/counters; request additional detail only when a checkpoint is missing, malformed, contradictory, or untrustworthy.

On Codex, spawn every attempt with fork_turns: "none" and set both model and reasoning_effort explicitly from the current spawn allowlist. Complete and validate Phase 1 before dispatching Phase 2. When idle, use event waits of 5–10 minutes instead of short polling or repeated unchanged status narration. A retry is a fresh agent and increments the applicable phase counter; follow-up messages may clarify a returned checkpoint but do not constitute another implementation attempt.

Scope and Iron Laws

Features/gaps route to feature-workflow:feature-researching. Product ambiguity, broad refactoring, contracts, migrations, security, data-loss, or feature-like scope route to Human Intervention.

NO PHASE 1 BEFORE THE BUGFIX BRANCH EXISTS NO FIX WITHOUT AN EVIDENCE-BACKED ROOT CAUSE NO PHASE 2 WORKSPACE CHANGE WITHOUT AN ATTRIBUTABLE COMMIT NO SUCCESS CLAIM WITHOUT INDEPENDENT FRESH VERIFICATION NO FOURTH SPAWN OF EITHER PHASE NO RESET OR HISTORY REWRITE TO DISCARD A FAILED ATTEMPT NO Z-ARTIFACT OR FEATURE-QA PIPELINE FOR THIS WORKFLOW

No Z artifacts, tracker/phased plans, batch approvals, or feature-QA/multi-profile pipeline. Never reset/rewrite attempts. Push, PR, merge, issue close, labels, or assignment require explicit request; comments follow the contract below.

Step 0: Load Instructions, Resolve Source, and Create the Branch

Read instructions. Source priority: explicitly supplied GitHub issue; GitHub issue unambiguously identified by task context; direct report. Multiple/ambiguous contextual issues require clarification before branch/comment. For canonical issues, GitHub-read body/comments before branching; unreadable source is an external blocker. Never guess. Direct reports remain in-task; create no tracker.

• Branches: issue bugfix/<issue-number>_<bug-slug>; direct bugfix/<bug-slug>
• Slug: lowercase snake_case, unsafe characters removed, maximum 50 characters
• Base: main unless user-authorized otherwise

Pre-branch: instructions, minimal source resolution, read-only git inspection only. Resume only the exact branch. Detached HEAD, unrelated branch, unclear provenance, or any dirty tree pauses before agents; preserve all user changes.

Step 1: Initialize Attempt State

phase_1_attempts = 0
phase_2_attempts = 0

before spawning phase N:
  if phase_N_attempts >= 3:
    create Human Intervention Checkpoint and stop
  phase_N_attempts += 1
  spawn a fresh phase N agent

Independent cumulative counters persist across phase switches/resume. A successful third attempt completes normally. Retry needs new evidence/different approach.

Step 2: Spawn Phase 1 — Reproduce and Diagnose

Before dispatch, require the isolated diagnosis agent to load and follow superpowers:systematic-debugging; include the exact skill name in the phase brief. If it is unavailable, return a dependency blocker without consuming an attempt. Pass only source, branch, constraints, attempt, checkpoint, retry evidence. On-branch, use superpowers:systematic-debugging: expected/actual behavior, reproduction/evidence, tested hypotheses, causal root cause, options, success criteria. No production fix/tracked changes; remove instrumentation.

Step 3: Validate and Publish the Diagnosis Checkpoint

Validate log, exit, and clean git status --short. Require:

Status: ready | retryable | blocked | escalate
Reproduction:
Evidence:
Root cause:
Affected scope:
Fix options:
Recommended fix:
Risk flags:
Phase 2 success criteria:

ready = evidence-backed root cause, bounded fix, testable criteria, no ambiguity/risk. Feature gap = Status: escalate, Affected scope: feature-gap; stop before Phase 2, route to feature-workflow:feature-researching. blocked -> Human Intervention. Auto-comment accepted issue diagnosis.

Step 4: Spawn Phase 2 — Plan, Fix, Verify, and Commit

Before dispatch, require the isolated implementation agent to load and follow both superpowers:test-driven-development and superpowers:verification-before-completion; include both exact skill names in the phase brief. If either is unavailable, return a dependency blocker without consuming an attempt. Pass diagnosis. On-branch, use the two loaded skills and a three-to-six-step plan. Write a failing regression first. Use precise manual reproduction only when no existing automated harness can express the regression without disproportionate new infrastructure; record why in Regression coverage. Make the smallest root-cause fix; verify original/neighbors; remove residue; commit.

Require:

Status: fixed | retryable | diagnosis-invalidated | blocked | escalate
Plan executed:
Commit SHA:
Files changed:
Regression coverage:
Original reproduction result:
Verification commands and results:
Residual risks:

blocked needs no empty commit. fixed/changed retryable require an attributable exact-branch commit.

Step 5: Validate the Resolution Checkpoint and Commit

Always validate log, exit, checkpoint, and clean git status --short. For blocked, unchanged retryable, escalate, or unchanged diagnosis-invalidated without a commit, route normally. Only when Phase 2 returns changed work/a commit:

1. Confirm expected-branch commit.
2. Inspect scope/residue/unrelated diff.
3. Rerun original/proportionate verification.
4. Keep success.
5. Keep useful partial commit before retry.
6. Reject with git revert, never git reset.
7. On invalidated diagnosis, revert then Phase 1.
8. Require clean git status --short after the commit and any revert.

Step 6: Route Completion, Retry, Re-Diagnosis, or Human Intervention

Phase 1 ready -> Phase 2
Phase 1 retryable -> Phase 1, subject to the attempt gate
Phase 1 blocked -> Human Intervention
Phase 1 ambiguity/risk/escalate -> Human Intervention
Phase 2 fixed and independently verified -> Complete
Phase 2 retryable with valid diagnosis -> Phase 2, subject to the attempt gate
Phase 2 diagnosis-invalidated -> revert if needed, then Phase 1
Phase 2 blocked -> Human Intervention
Phase 2 ambiguity/risk/escalate -> Human Intervention

On Human Intervention, return:

Blocked phase:
Phase 1 attempts:
Phase 2 attempts:
Latest accepted diagnosis:
Current branch and commit:
Current diff state:
Latest failed reproduction or verification:
Why autonomous progress stopped:
Recommended human decision:

GitHub Comment Contract

For canonical issues, automatically post in one or two sentences:

• Diagnosis: reproduction + root cause + intended fix
• Resolution: fix + passing verification
• Blocked: exhausted phase/risk + needed decision

Skip retries; correct a superseded diagnosis once. Only comments mutate automatically. Report failure accurately; it does not invalidate a verified fix.

Completion Contract

Complete after Step 5 with resolved risks and clean workspace. For a canonical GitHub issue, also require the resolution comment or an accurately reported failure; direct reports require no tracker comment. Report cause, fix, commit, verification, risk.

Red Flags

Stop on any violated gate.