vs-bugfix

Files (8)

• SKILL.md
• openai.yaml · agents/
• bugfix.eval.ts · test/
• package.json · test/fixtures/ts-library-with-bug/
• index.ts · test/fixtures/ts-library-with-bug/src/
• slugify.test.ts · test/fixtures/ts-library-with-bug/src/
• slugify.ts · test/fixtures/ts-library-with-bug/src/
• tsconfig.json · test/fixtures/ts-library-with-bug/

SKILL.md (first lines)

# Fix

Bug in, evidence-backed 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:
1. Can't identify root cause after 3 investigation rounds
2. Bug cannot be reproduced after 3 attempts
3. Fix causes more test failures than it solves
4. Bug is in an external dependency or infrastructure (can't fix from this repo)

Before delegating, load and follow
[`../vs-internal-shared/references/subagents.md`](../vs-internal-shared/references/subagents.md).
Use the standard budget unless the user explicitly asks for deep investigation.

## Codex Goal Integration

When running in Codex, use
[`../vs-internal-shared/references/codex-goal.md`](../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.

---

## Phase 0: Setup

### Step 1: Classify Input

| 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:
```bash
gh issue view <number> --json title,body,labels --jq '{title: .title, body: .body, labels: [.labels[].name]}'
```

### Step 2: Read Context

- Read CLAUDE.md for project-specific commands (test, build, lint).
- Run `git status` and `git diff` to understand the current state.
- Note the test command, build command, and lint command.
  If not found in CLAUDE.md, search package.json, Makefile, or equivalent.

### Step 3: Validate Guardrails

Dry-run each guardrail command:

```bash
[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.

### Step 4: Create Branch

```bash
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.

```bash
git checkout -b <branch-name>
```

If already on a feature branch (not main/master/develop), stay on it.

### Step 5: Load Skills

Before each phase, load the relevant sibling skill from disk using
`../<skill-name>/SKILL.md`. A gated skill cannot be replaced safely: if its file
cannot be resolved, give the user the exact slash command below and stop.
Ungated building blocks may use the listed inline fallback.

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` | Stop; tell the user to type `/vs-tdd` |
| Phase 3 (Web bugs) | `../vs-qa/SKILL.md` | Stop; tell the user to type `/vs-qa` |
| Phase 1 (Deep exploration) | Local repo search | Grep + read |
| Phase 5 (Verify) | `../vs-verify/SKILL.md` | Manual evidence summary |
| Phase 6 (Review) | `../vs-roast-code/SKILL.md` | Lightweight self-review |

---

## Phase 1: Understand

Goal: know exactly what's broken and where to look.

### From bug description (default)

1. Identify the affected area — search for keywords in the codebase:
   ```bash
   grep -r "keyword" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.py" -l | head -20
   ```

2. Read the affected files. Trace the code path from user-facing behavior
   to the suspected failure point.

From vltansky/vs, MIT.

More from vltansky/vs