MCPInstall

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
  1. 01

    Install

    Run the command in your project. The CLI asks which agents to install for.

  2. 02

    Describe the task

    Ask your agent for something this skill covers. It loads test-first-bugs automatically when relevant.

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

  1. Understand the bug, Gather details about expected vs actual behavior
  2. Identify the test location, Determine where tests live in the project (check for tests/, __tests__/, spec/, *.test.*, *.spec.* patterns)
  3. Write a failing test, Create a test that demonstrates the bug

Phase 2: Fix with subagents

  1. Launch fix subagents, Use the Task tool with subagent_type=general-purpose to attempt fixes
  2. Run the test, Verify the fix by running the specific test
  3. Iterate if needed, If test still fails, launch additional subagents with new approaches

Phase 3: Verify and complete

  1. Run full test suite, Ensure no regressions were introduced
  2. 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:

  1. Direct fix agent, Focus on the immediate code causing the bug
  2. Root cause agent, Investigate deeper architectural issues
  3. Edge case agent, Look for similar bugs in related code

When projects lack tests

If the project has no test infrastructure:

  1. Set up minimal test framework first
  2. Create the test file in a sensible location
  3. 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:

  1. Detects when a user reports a bug
  2. Reminds Claude to follow the test-first workflow
  3. Blocks Edit/Write tools until a test file has been created or modified

Additional resources

Reference files

  • references/test-frameworks.md, Framework-specific test patterns
  • references/common-bugs.md, Common bug patterns and test strategies

Example files

  • examples/python-bug-test.py, Python pytest example
  • examples/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

View all →

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.

Docs & Writing2.9K installs

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.

DevOps & Cloud604 installs

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.

Docs & Writing505 installs

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.

Media & Creative426 installs

Popular testing & qa skills

View category →

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.

Testing & QA1.2M installs

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.

Testing & QA996.2K installs

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.

Testing & QA484.1K installs

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.

Testing & QA337.8K installs

test-driven-development

obra/superpowers

Use when implementing any feature or bugfix, before writing implementation code

Testing & QA261.8K installs

Use when implementation is complete, all tests pass, and you need to decide how to integrate the work

Testing & QA216.8K installs