con un clic
fix-bug
Test-first bug fixing: Write failing test that reproduces bug → Fix code → Test passes. Systematic, verifiable approach prevents regression and wastes no time on trial-and-error deployments.
Menú
Test-first bug fixing: Write failing test that reproduces bug → Fix code → Test passes. Systematic, verifiable approach prevents regression and wastes no time on trial-and-error deployments.
Execute a complete iteration cycle: planning → batch execution → documentation → review setup. Follows file-based orchestration with TDD/ATDD, work logs, and quality gates.
Delegate task to specialist agent when expertise required: Initialize as specialist (Planning Petra, Backend Benny, Architect Alphonso, etc.) OR spawn sub-agent if available. Use when task requires specialized knowledge in agent's core focus area.
Architect Alphonso conducts rigorous code review and architecture-fit analysis: ADR compliance, test coverage, architectural patterns, security. Outputs review document with APPROVED/REDIRECT/BLOCKED status.
Mid-execution self-monitoring checkpoint (Ralph Wiggum Loop): Detect warning signs (drift, confusion, gold-plating), course-correct before completion. Mandatory at 25% progress and before delegation.
Create functional specification for complex features: detailed requirements, user scenarios, constraints, acceptance criteria. Bridges strategic intent and implementation with MoSCoW prioritization and Given/When/Then scenarios.
Assess current implementation state: pending tasks, active work, progress metrics, blockers, and next recommended batch. Provides Planning Petra's executive view.
| name | fix-bug |
| description | Test-first bug fixing: Write failing test that reproduces bug → Fix code → Test passes. Systematic, verifiable approach prevents regression and wastes no time on trial-and-error deployments. |
| version | 1.0.0 |
| type | problem-solving |
| category | debugging |
Resolve software defects using a disciplined test-first approach. Write a failing test that reproduces the bug BEFORE modifying any production code.
Phase 1: Write a Failing Test (DO THIS FIRST)
Choose test level:
Write test that reproduces the bug:
# Python example
def test_bug_description():
"""Bug: [Describe what's wrong]"""
# Arrange: Set up scenario that triggers bug
input_data = create_bug_triggering_input()
# Act: Execute the failing code
result = system_under_test.process(input_data)
# Assert: What SHOULD happen (test will FAIL)
assert result == expected_correct_behavior
// Java example
@Test
@DisplayName("Bug: [Describe what's wrong]")
void reproduceBug() {
// Arrange: Set up scenario that triggers bug
var input = createBugTriggeringInput();
// Act: Execute the failing code
var result = systemUnderTest.process(input);
// Assert: What SHOULD happen (test will FAIL)
assertThat(result).isEqualTo(expectedCorrectBehavior);
}
Run the test - MUST FAIL:
Verify failure reason:
Commit the failing test:
git add tests/...
git commit -m "test: reproduce bug - [description]
Failing test demonstrates [bug behavior].
Expected: [correct behavior]
Actual: [buggy behavior]
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>"
Phase 2: Fix the Code
Minimal change:
Run the test - MUST PASS:
Run ALL tests:
Refactor if needed:
Phase 3: Commit the Fix
git add src/...
git commit -m "fix: [description of bug fix]
Resolves issue where [bug behavior] occurred.
Root cause: [explanation]
Fix: [what was changed]
Test: tests/.../test_bug_reproduction.py
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>"
❌ DO NOT:
✅ DO:
Traditional Approach (Anti-Pattern):
1. Guess where problem is
2. Change production code
3. Deploy and test manually
4. Still broken? Go to step 1
5. Eventually works (you think)
6. Hope you didn't break anything
Problems:
Test-First Approach:
1. Write failing test (reproduces bug)
2. Fix production code
3. Test passes
4. Run all tests
5. Done - proven fixed
Benefits:
User: Bug report - API returns 500 when input contains special characters
Agent (Backend-Dev):
Phase 1: Reproduce bug with test
Created: tests/test_api_special_chars.py
def test_api_handles_special_characters():
\"\"\"Bug: API returns 500 for input with special chars\"\"\"
client = TestClient(app)
response = client.post("/api/process", json={
"text": "Hello <world> & friends!"
})
# Should return 200, not 500
assert response.status_code == 200
assert response.json()["status"] == "success"
Running test... ❌ FAILED
AssertionError: assert 500 == 200
Good! Test reproduces the bug.
Committed: git commit -m "test: reproduce API 500 with special chars"
Phase 2: Fix the code
Root cause: Input sanitization missing for HTML entities
Fixed: src/api/processor.py
- Added html.escape() before processing input
Running test... ✅ PASSED
Running all tests... ✅ 127/127 PASSED
Phase 3: Commit fix
git commit -m "fix: sanitize HTML entities in API input
Resolves 500 error when input contains <, >, &, etc.
Root cause: Missing input sanitization
Fix: Added html.escape() in processor
Test: tests/test_api_special_chars.py
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>"
✅ Bug fixed with proof (test passes)
✅ Regression prevented (test stays in suite)
Unit Test - Choose when:
Integration Test - Choose when:
Acceptance Test - Choose when:
Start with smallest test that reproduces bug (usually unit test).
Pitfall 1: "I'll write test after fixing"
Pitfall 2: "Test passes but bug still exists"
Pitfall 3: "Too hard to write test"
Pitfall 4: "I fixed it manually, works now"
/iterate - Use after fixing bug to continue with next batch/review - Request architect review for complex bug fixes.github/agents/directives/028_bugfixing_techniques.md.github/agents/approaches/test-first-bug-fixing.md.github/agents/approaches/bug-fixing-checklist.md.github/agents/directives/017_test_driven_development.md (TDD)