fix-bug
A systematic testing-led approach to debugging code.
Install
mkdir -p .claude/skills/fix-bug && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/2834" && unzip -o skill.zip -d .claude/skills/fix-bug && rm skill.zipInstalls to .claude/skills/fix-bug
Activation
This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.
Guide for fixing bugs in ClaudeBar following Chicago School TDD and rich domain design. Use this skill when:
(1) User reports a bug or unexpected behavior
(2) Fixing a defect in existing functionality
(3) User asks "fix this bug" or "this doesn't work correctly"
(4) Correcting behavior that violates the user's mental modelKey capabilities
- →Executes the Chicago School TDD cycle (Red-Green-Refactor)
- →Identifies root causes via step-by-step reproduction
- →Validates fixes with failing test cases
- →Verifies existing functionality through regression tests
How it works
It forces a strict workflow where a test must fail for the identified bug before any implementation code is modified.
Inputs & outputs
When to use fix-bug
- →Debugging reported issues
- →Refactoring code with safety tests
- →Fixing production defects
About this skill
Fix Bug in ClaudeBar
Fix bugs using Chicago School TDD, root cause analysis, and rich domain design.
Workflow
┌─────────────────────────────────────────────────────────────┐
│ 1. REPRODUCE & UNDERSTAND │
├─────────────────────────────────────────────────────────────┤
│ • Reproduce the bug │
│ • Identify expected vs actual behavior │
│ • Locate the root cause in code │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 2. WRITE FAILING TEST (Red) │
├─────────────────────────────────────────────────────────────┤
│ • Write test that exposes the bug │
│ • Test should FAIL before fix │
│ • Test should verify CORRECT behavior │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 3. FIX & VERIFY (Green) │
├─────────────────────────────────────────────────────────────┤
│ • Implement minimal fix │
│ • Test now PASSES │
│ • All existing tests still pass │
└─────────────────────────────────────────────────────────────┘
Phase 1: Reproduce & Understand
Identify the Bug
- Reproduce: Follow exact steps to trigger the bug
- Expected: What SHOULD happen (the person's mental model — USER_JOURNEYS)
- Actual: What IS happening (current behavior)
- Root cause: WHY it's happening (code analysis)
For a provider that shows the wrong thing or fails:
- The log:
~/Library/Logs/ClaudeBar/ClaudeBar.log(infoand above) — which data source answered, which step failed (lookup · fetch · mapping);debuggoes to OSLog only (troubleshooting). - The failed step:
account.lastFailedStepandlastErrorsay whether the key, the request or the reading broke — fix that piece. - The real response: capture the CLI's or API's actual answer, redacted (no token, email, name or real usage), as the test's fixture. Never log a token, key or cookie while investigating.
Find the law it breaks
Read the design in order — USER_JOURNEYS, CANONICAL_MODEL, TARGET_ARCHITECTURE,
then the feature's or provider's design.md. The design docs are the source of truth (AGENTS.md).
A bug is usually a law in CANONICAL_MODEL.md §5 (or a feature's
design.md) that the code breaks: find the law and its one owner, and fix it there, not
at a call site. If the right fix changes a law or moves it to another owner, that is a
design change: update the doc and ask the user to confirm before fixing. If no law covers
it, propose the law first.
Think how the domain should be
A bug is often a shape that let it happen: a rule a view could call and decide
for itself, two lifecycles in one class whose optionals disagree, a String
where a type would have refused the bad value, a boundary that guessed the
other side's format. Before fixing, ask how the domain should be, from the
person's problem, and ask the seven questions of the types the bug touches
→ domain-shape.md. Fix the
shape when it is the cause, in the same change, test first; a new aggregate or
a moved owner is a design change, confirmed first. A screen that contradicts
itself ("On track" beside "Runs out") is usually one law with two owners: fix it
by giving the law one owner, not by adjusting one copy.
Locate in Architecture
Reference: MODULAR_DESIGN.md (modules) · TARGET_ARCHITECTURE.md (how a provider runs) · ARCHITECTURE.md (the app layers)
Find which module the behaviour lives in before you change it: the table in implement-feature → Architecture is the one map (where each thing lives, and where its tests go).
A bug or improvement in a provider is made in its JSON (or its mapping
script), or generically in DataSources — never with vendor-named Swift, and
never with a line in ClaudeBarApp that names it (providers are found by
ProviderCatalog.detect()). Modules never import Domain.
Domain Invariants
Check if the bug violates domain invariants that should be maintained:
// Example: QuotaMonitor should maintain selection invariants
// - selectedProviderId should always point to an enabled provider
// - Domain should be self-validating (no external "ensure" calls needed)
Phase 2: Write Failing Test (Red)
Chicago School TDD
Name each test should <outcome> [when <situation>], in the person's words, never a method, type or mechanism verb → Naming tests.
We follow Chicago School TDD (state-based testing):
- Test state changes and return values, not interactions
- Focus on the "what" (observable outcomes), not the "how" (method calls)
- Mocks stub dependencies to return data, not to verify calls
- No
verify()calls - assert on resulting state instead
Test Pattern
Test the CORRECT behavior, not the bug:
@MainActor
@Suite
struct {Component}Tests {
@Test func `should {correct outcome} when {the situation that showed the bug}`() async throws {
// Given - the response that triggers the bug, captured from the real CLI/API
let stub = try StubbedProvider(providerId: "codex")
defer { stub.cleanUp() }
stub.answerRPC(#"{"id":2,"result":{"rateLimits":{"primary":{"usedPercent":30,"windowDurationMins":10080}}}}"#)
// When - the real definition reads it
let usage = try await stub.make("codex").refreshPlain()
// Then - assert EXPECTED behavior (will FAIL before fix)
#expect(usage.quota(for: .session)?.windowDuration == 7 * 86400) // the window the provider stated
}
}
Test Location
The test goes beside the code it pins (the table in Phase 1). For a migrated
provider, add the captured response to its golden tests in
Modules/Providers/Tests/; for a generic worker, to Modules/DataSources/Tests/.
Run Test (Should FAIL)
tuist test Providers # one module's tests while working (schemes: Providers, DataSources, Domain, Infrastructure, AppTests, AcceptanceTests)
# tuist caches results; one suite for real, and the final check of everything:
xcodebuild test -workspace ClaudeBar.xcworkspace -scheme ClaudeBar-Workspace \
-destination 'platform=macOS,arch=arm64' -only-testing:ProvidersTests/ClaudeAPITests
xcodebuild test -workspace ClaudeBar.xcworkspace -scheme ClaudeBar-Workspace -destination 'platform=macOS,arch=arm64'
Phase 3: Fix & Verify (Green)
Fix Guidelines
- Minimal change: Fix only what's broken
- At the law's owner: fix the one type that owns the rule (CANONICAL §5), not a call site or a view
- A provider is data: its JSON or script, or a generic rule in
DataSourcesthat every definition gains — never a branch on a provider's id - Maintain invariants: the owner stays self-validating — tell, don't ask
- No over-engineering: Don't refactor unrelated code
Domain Design Principles
When fixing domain bugs, ensure:
// 1. Domain maintains its own invariants
public init(...) {
// Validate on construction
selectFirstEnabledIfNeeded() // Called internally, not externally
}
// 2. Public API hides implementation details
public func setProviderEnabled(_ id: String, enabled: Bool) {
provider.isEnabled = enabled
if !enabled {
selectFirstEnabledIfNeeded() // Private - called automatically
}
}
// 3. Private methods for internal invariant maintenance
private func selectFirstEnabledIfNeeded() { ... }
Verify Fix
Run the same suite again (it should PASS now), then the full xcodebuild test
(tuist test skips cached targets). Then the docs in the same change: a
provider's README.md Gotchas when the person can hit it, its design.md
when the reading changed, and the CHANGELOG line.
Checklist
- Bug reproduced and understood
- Root cause identified in code
- Domain thought through: is the bug a shape the seven questions would have refused? Fixed there if so
- Failing test written (exposes bug)
- Test FAILS before fix
- Minimal fix implemented
- Test PASSES after fix
- All existing tests still pass
- Domain invariants maintained (if applicable)
- Full
xcodebuild testgreen - Docs updated where the person or a contributor would look (provider README / design.md)
- One line under
## [Unreleased]inCHANGELOG.md, under its heading (Fixed/Changed): the effect in the person's words, ≤300 characters, an absolute issue or PR link
When not to use it
- →When a project lacks a test suite
- →For UI/styling issues where TDD is not applicable
Prerequisites
Limitations
- →Slower than quick-patch methods
- →Strictly relies on the ability to reproduce bugs in a test environment
How it compares
It prevents 'fix-by-guess' by requiring a failing test as the foundational requirement for every correction.
Compared to similar skills
fix-bug side by side with the closest alternatives in the catalog.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| fix-bug (this skill) | 11 | 10mo | Review | Intermediate |
| python-testing-patterns | 77 | 5mo | Review | Intermediate |
| test-fixing | 1 | 1y | Review | Intermediate |
| fixing-bugs-systematically | 1 | 11mo | No flags | Intermediate |
Try saying
Example prompts that trigger this skill in your AI assistant.
More by tddworks
View all by tddworks →You might also like
python-testing-patterns
wshobson
Implement comprehensive testing strategies with pytest, fixtures, mocking, and test-driven development. Use when writing Python tests, setting up test suites, or implementing testing best practices.
test-fixing
mhattingpete
Run tests and systematically fix all failing tests using smart error grouping. Use when user asks to fix failing tests, mentions test failures, runs test suite and failures occur, or requests to make tests pass.
fixing-bugs-systematically
CaptainCrouton89
Diagnose and fix bugs through systematic investigation, root cause analysis, and targeted validation. Use when something is broken, errors occur, performance degrades, or unexpected behavior manifests.
moai-workflow-testing
modu-ai
Comprehensive development workflow specialist combining DDD testing, debugging, performance optimization, code review, PR review, and quality assurance into unified development workflows
investigate
MadAppGang
Unified entry point for code investigation. Auto-routes to specialized detective based on query keywords. Use when investigation type is unclear or for general exploration.
review
MatrixAges
Review uncommitted code changes to find unreasonable design, unfinished requirements, potential bugs, missed reuse opportunities, and optimization opportunities. Use when the user asks for a review of pending, uncommitted, or unpublished code changes and expects both findings and concrete improvemen