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.zip

Installs 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 model
324 chars · catalog description✓ has a “when” triggerlonger than Claude Code's old 250-char listing cap (fine on current versions)
Intermediate

Key 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

You give it
Bug description or failure steps
You get back
Reproduction test case and minimal functional fix

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

  1. Reproduce: Follow exact steps to trigger the bug
  2. Expected: What SHOULD happen (the person's mental model — USER_JOURNEYS)
  3. Actual: What IS happening (current behavior)
  4. 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 (info and above) — which data source answered, which step failed (lookup · fetch · mapping); debug goes to OSLog only (troubleshooting).
  • The failed step: account.lastFailedStep and lastError say 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

  1. Minimal change: Fix only what's broken
  2. At the law's owner: fix the one type that owns the rule (CANONICAL §5), not a call site or a view
  3. A provider is data: its JSON or script, or a generic rule in DataSources that every definition gains — never a branch on a provider's id
  4. Maintain invariants: the owner stays self-validating — tell, don't ask
  5. 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 test green
  • Docs updated where the person or a contributor would look (provider README / design.md)
  • One line under ## [Unreleased] in CHANGELOG.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

Existing test suite

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.

SkillInstallsUpdatedSafetyDifficulty
fix-bug (this skill)1110moReviewIntermediate
python-testing-patterns775moReviewIntermediate
test-fixing11yReviewIntermediate
fixing-bugs-systematically111moNo flagsIntermediate

Try saying

Example prompts that trigger this skill in your AI assistant.

Search skills

Search the agent skills registry