
test-first-bugs
Enforces a test-driven bug-fixing workflow. Use when a user reports a bug, failing code, an error, or asks to fix something.
- Installs
- 157
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/jamditis/claude-skills-journalism --skill test-first-bugs- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads test-first-bugs automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
Test-first bug fixing
Enforce a disciplined bug-fixing workflow that prevents regression and parallelizes fix attempts.
Core workflow
When a bug is reported, follow these steps in order:
Phase 1: Reproduce and document
- Understand the bug, Gather details about expected vs actual behavior
- Identify the test location, Determine where tests live in the project (check for
tests/,__tests__/,spec/,*.test.*,*.spec.*patterns) - Write a failing test, Create a test that demonstrates the bug
Phase 2: Fix with subagents
- Launch fix subagents, Use the Task tool with
subagent_type=general-purposeto attempt fixes - Run the test, Verify the fix by running the specific test
- Iterate if needed, If test still fails, launch additional subagents with new approaches
Phase 3: Verify and complete
- Run full test suite, Ensure no regressions were introduced
- Report success, Confirm the bug is fixed with passing test as proof
Writing the failing test
Test naming convention
Name the test to describe the bug:
# Python (pytest)
def test_user_login_fails_when_email_has_uppercase():
...
# Python (unittest)
def test_should_handle_empty_input_without_crashing(self):
...
// JavaScript (Jest/Vitest)
it('should not crash when input array is empty', () => { ... });
test('handles special characters in username', () => { ... });
// TypeScript
describe('UserService', () => {
it('returns null when user not found instead of throwing', () => { ... });
});
Test structure
Every bug reproduction test follows this pattern:
def test_bug_description():
# 1. ARRANGE - Set up the conditions that trigger the bug
input_data = create_problematic_input()
# 2. ACT - Perform the action that causes the bug
result = function_under_test(input_data)
# 3. ASSERT - Verify the expected (correct) behavior
assert result == expected_value # This should FAIL initially
Finding the right test file
Check the project structure for existing test patterns:
# Find test files
find . -name "*.test.*" -o -name "*.spec.*" -o -name "test_*.py" | head -20
# Find test directories
ls -la tests/ __tests__/ spec/ test/ 2>/dev/null
# Check package.json for test command
grep -A5 '"test"' package.json
Launching fix subagents
Use the Task tool to parallelize fix attempts:
Task tool parameters:
- subagent_type: "general-purpose"
- description: "Fix [bug description]"
- prompt: Include:
1. The bug description
2. The failing test location and contents
3. Suspected cause (if known)
4. Constraint: "Run the test to verify your fix works"
Parallel fix strategies
Launch multiple subagents with different approaches:
- Direct fix agent, Focus on the immediate code causing the bug
- Root cause agent, Investigate deeper architectural issues
- Edge case agent, Look for similar bugs in related code
When projects lack tests
If the project has no test infrastructure:
- Set up minimal test framework first
- Create the test file in a sensible location
- Document the test setup for future use
Quick test setup commands
# Python
pip install pytest
mkdir -p tests && touch tests/__init__.py
# JavaScript/TypeScript
npm install --save-dev jest
# or
npm install --save-dev vitest
# Go
# Tests are built-in, create *_test.go files
Verifying the fix
After subagent reports completion:
# Run the specific test
pytest tests/test_module.py::test_bug_description -v
npm test -- --grep "bug description"
go test -run TestBugDescription -v
# Run full suite to check for regressions
pytest
npm test
go test ./...
Example workflow
User reports: "The login function crashes when email has spaces"
Phase 1, Write failing test:
# tests/test_auth.py
def test_login_handles_email_with_spaces():
"""Bug: Login crashes when email contains spaces"""
auth = AuthService()
# This should return an error, not crash
result = auth.login("user @example.com", "password")
assert result.success == False
assert "invalid email" in result.error.lower()
Run test to confirm it fails:
pytest tests/test_auth.py::test_login_handles_email_with_spaces -v
# Expected: FAILED (demonstrates the bug)
Phase 2, Launch subagent:
Task tool:
- subagent_type: "general-purpose"
- description: "Fix email space crash"
- prompt: "Fix the login crash when email contains spaces.
Bug: AuthService.login() crashes instead of returning error when email has spaces.
Failing test: tests/test_auth.py::test_login_handles_email_with_spaces
After fixing, run: pytest tests/test_auth.py::test_login_handles_email_with_spaces -v
The test must pass to confirm the fix."
Phase 3, Verify:
# Specific test passes
pytest tests/test_auth.py::test_login_handles_email_with_spaces -v
# PASSED
# No regressions
pytest tests/test_auth.py -v
# All tests pass
Integration with hooks
The bug-report-detector hook in this plugin automatically:
- Detects when a user reports a bug
- Reminds Claude to follow the test-first workflow
- Blocks Edit/Write tools until a test file has been created or modified
Additional resources
Reference files
references/test-frameworks.md, Framework-specific test patternsreferences/common-bugs.md, Common bug patterns and test strategies
Example files
examples/python-bug-test.py, Python pytest exampleexamples/js-bug-test.js, JavaScript Jest example
Scripts
scripts/find-tests.sh, Locate test infrastructure in a project
FAQ
What does the test-first-bugs skill do?
Enforces a test-driven bug-fixing workflow. Use when a user reports a bug, failing code, an error, or asks to fix something.
How do I install test-first-bugs?
Run npx skills add https://github.com/jamditis/claude-skills-journalism --skill test-first-bugs in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/test-first-bugs/ (personal) or .claude/skills/test-first-bugs/ (project).
Which AI agents can use test-first-bugs?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is test-first-bugs safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains test-first-bugs?
It is published by jamditis in jamditis/claude-skills-journalism. It has 157 recorded installs.
More from jamditis/claude-skills-journalism
web-scraping
jamditis/claude-skills-journalism
Authorized web scraping with fallback cascades and access-failure handling. Use for social media, yt-dlp, CAPTCHA or 403 blocks.
academic-writing
jamditis/claude-skills-journalism
Scholarly writing and research compliance. Use for CRediT, preregistration, Plan S, Nelson Memo, preprints, ORCID, LLM disclosure.
page-monitoring
jamditis/claude-skills-journalism
Web page change detection, availability tracking, and RSS feed generation. Use to monitor changes, downtime, or make a feed.
fact-check-workflow
jamditis/claude-skills-journalism
Structured fact-checking workflow. Use when verifying claims for publication, rating claims, or setting pre-publication checks.
pdf-design
jamditis/claude-skills-journalism
Designs PDF reports and proposals from HTML with previews and branding. Use to create, export, or securely upload a PDF.
source-verification
jamditis/claude-skills-journalism
Verify sources, claims, images, video, documents, interviews, and synthetic media with SIFT and a durable evidence trail. Use before relying on uncertain material.
Popular testing & qa skills
tdd
mattpocock/skills
Test-driven development. Use when the user wants to build features or fix bugs test-first, mentions "red-green-refactor", or wants integration tests.
grilling
mattpocock/skills
Grill the user relentlessly about a plan, decision, or idea. Use when the user wants to stress-test their thinking, or uses any 'grill' trigger phrases.
migrate-to-shoehorn
mattpocock/skills
Migrate test files from as type assertions to @total-typescript/shoehorn. Use when user mentions shoehorn, wants to replace as in tests, or needs partial test data.
run-train
lllllllama/rigorpilot-skills
Rigor Train skill for deep learning research repositories. Use when a documented or selected training command should be run conservatively for startup verification, short-run verification, full kickoff, or resume, with command, config, seed, log, checkpoint, status, and metric evidence written to standardized trainoutputs/. Do not use for environment setup, exploratory sweeps, speculative idea implementation, or end-to-end orchestration.
test-driven-development
obra/superpowers
Use when implementing any feature or bugfix, before writing implementation code
finishing-a-development-branch
obra/superpowers
Use when implementation is complete, all tests pass, and you need to decide how to integrate the work