---
name: fix-one-issue
description: |
  Use this skill to fix a single issue end-to-end: read
  the repo README and CLAUDE.md, sync master, confirm the
  baseline build is green, branch by the issue name, write
  a failing test that reproduces the bug, commit the test,
  fix the source, stabilize the build and linters, commit
  the fix, push, and open a pull request. One issue per
  run, one branch per run, one pull request per run —
  then stop.
---

Run `git status` first; if the working directory has any
  uncommitted changes, untracked files, or staged hunks,
  stop immediately and do not continue.

This skill must start from a clean tree so that nothing
  it does can mix with, overwrite, or accidentally commit
  unrelated work in progress.

Prioritize correctness over speed at every step: read
  carefully, reason through each change, verify each
  result, and never trade a thorough fix for a faster
  one.

Read the `README.md` file at the root of the repository
  before doing anything else; it names the build command,
  the test layout, the branch and commit conventions, and
  any project-specific rules this skill must respect.

Read the `CLAUDE.md` file at the root of the repository
  too, if it exists; it carries instructions written
  specifically for the agent — coding conventions, build
  shortcuts, files to avoid, and project-specific rules
  that override generic defaults.

Check out the `master` branch and run `git pull` to sync
  with the remote, so the work starts from the latest
  known state and not from a stale local copy.

Skim the code base while still on `master`, and if you
  spot serious inconsistencies or areas for improvement
  — broken architecture, dead modules, contradicting
  conventions, missing safeguards, or other structural
  problems — open new issues on GitHub (for example with
  `gh issue create`) describing each one, then continue
  the current run unaffected.

Do not file issues for small or cosmetic findings —
  typos, formatting drift, minor naming, stray imports
  — those can be folded into the fix at hand or left
  for a later pass.

Run the full build — every test, every linter, every
  static check — and confirm it is green before touching
  anything; a failing test later must be attributable to
  the new test alone.

If the baseline build fails on `master`, do not try to
  fix it as part of this run; instead, open a new issue
  on GitHub (for example with `gh issue create`) that
  explains what failed, includes the relevant log
  excerpt, and names the build command used, then stop.

Baseline repair belongs to its own issue, its own
  branch, and its own pull request.

If existing tests are flaky or outright broken — failing
  intermittently, asserting nothing, or red on a clean
  tree — do not delete them, do not skip them, and do not
  rewrite them; open a new issue on GitHub for each one
  describing the symptom and the suspected cause, then
  stop the current run.

Create a new branch whose name is exactly the issue
  number as a plain integer and nothing else — for
  example `123` for issue #123, never `fix-123`,
  `issue/123`, `123-null-pointer`, `bug_123`, or any
  other variant that adds words, English, slugs,
  prefixes, suffixes, slashes, dashes, underscores,
  or descriptions; the branch name must match the
  regular expression `^[0-9]+$` and contain no
  characters other than digits.

Reject every temptation to make the branch name
  "more readable" or "more descriptive": the integer
  alone is the contract, and a branch named anything
  other than a bare integer is a defect of this skill,
  not a stylistic choice.

Do not reuse an existing branch for unrelated work,
  and do not create the branch under any namespace
  such as `claude/`, `bot/`, `agent/`, or a username
  prefix — the branch sits at the top level of the
  ref namespace as a bare integer.

Write a single test that reproduces the bug or exercises
  the missing feature; place it next to the matching
  feature file, give it a sentence-style name, and assert
  exactly one behavior with a negatively-toned failure
  message.

Run the build and confirm the new test fails for the
  expected reason — not because of a typo, a missing
  import, or an unrelated error; do not continue until
  the failure is the failure the issue describes.

Commit the failing test on its own, with a message that
  names the issue and states that the test reproduces it;
  this commit captures the bug as executable evidence
  before any fix exists.

Fix the issue in the source, editing by hand, one file at
  a time; change only what the failing test demands, and
  do not refactor neighboring code, rename APIs, or clean
  up unrelated style.

Run the full build again and stabilize it: the new test
  must pass, every previously-passing test must still
  pass, and every linter and static check must be clean.

Fix every linter and static-check warning the build
  surfaces, including ones that existed before this
  change; do not suppress with `eslint-disable`, `noqa`,
  `.skip`, `--no-verify`, lowered thresholds, or
  commented-out tests.

Commit the fix on its own, with a message that explains
  the root cause and references the issue; keep the test
  commit and the fix commit separate so the history shows
  red-then-green.

Push the branch to the remote and open a pull request
  against `master`; the title must reference the issue,
  and the description must link to it and summarize the
  root cause and the fix in one short paragraph.

Keep the pull request description concise and free of
  headings, bullet lists, tables, checkboxes, or any
  other elaborate formatting — plain prose only, a few
  sentences at most.

Talk like a human in every piece of text this skill
  writes — commit messages, the pull request title and
  description, replies to Copilot, and the final ping
  comment — state the point directly, drop pleasantries
  and marketing language, and never sign off with an
  AI-disclosure line or a "generated by" banner.

Check the status of the CI jobs on GitHub for the pull
  request (for example with `gh pr checks --watch`) and
  wait for every one of them to finish; do not consider
  the work done while any check is still running.

If any CI job fails — for any reason, including flakes,
  environment issues, unrelated linters, or checks the
  local build did not run — diagnose the failure from
  the job logs, fix the code base, commit, and push
  again; repeat this loop until every check on the pull
  request is green.

Do not mark a failure as "not my problem" and do not
  ask a maintainer to re-run a red job to make it green
  by chance.

Stop only after every CI job is green.

Wait for GitHub Copilot to review the pull request (for
  example by polling `gh pr view --json reviews,comments`
  or `gh api repos/:owner/:repo/pulls/:number/comments`)
  and do not proceed while Copilot has not yet posted
  its review.

Address every suggestion Copilot leaves on the pull
  request — inline comments and review summary alike —
  one by one, with no exception and no silent dismissal.

For each Copilot suggestion, either apply the fix in the
  code, commit it, and push to the same branch, or reply
  to that specific Copilot comment on GitHub (for example
  with `gh api .../comments/:id/replies` or
  `gh pr comment`) explaining the technical reason the
  suggestion does not apply.

Do not mark a Copilot thread resolved without either a
  pushed code change or a written reply, and do not
  bundle replies into a single generic comment — answer
  each suggestion where it was raised.

If a code change made in response to Copilot triggers
  CI again, wait for the new run to finish and repeat
  the CI loop until every check is green once more.

Stop only after every CI job is green and every Copilot
  suggestion has been answered with either a commit or
  a reply.

Do not start the next issue, do not merge, do not
  rebase — hand off to review.

Do not bundle multiple issues into one branch or one
  pull request; if a second issue surfaces during the
  fix, note it and run this skill again from the top
  for that issue.

Do not skip the failing-test step "because the fix is
  obvious"; without a red test first there is no proof
  the fix addresses the issue and no guard against
  regression.

Do not amend or force-push once the pull request is
  open unless review explicitly asks for it; new
  feedback becomes new commits.

After the fix is ready, update `README.md` and
  `CLAUDE.md` if the change makes either of them
  inaccurate, incomplete, or stale — new commands,
  new conventions, renamed files, removed features,
  or shifted defaults all require an update in the
  same pull request.

Once the pull request is fully ready — every CI job
  green, every Copilot thread answered, and every
  documentation update committed — post a single
  comment on it that tags the issue reporter with
  `@username` and asks them to review the change.