Menu
Use when the user says fix, bugfix, broken, or describes a bug. Reproduces, fixes, verifies, reviews, and hands back a clean branch.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Analyze Codex, Claude Code, or Cursor threads, transcripts, and transcriptions. Use for thread analysis, transcript review, conversation audits, agent-performance diagnosis, comparing sessions, finding loops or corrections, and extracting decisions, outcomes, evidence, and actionable improvements.
Internal reference for vs shared conventions: artifact paths, project ID resolution, storage preference, and skill taxonomy.
Use when asked to scan a named external repo for ideas worth porting. Produces a cited, ranked steals report.
Use when asked to QA, test this site or app, find bugs, or test and fix a user-facing interface. Runs harness-aware browser or computer-use QA, fixes issues, and re-verifies.
Use when the user wants to create/open a pull request, submit changes for review, send changes to dev, or otherwise ship local Git changes. Also use for explicit commit and push or push to main/master or the current branch requests. Requires affirmative publish intent; do not use for review/readiness-only requests. Creates and verifies a GitHub PR by default; honors explicit direct pushes and babysits only when requested.
Use when asked to watch a PR, fix CI, address review comments, or keep a branch merge-ready in a loop.
| name | vs-bugfix |
| description | Use when the user says fix, bugfix, broken, or describes a bug. Reproduces, fixes, verifies, reviews, and hands back a clean branch. |
| disable-model-invocation | true |
Bug in, fixed branch out with scoped progress inside the reported bug.
Classify → Understand → Hypothesize → Reproduce → Fix → Verify → Review → Handoff
Work only on changes directly required to reproduce and fix the reported bug. Stop when resolving the bug would require a product decision, unrelated refactor, or new scope.
Four circuit breakers halt the run:
Before delegating, load and follow
../vs-internal-shared/references/subagents.md.
Use the standard budget unless the user explicitly asks for deep investigation.
When running in Codex, use
../vs-internal-shared/references/codex-goal.md
for goal ownership and completion rules.
Bugfix owns an execution goal only after the bug is concrete enough to verify: bug statement, target area, and reproduction or verification plan are known. Do not create a goal for a vague "something is broken" report until Phase 1 has enough evidence. Complete the goal after the root cause is fixed, regression or browser/script reproduction is verified green, guardrails run, and the Phase 7 handoff is reported. Leave it active or blocked when a circuit breaker stops the run.
| Input | Detection | Action |
|---|---|---|
| Bug description | Default — no URL, no stack trace | Proceed to Phase 1 |
| GitHub issue | URL or #123 pattern | Fetch via gh issue view, extract repro steps + expected/actual |
| Error / stack trace | Error:, stack frames, exit codes | Extract error, file paths, line numbers — feed as hints to Phase 1 |
| Failing test | Test file path or FAIL output | Record the test, skip to Phase 4 (reproduction already done) |
For GitHub issues:
gh issue view <number> --json title,body,labels --jq '{title: .title, body: .body, labels: [.labels[].name]}'
git status and git diff to understand the current state.Dry-run each guardrail command:
[test command] 2>&1 | head -5
[typecheck command] --noEmit 2>&1 | head -5
If any command fails due to missing dependencies: install them now. Do not proceed until guardrail commands execute without "command not found" errors.
GIT_USER=$(git config user.name 2>/dev/null | tr '[:upper:]' '[:lower:]' | tr ' ' '-')
Derive branch name from the bug: {user-prefix}/fix-{bug-topic}.
Use the branch prefix convention from CLAUDE.md if one exists.
git checkout -b <branch-name>
If already on a feature branch (not main/master/develop), stay on it.
Before each phase, load the relevant sibling skill from disk using ../<skill-name>/SKILL.md. If sibling resolution fails, use the fallback listed below.
Skills to load per phase:
| Phase | Skill | Fallback if not found |
|---|---|---|
| Phase 2 (Hypothesize) | ../vs-debug-mode/SKILL.md | Inline hypothesis methodology |
| Phase 3 (Reproduce) | ../vs-tdd/SKILL.md | Manual reproduction script |
| Phase 3 (Web bugs) | ../vs-qa/SKILL.md | Skip browser verification |
| Phase 1 (Deep exploration) | Local repo search | Grep + read |
| Phase 5 (Verify) | ../vs-verify/SKILL.md | Manual evidence summary |
| Phase 6 (Review) | ../vs-roast-review/SKILL.md | Lightweight self-review |
Goal: know exactly what's broken and where to look.
Identify the affected area — search for keywords in the codebase:
grep -r "keyword" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.py" -l | head -20
Read the affected files. Trace the code path from user-facing behavior to the suspected failure point.
If the codebase is large or unfamiliar, do deep local exploration with search and read tools before changing code.
Check git history for recent changes to affected files:
git log --oneline -10 -- <affected-files>
Extract from the issue body:
Map these to code paths using the same search approach.
Parse the stack trace for:
Read each file in the stack trace. Start from the innermost frame.
By end of Phase 1, you must have:
Use the hypothesis generation approach from debug-mode's Phase 2. For investigation, use the techniques below (adapted from debug-mode Phase 3 for a fix-oriented workflow).
Generate 3-5 specific, testable hypotheses. Order by likelihood.
H1: [specific cause]
Test: [how to confirm or reject]
H2: [specific cause]
Test: [how to confirm or reject]
Common root causes: state (wrong/missing/stale), timing (race/async), environment (missing file/config), types (null/coercion), logic (off-by-one/wrong condition), integration (contract mismatch).
For each hypothesis (most likely first):
git log --oneline -20 -- <files> / git diff <last-good>..HEADClassify each:
Max 3 investigation rounds. If all hypotheses rejected/inconclusive after 3 rounds:
CIRCUIT BREAKER: Could not identify root cause.
Investigated:
- [hypothesis]: [why rejected]
- [hypothesis]: [why rejected]
Suspect area: [best guess with evidence]
Recommendation: [what to try next manually]
Stop. Present findings. Do not attempt a fix without understanding the cause.
Prove the bug exists with a failing test. Follow the TDD skill's Phase 2 (Red) methodology.
If the test passes: the hypothesis is wrong. Return to Phase 2 with this new evidence.
git add <test-file>
git commit -m "test: add failing test for <bug description>"
If no test infrastructure exists for the affected area:
If the bug cannot be reproduced after 3 attempts with different approaches:
CIRCUIT BREAKER: Could not reproduce the bug.
Attempts:
- [approach 1]: [result]
- [approach 2]: [result]
- [approach 3]: [result]
The bug may be: intermittent / environment-specific / already fixed.
Stop. Present findings.
Apply the minimal fix. Follow the TDD skill's Phase 3 (Green) methodology.
[test command]
If the fix causes more test failures than existed before:
CIRCUIT BREAKER: Fix causes regressions.
New failures:
- [test]: [error]
The fix at [file:line] resolves the original bug but breaks [N] other tests.
This suggests the root cause analysis was incomplete or the fix approach
needs rethinking.
Revert the fix: git checkout -- <changed-files>. Stop. Present findings.
If investigation reveals the bug is in:
CIRCUIT BREAKER: Bug is outside this repository.
Root cause: [what and where]
Evidence: [how you confirmed it's external]
Workaround: [if one exists in this repo]
Upstream fix: [what needs to change externally]
Stop. Present findings with workaround options if applicable.
Do NOT commit yet — Phase 5 verifies first.
Full validation after the fix:
If available, load ../vs-verify/SKILL.md and use its
## Verification Result as the Phase 5 evidence wrapper. The checks below are
the required evidence inputs.
[test command]
[typecheck command]
[build command]
Distinguish between:
git add <implementation-files>
git commit -m "fix: <description of the bug fix>"
Two sub-phases: test verification first, then code review. Run both.
The parent first extends the regression test with the nearest boundary and failure cases suggested by the root cause. Use a stress-test subagent only when the fix touches auth, security, persistence, migrations, concurrency, payments, or a public API; spans more than 3 production files; or the affected branch has no meaningful test coverage. The subagent gets the bug description, exact changed paths, the diff location, and one instruction:
"Write tests that try to break this fix. Cover: the original bug, edge cases adjacent to the fix, and any state the fix assumes. Run the tests. Report which pass and which fail."
If the risk gate does not apply, run these focused cases in the parent and spend no child budget. If a subagent finds failing tests:
If no test infrastructure exists for the affected area, skip 6a and note it in the decision log.
For a small, low-risk fix, review the complete changed files in the parent: search for existing helpers, inspect callers, and run the focused regression test plus deterministic guardrails. Do not add a second model by default.
Load roast-review only when the Phase 6a risk gate applies or the diff exceeds 5 files or 300 changed lines. If found, follow its methodology within the shared child budget; any cross-model review counts toward that same budget.
Auto-select option b) Critical + serious and apply immediately (same as build-it's override).
If not found: run a lightweight self-review covering the same dimensions.
For each review finding that claims a bug: write a failing test first to confirm it's real. If you can't write a failing test, the finding may be a false positive — note it in the decision log instead of applying a speculative fix.
After applying review fixes:
refactor: <description>Present the result:
## Fix Complete
### Branch
`{branch-name}` — [N] commits
### Bug
**Root cause:** [what and why — one sentence]
**Evidence:** [what confirmed it]
### Fix
**Files changed:** [list]
**Test added:** [test file:line] (or "browser-verified" / "script-verified")
### Pipeline
| Phase | Result |
|-------|--------|
| Understand | [affected area identified] |
| Hypothesize | [N] hypotheses, [root cause] confirmed |
| Reproduce | [test/browser/script] — verified failing |
| Fix | [minimal fix applied] |
| Verify | guardrails pass/fail |
| Review | [N] found, [M] fixed |
### Codex Goal
[created/reused/completed/unavailable/left active because ...]
### Decision Log
| # | Phase | Decision | Rationale |
|---|-------|----------|-----------|
| 1 | ... | ... | ... |
List every auto-resolved decision here.
### Guardrails
- Tests: pass/fail ([N] passed, [M] failed)
- Types: pass/fail
- Build: pass/fail
### Suggested next step
[Based on results:]
- All green → `/vs-ship-it`
- Guardrail failures → list what's broken, recommend fixing
- Deferred issues → note for future work
Direct: emit Next only. Composed: return to caller.
Prev: bug report | issue | test failure | /vs-debug-mode
Next: /vs-ship-it
Relevant: /vs-build-it | /vs-qa