Menu
Structured bug fix workflow — triage, diagnose, discuss with user, write a focused spec, hand off for implementation
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
Invoked by gather-context or the human after a knowledge gap surfaces — author one long-form reference doc and wire a pointer into AGENTS.md's Context Map
Invoked by session-end or the human after a fact surfaces — route it to the correct context document (production map, dangerous assumptions, decision log, institutional knowledge, troubleshooting)
Invoked at the design bookend by decompose's decision gate or the human directly — turn open questions into a decision dossier; every decision terminates clarified, backlogged, or discarded
Break a feature brief into atomic specs — small, testable, independently executable units
Design discussion before decomposition — produce a ~200-line design artifact for human review, catching wrong assumptions before they propagate into specs
Invoked by tune, optimize, or session-end to convert eligible boundary prose into machine-checked deny patterns — not a user entry point.
| name | joycraft-bugfix |
| entry | human |
| description | Structured bug fix workflow — triage, diagnose, discuss with user, write a focused spec, hand off for implementation |
| instructions | 32 |
You are fixing a bug. Follow this process in order. Do not skip steps.
Guard clause: If this is clearly a new feature, redirect to /joycraft-new-feature and stop.
Establish what's broken. Gather: symptom, steps to reproduce, expected vs actual behavior, when it started, relevant logs/errors. If an error message or stack trace is provided, read the referenced files immediately. Try to reproduce if steps are given.
Done when: You can describe the symptom in one sentence.
Find the root cause. Start from the error site and trace backward. Read source files — don't guess. Identify the specific line(s) and logic error. Check git blame if it's a recent regression.
Done when: You can explain what's wrong, why, and where in 2-3 sentences.
Present findings to the user BEFORE writing any code or spec:
Ask: "Does this match? Comfortable with this approach?" If large/risky, suggest decomposing into multiple specs.
Done when: User agrees with the diagnosis and fix direction.
Write a bug fix spec to docs/bugfixes/<area>/bugfix-name.md. Use the relevant area as the subdirectory (e.g., auth, cli, parser). Lazy-create the docs/bugfixes/<area>/ directory if it doesn't exist.
(Bugfixes live under docs/bugfixes/<area>/, separate from docs/features/<slug>/specs/. Bugfixes are area-level, not feature-tied — multiple unrelated bugs accumulate in the same area folder over time, which is a fundamentally different folder shape from features.)
Area README: When creating (or adding to) a docs/bugfixes/<area>/ folder, also lazy-create/update a docs/bugfixes/<area>/README.md index — a one-line-per-bug table (| Bug | Spec | Status | Date |) so areas that accumulate many bugs stay navigable. Append a row for the new bugfix.
Why: Even bug fixes deserve a spec. It forces clarity on what "fixed" means, ensures test-first discipline, and creates a traceable record of the fix.
The spec file MUST start with YAML frontmatter — the 4-field personal schema (the area: field carries the area name, used informally to indicate "what folder this lives under"):
---
status: active
owner: <resolved name>
created: YYYY-MM-DD
area: <area>
---
Owner resolution: look up the owner name in this order — (1) git config user.name, (2) value in your auto-memory joycraft-owner.txt if present, (3) ask the user once and persist.
Use this template for the body:
# Fix [Bug Description] — Bug Fix Spec
> **Parent Brief:** none (bug fix)
> **Issue/Error:** [error message, issue link, or symptom description]
> **Status:** Ready
> **Date:** YYYY-MM-DD
> **Estimated scope:** [1 session / N files / ~N lines]
---
## Bug
What is broken? Describe the symptom the user experiences.
## Root Cause
What is wrong in the code and why? Name the specific file(s) and line(s).
## Fix
What changes will fix this? Be specific — describe the code change, not just "fix the bug."
## Acceptance Criteria
- [ ] [The bug no longer occurs — describe the correct behavior]
- [ ] [No regressions in related functionality]
- [ ] Build passes
- [ ] Tests pass
## Test Plan
| Acceptance Criterion | Test | Type |
|---------------------|------|------|
| [Bug no longer occurs] | [Test that reproduces the bug, then verifies the fix] | [unit/integration/e2e] |
| [No regressions] | [Existing tests still pass, or new regression test] | [unit/integration] |
**Execution order:**
1. Write a test that reproduces the bug — it should FAIL (red)
2. Run the test to confirm it fails
3. Apply the fix
4. Run the test to confirm it passes (green)
5. Run the full test suite to check for regressions
**Smoke test:** [The bug reproduction test — fastest way to verify the fix works]
**Before implementing, verify your test harness:**
1. Run the reproduction test — it must FAIL (if it passes, you're not testing the actual bug)
2. The test must exercise your actual code — not a reimplementation or mock
3. Identify your smoke test — it must run in seconds, not minutes
## Constraints
- MUST: [any hard requirements for the fix]
- MUST NOT: [any prohibitions — e.g., don't change the public API]
## Affected Files
| Action | File | What Changes |
|--------|------|-------------|
## Edge Cases
| Scenario | Expected Behavior |
|----------|------------------|
For trivial bugs: The spec will be short. That's fine — the structure is the point, not the length.
For large bugs that span multiple files/systems: Consider whether this should be decomposed into multiple specs. If so, create a brief first using /joycraft-new-feature, then decompose. A bug fix spec should be implementable in a single session.
Tell the user a one-line summary, then emit the canonical Handoff block.
Next:
/joycraft-implement docs/bugfixes/<area>/bugfix-name.md
Run /clear first.
Why: A fresh session for implementation produces better results. This diagnostic session has context noise from exploration — a clean session with just the spec is more focused.