87 added, 40 removed. Audit A to A.
---
name: bug-fix
description: "Bug fix workflow. Use when: fixing bugs, resolving issues, regression fixes. Not for: new features (use feature-dev), understanding code (use code-explore). Output: fix + regression test + review gate."
- allowed-tools: Read, Grep, Glob, Edit, Write, Bash(git:*), Bash(yarn:*), Bash(gh:*)
+ allowed-tools: Read, Grep, Glob, Edit, Write, Bash
---
# Bug Fix Skill
## Trigger
- Keywords: bug, issue, fix, error, broken, failing
## When NOT to Use
- New feature development (use feature-dev)
- Just want to understand code (use code-explore)
+ - Pure test-only tasks without feature changes (use `/codex-test-review` directly)
+ ## Prohibited Actions
+
+ ```
+ ❌ git add | git commit | git push — per @rules/git-workflow.md
+ ```
+
+ This skill fixes bugs but does **not** commit. `/precommit-fast` and `/precommit` are quality gates only. To commit, the user must invoke `/smart-commit --execute` separately.
+
## Workflow
```
- Investigate ──→ Locate ──→ Fix ──→ Test ──→ Review
- │ │ │ │ │
- ▼ ▼ ▼ ▼ ▼
- gh issue Grep Edit Write /codex-review-fast
- /git-inv Read tests /verify /precommit
+ Investigate → Locate → Fix → Test + Review → Precommit Gate
+ │ │ │ │ │
+ ▼ ▼ ▼ ▼ ▼
+ gh issue Grep Edit /verify /precommit-fast
+ /git-investigate Read tests /codex-test-review
+ /codex-review-fast
```
## Phase 1: Investigation
- | Source | Action |
- | -------------- | ------------------------ |
- | GitHub Issue | `gh issue view <number>` |
- | Error message | `Grep("error message")` |
- | Code history | `/git-investigate` |
+ | Source | Action |
+ |--------|--------|
+ | GitHub Issue | `gh issue view <number>` |
+ | Error message | `Grep("error message")` |
+ | Code history | `/git-investigate` |
**Output root cause analysis**:
- - Problem location: `src/xxx.ts:123`
+ - Problem location: `src/<module>/<file>:<line>`
- Root cause: <specific cause>
- Impact scope: <which features are affected>
## Phase 2: Fix
- | Principle | Description |
- | --------------------- | ------------------------------------ |
- | Minimal changes | Only modify what is necessary |
- | No new issues | Confirm changes don't affect other features |
+ | Principle | Description |
+ |-----------|-------------|
+ | Minimal changes | Only modify what is necessary |
+ | No new issues | Confirm changes don't affect other features |
- ## Phase 3: Add Tests ⚠️
+ ## Phase 3: Add Regression Test ⚠️
- **Bug fixes must have tests at the corresponding level**
+ Follow `@rules/testing.md` for conventions (AAA, naming, evidence model).
+ Follow `@rules/testing-project.md` for project-specific overrides.
- | Bug Type | Required | Recommended |
- | --------------- | ----------- | ----------- |
- | Logic error | Unit | - |
- | Service issue | Unit | Integration |
- | API issue | Integration | E2E |
- | User flow | E2E | - |
+ **Bug fixes must have tests at the corresponding level:**
- Detailed guide: [testing-guide.md](./references/testing-guide.md)
+ | Bug Type | Required | Recommended |
+ |----------|----------|-------------|
+ | Logic error | Unit | - |
+ | Service issue | Unit | Integration |
+ | API issue | Integration | E2E |
+ | Cross-service/data flow | Integration | E2E |
+ | User flow | E2E | - |
- ## Phase 4: Review
+ ## Phase 4: Verify + Review
- ```bash
- /verify # Run tests
- /codex-review-fast # Code review
- /codex-test-review # Test review
- /precommit # Pre-commit checks
+ ### Step 1: Run tests
+
```
+ /verify → all tests pass?
+ Yes → Step 2
+ No → fix failures → re-run /verify
+ ```
+ ### Step 2: Test adequacy review (mandatory for code changes)
+
+ ```
+ /codex-test-review → ✅ Tests sufficient?
+ Yes → Step 3
+ No → close gaps (Step 2a) → /codex-test-review --continue <threadId>
+ ```
+
+ ### Step 2a: Gap closure
+
+ | Gap Type | Remediation |
+ |----------|-------------|
+ | Unit test missing | `/codex-test-gen` → write tests → `/verify` |
+ | Integration/E2E missing | `/post-dev-test` → write tests → `/verify` |
+
+ ### Step 3: Code review (auto-loop)
+
+ ```
+ /codex-review-fast → ✅ Ready?
+ Yes → Precommit Gate
+ No → fix issues → re-run /codex-review-fast (auto-loop)
+ ```
+
+ ### Freshness rule
+
+ If code changes after the latest `✅ Tests sufficient` gate (e.g., fixes from code review), rerun `/verify` then `/codex-test-review --continue <threadId>` before proceeding to precommit gate.
+
## Review Loop
- **⚠️ Follow @rules/auto-loop.md**
+ **MUST re-review after fix until PASS** (per @rules/auto-loop.md)
```
- Fix → Review → Issues found → Fix again → ... → ✅ Pass
+ Fix → Review → Issues found → Fix again → ... → ✅ Pass → Next step
```
+ ## Doc Sync
+
+ Doc Sync is governed by `@rules/auto-loop.md` (behavior-layer rule). After precommit pass, triggers conditionally when changes map to `docs/features/`.
+
## Output
```markdown
## Bug Fix Report
- **Root cause**: <analysis>
- **Fix**: <description of changes>
- **Regression test**: <test result>
- **Gate**: ✅ Fixed / ⛔ Needs further investigation
```
- ## Verification
+ ## Verification Checklist
- - [ ] Issue confirmed fixed
- - [ ] Tests at corresponding level written
- - [ ] All tests passing
- - [ ] Code review passed (Gate ✅)
+ - [ ] Root cause identified and documented
+ - [ ] Regression test written at appropriate level
+ - [ ] All tests pass (`/verify`)
+ - [ ] Test adequacy reviewed (`/codex-test-review`)
+ - [ ] Code review passed (`/codex-review-fast` ✅ Ready)
+ - [ ] Precommit passed (`/precommit-fast` ✅ All Pass)
+ - [ ] No `git add/commit/push` executed
## Examples
```
Input: Fix issue #123 - calculation error
- Action: gh issue view → locate → fix → write Unit Test → /verify → /codex-review-fast
+ Action: gh issue view → locate → fix → write Unit Test → /verify → /codex-test-review → /codex-review-fast → /precommit-fast
```
```
Input: API returning 500 error
- Action: Grep error → read code → fix → write Integration Test → /verify → /codex-review-fast
+ Action: Grep error → read code → fix → write Integration Test → /verify → /codex-test-review → /codex-review-fast → /precommit-fast
```