agentleFS
akshaypimprikarakshaypimprikar/pragma/.claude/skills/bugfix/SKILL.md

bugfix

Skill4 starsChanged 4 days agoMITView on GitHub

Fix a reported bug with a regression test. Invoke with a bug description and reproduction steps.

35 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use refactor, commit and 5 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • GitHubSkill

    refactor

    Surgical code refactoring to improve maintainability without changing behavior. Covers extracting functions, renaming variables, breaking down god functions, improving type safety, eliminating code smells, and applying design patterns. Less drastic than repo-rebuilder; use for gradual improvements.

    Also in 6 projects that use this

  • SentrySkill

    commit

    Create commit messages following Sentry conventions. Use when committing code changes, writing commit messages, or formatting git history. Follows conventional commits with Sentry-specific issue references.

    Also in 8 projects that use this

  • Microsoft AzureSkill

    docs

    Also in 3 projects that use this

  • MicrosoftSkill

    pr-review

    Verify the technical accuracy of a vscode-docs pull request against the VS Code source code in microsoft/vscode. Use when reviewing a docs PR for factual correctness: setting names, command IDs, default values, API shapes, keybindings, versioned availability, and described behavior.

    Also in 3 projects that use this

  • Hugging FaceSkill

    implement

    Make tests pass. Invoke after /write-tests produces failing tests.

    Also in 3 projects that use this

  • NVIDIASkill

    research

    Before designing a feature, research how comparable libraries solve the problem, check best practices, known pitfalls, and upstream changes. Use when starting a new feature, investigating an unfamiliar area, or the user asks to research something.

    Also in 3 projects that use this

The file

We split this skill into the rules it gives an agent

8 rules. 0 are common, 6 are distinctive, and 2 are very specific to this project.

  • 0

    Common

    Most of the 32 edited versions we read keep these.

  • 6

    Distinctive

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Read AGENTS.md/CLAUDE.md before touching any file.

    line 20
  2. Distinctive:

    Before changing any production code, write a test that:

    line 28
  3. Distinctive:

    Run it to confirm it fails:

    line 32
  4. Distinctive:

    Do not proceed until it fails for the right reason.

    line 40
  5. Distinctive:

    Run the new test — must pass

    line 46
  6. Distinctive:

    Run the full test suite — must all pass, no regressions:

    line 47
  7. Very specific:

    All fixes must respect the layer boundaries in AGENTS.md/CLAUDE.md:

    line 83
  8. Distinctive:

    No business logic moved into Views to work around a bug

    line 86

“Common” is measured: kept by at least 6 in 10 of the 32 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Bug Fix Agent

You are the Bug Fix Agent for an iOS app project. Your job is to fix a reported bug with a regression test.

Trigger

Invoked with a bug report: description + reproduction steps (e.g. /bugfix "CSV import creates duplicate transactions when imported twice").

Process

1. Create the branch

Regular bug: Branch fix/<bug-name> off develop. Hotfix (production bug on main): Branch hotfix/<bug-name> off main, then merge to both main and develop.

Read AGENTS.md/CLAUDE.md before touching any file.

Also read if they exist — skip silently if absent:

  • .claude/context/invariants.md — inviolable rules; ensure the fix does not violate any
  • .claude/context/rejections.md — past review violations; ensure the fix does not repeat known bad patterns
  • .claude/context/incidents.md — past bugs and their root causes; check whether this symptom matches one already diagnosed before investigating from scratch

2. Write the failing test first

Before changing any production code, write a test that:

  • Reproduces the exact bug described
  • Fails with a clear error message that matches the symptom

Run it to confirm it fails:

xcodebuild test <BuildTarget> -scheme <AppName> \
  -destination 'platform=iOS Simulator,name=<simulator from AGENTS.md/CLAUDE.md>' \
  -only-testing:<AppName>Tests/<SuiteName>/<testName> \
  2>&1 | grep -E "Test.*passed|Test.*failed|BUILD"

Do not proceed until it fails for the right reason.

3. Implement the minimal fix

Change only what's needed to make the failing test pass. Do not refactor, rename, or clean up surrounding code unless it's the direct cause of the bug.

4. Confirm the fix

  • Run the new test — must pass
  • Run the full test suite — must all pass, no regressions:
xcodebuild test <BuildTarget> -scheme <AppName> \
  -destination 'platform=iOS Simulator,name=<simulator from AGENTS.md/CLAUDE.md>' \
  2>&1 | grep -E "TEST SUCCEEDED|TEST FAILED"

5. Update CHANGELOG

Append a one-line entry to the ## [Unreleased] section of CHANGELOG.md (create the section if absent). Skip only for internal refactors with no user-visible behaviour change.

6. Log the incident

Append an entry to .claude/context/incidents.md (create the file with a one-line header if it doesn't exist):

## YYYY-MM-DD — <bug name>
**Symptom:** <what was observed — error message, wrong behavior, exact repro condition>
**Root cause:** <one line — the actual mechanism, not just "logic error">
**Fix:** <file:line or brief description of the change>
**Search terms:** <keywords a future symptom description might match — error strings, type names, subsystem>

The point is a searchable root-cause record, not a duplicate of the CHANGELOG entry (which is user-facing) or the git commit message (which is buried in history until someone thinks to git log for it). Keep each entry to what a future /bugfix run skimming this file needs to recognize "this is the same thing" from a different symptom description.

7. Commit and PR

git add <changed files>
git commit -m "fix: <short description of what was wrong>"

Regular bug: Open PR to develop. The Review Agent (/review) runs on the PR. Hotfix: Open PR to main — also open a second PR to develop. Both go through /review and, on the app lane, code-review (medium) (via /pr-followup) before merging; /test's coverage audit runs before /gates. Unlike release/SKILL.md's develop back-merge (safe as a raw git merge because a release branch only ever contains commits develop already reviewed), a hotfix branches directly off main and its commits have never been through /review on develop — so its back-merge needs the same gate its main PR got, not a raw merge.

Architecture rules

All fixes must respect the layer boundaries in AGENTS.md/CLAUDE.md:

  • Domain Service fixes stay in Services/
  • Repository fixes stay in Repositories/ (implementation subfolder per your architecture)
  • No business logic moved into Views to work around a bug

Done when

Failing test passes, full suite green, PR open.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.