Add fix-bug agent skill [loop engineering]

[drbenvincent]

What is this?

Imagine you have a robot helper that fixes bugs in your codebase. This PR adds a recipe that teaches that robot how to fix bugs in CausalPy — step by step, like a checklist.

You can say things like "fix bug #149" or "bugfix PR #123", and the agent knows what to do next.

How does it work? (the simple version)

1. Read the bug — understand what's broken and pick one thing to fix (not ten at once).
2. Fix it — write the code, run tests, push a branch, open a PR.
3. Get a second opinion — a different robot reads the PR and leaves review comments. The fixer never reviews its own work.
4. Try again if needed — fix what the reviewer found, push again, repeat (up to 3 rounds).
5. Ask a human if stuck — if it can't get there after 3 tries, it labels the PR needs:maintainer-decision and hands off.

Think of it like homework: you do the work, a friend checks it, you fix mistakes, and if you're still stuck you ask the teacher.

Why is this cool for developers?

• Less babysitting — you point at a GitHub issue and walk away; the agent handles branch, tests, PR, and review loop.
• Safer automation — the fixer and reviewer are separate, so the agent doesn't rubber-stamp its own mistakes.
• Resumable — special markers in PR comments (fix-bug-round, fix-bug-approved, etc.) let a new session pick up where the last one left off.
• One bug per PR — umbrella issues with lots of sub-bugs get tackled one at a time, so PRs stay small and reviewable.
• CausalPy-aware — the recipe knows our conda env, prek, pytest paths, and when to escalate to maintainers.

Where did it come from?

Copied from the fix-bug skill in pathmc, which has been working well. The workflow is the same; only the CausalPy-specific bits (how to run tests, lint, etc.) were swapped in.

Test plan

• Pre-commit hooks pass on the new skill file
• Skill is discoverable under .agents/skills/fix-bug/SKILL.md

[drbenvincent]

@juanitorduz @cetagostini I've been using this to great effect in pathmc. Can you give it a quick once over? It's my first exploration of loop engineering. It seems to work really well in terms of eliminating a lot of manual orchestration work that I was doing.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.03%. Comparing base (ea44a98) to head (e1cba85).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1163   +/-   ##
=======================================
  Coverage   96.03%   96.03%           
=======================================
  Files         105      105           
  Lines       16370    16370           
  Branches      916      916           
=======================================
  Hits        15721    15721           
  Misses        485      485           
  Partials      164      164           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[drbenvincent]

Automated triage

Recommendation: review:medium — no decision gate identified.

Why:

• Adds a single developer-only skill file (.agents/skills/fix-bug/SKILL.md) with no runtime or public API changes.
• The skill is an agent recipe for bug-fixing workflows; it does not affect users, dependencies, or production behaviour.
• All CI checks pass — prek, tests (3.11, 3.14), docs, CodeQL, and pre-commit.

Review focus:

1. Confirm the skill instructions match the projects actual dev workflow (conda env, prek, pytest paths).
2. Check that the escalation/resumption protocol (fix-bug-round, fix-bug-approved markers) is documented clearly.
3. Verify no unintended side effects from .agents/skills/ directory additions in editor tooling.

Confidence: high