fix-issue
Pick up an open GitHub issue in this repo and ship a fix as a PR. Reads the issue body (assumes the create-issue format), branches from latest main, implements the change, runs `make test`, pushes, an
SKILL.md.claude/skills/fix-issue/SKILL.md
GitHubfix-issue
Take a single issue from open to PR. The issue is the source of truth — read it, plan against it, verify against its acceptance criteria. Issues filed by create-issue follow a known shape: Summary / Context / Current Behavior / Expected Behavior / Acceptance Criteria / (optional) Notes.
When to Use
- User asks to "fix issue #N", "pick up the latest issue", "work on issue X"
- User invokes
/fix-issuewith or without a number - User asks what's available — list open
claude-readyissues
Arguments
/fix-issue 42— fix that specific issue/fix-issue(no arg) — list openclaude-readyissues and ask which to pick up/fix-issue list— same as no-arg
Never pick an issue on your own without showing the user the candidate first.
Instructions
Step 1: Resolve the target issue
If given a number, fetch it:
gh issue view <N> --json number,title,body,labels,state,url
If no number, list candidates:
gh issue list --state open --label claude-ready --json number,title,labels --limit 20
Show the list and ask which one. If the chosen issue is closed, stop and ask.
Step 2: Read context
Parse the issue body against the create-issue template (Summary / Context / Current Behavior / Expected Behavior / Acceptance Criteria). If the format is off, work from what's there — don't refuse to proceed, but flag the gap to the user.
Read CLAUDE.md for project conventions (Python 3.12 + FastAPI + SQLModel + typer CLI under src/job_applier/; SvelteKit + Svelte 5 runes + TypeScript under web/src/; pytest + vitest, make test; ruff lint via make lint; migrations as _ensure_*_columns() in models/migrations.py — no alembic; mutations via SvelteKit form actions; web/src/lib/api.ts must stay browser-safe; AI only via the sandboxed CLI subprocess in ai/providers.py, never an SDK or API key; no LinkedIn/Indeed scraping; feature branch + PR workflow).
Read the files named in Context. If the issue doesn't name files, grep/find them from the description before guessing (grep -rn across src/job_applier/ and web/src/).
Step 3: Plan and confirm
Output to the user:
- 1–2 sentences restating what the issue asks for
- Files you intend to touch (Python under
src/job_applier/, frontend underweb/src/, tests undertests/and/orweb/src/**) - Test plan — which existing tests cover this area, which new test(s) you'll add (pytest for backend, vitest for frontend)
- Any ambiguity in the issue you want resolved before coding
Wait for go-ahead. This step exists because issue bodies are often terse and one round of clarification saves a wrong-direction PR.
Step 4: Branch from latest main
git status --short # must be clean
git fetch origin main
git checkout main && git pull --ff-only origin main
git checkout -b fix/issue-<N>-<short-slug>
If the working tree is dirty, stop and ask. Never auto-stash.
Step 5: Implement + test
- Write the fix in scope of the acceptance criteria.
- Add or update tests. Backend tests go in
tests/test_<module>.py(reuse themake_rawfactory fromconftest.pyforRawJobsetup; use@pytest.mark.parametrizefor table-driven cases). Frontend tests go colocated asweb/src/lib/*.test.tsor underweb/src/lib/__tests__/(use@testing-library/svelte). New modules / endpoints / source adapters need tests (project rule). - If the change adds a
SQLModelfield, also add a matching idempotent_ensure_*_columns()helper insrc/job_applier/models/migrations.pyand wire it intomigrations.run()— fresh and returning DBs both need to land on the same schema. - Run
make test(which runs bothmake test-apipytest andmake test-webvitest). If backend changed, also runmake lint. If frontend changed, also runcd web && npm run check. - Iterate until green. Don't push a red branch.
Step 6: Standards self-review
Before staging, re-verify the diff against the project's standards — not just that it works, but that it meets the bar /code-review would hold it to. Run the gate against the same diff you're about to commit:
git diff main
Walk this checklist; each line is a gate, not a suggestion. Fix anything that fails before committing.
- Python / TypeScript idioms — Python: typed params and returns on public functions,
from __future__ import annotationsat the top of new modules, no bareexcept:, f-strings, ruff-clean (make lint). TypeScript/Svelte: explicit types on exports, noanyleaking intoweb/src/lib/api.ts,import typefor type-only imports,npm run checkclean. - Logging — no
print(insrc/job_applier/(the CLI usestyper.echo, everything else logging); noconsole.log(inweb/src/. Grep the diff for both. - Error handling — check fallible calls:
httpx.get(/.post(/raise_for_status(),json.loads(,Path(...).read_text(, SQLModel.one(),subprocess.run((timeouts, non-zero exit),pdf.render_to_pdf((→ 503). Form actions returnfail(<status>, { … })instead of throwing;fetch(results checkresponse.ok. A broadexcept Exceptionis acceptable only with# noqa: BLE001and a comment explaining the isolation — otherwise don't swallow errors. - Project hard rules — grep the diff for
import anthropic,from anthropic,import openai,ANTHROPIC_API_KEY,OPENAI_API_KEY(AI runs only through the CLI subprocess inai/providers.py);linkedin.com/indeed.cominsrc/job_applier/sources/; and any loosening of the draft character ban (—–“”‘’) inai/prompts/draft.mdorai/bans.py. Confirm you're not onmain. - Never hold a DB transaction across network or subprocess I/O — no open
Sessionspanningsource.fetch(), anhttpxcall, orsubprocess.run; write in short batches. - Documentation — where a changed function has a docstring or TSDoc, its
Raises:/Returns:/Args:(or@param/@returns/@throws) still match the code. There is nopydocstyle/eslint-plugin-jsdoc, so don't add docs for their own sake. If the change alters a rubric or draft rule, editsrc/job_applier/ai/prompts/first and then mirror it into the legacy.claude/commands/. UpdateCLAUDE.mdif a rule it states is now false. - DB migrations (when
models/changed) — every new field has an_ensure_*helper inmodels/migrations.pyguarded byPRAGMA table_info, called frommigrations.run(); a new table is added to_LEGACY_SCHEMAintests/test_migrations.py; a table rebuild orRENAME COLUMNis gated on a column check and covered by a migration test that seeds real rows; one-time backfills can't re-run;make prunestill never deletes rows. - SvelteKit (when
web/changed) — mutations go through form actions in+page.server.ts, not clientfetch(; page data comes fromload, notonMount;web/src/lib/api.tsimports nothing from$env/dynamic/private,$env/static/private,node:, orfs; new backend calls are typed methods onapi; Svelte 5 runes ($state/$derived,$app/state), and no$effectthat reads and writes the same state. - AI safety (when
ai/,drafts.py,pdf.py, ordesktop/main.jschanged) — provider calls stay argv-only (shell=Truenever), withtimeout=and_scrubbed_env(); untrusted job/resume text reaches prompts only viaprompt_safety.new_nonce()/clean_untrusted(); model output is parsed as data; draft writes go throughdrafts.save_markdown; the PDF engines still abort every subresource (_permit_request/route.abort(),webRequest.onBeforeRequest). - Test data safety — no new test enters
TestClient(app)or callsengine()without an isolated DB path; the developer's realdata/jobs.dbmust never be touched bymake test. - No debris — no commented-out code, no leftover scaffolding, no issue/PR references in comments.
/code-review is the deeper net and can be run on the branch as this gate (or in addition). Keep this inline checklist as the default: it's lighter and self-contained.
Step 7: Commit, push, open PR
Match recent commit-message style (git log --oneline -10) — short, imperative, no trailing period.
git push -u origin HEAD
gh pr create --title "<title>" --body "$(cat <<'EOF'
## Summary
<1–3 bullets on what changed>
## Test Plan
- [x] make test (passes locally)
- [ ] <any manual verification the user should do>
Closes #<N>
🤖 Generated with [Claude Code](https://claude.com/claude-code)
EOF
)"
The Closes #<N> line auto-closes the issue when the PR merges.
Step 8: Report
Return the PR URL. One line.
Guardrails
- One issue per invocation. Don't bundle fixes for multiple issues into a single PR even if they look related — open separate PRs and let the user merge in the order they prefer.
- Stay in scope. The acceptance criteria define done. If you spot adjacent bugs while reading the code, mention them at the end of the PR body (for a follow-up issue) but do not fix them in this PR.
- Never push to main directly. Always feature branch → PR.
- Never close the issue manually. Let the PR close it on merge.
- Standards self-review (Step 6) is a gate, not a formality. Run it against the diff before staging; fix what fails. Green tests are not the same as meeting the project's standards.
- Hard project rules to never violate while fixing:
- No
anthropic/openaiSDK and no API-key handling (ANTHROPIC_API_KEY,OPENAI_API_KEY). AI features run server-side only by shelling out to a user-installed CLI through the sandbox insrc/job_applier/ai/providers.py(argv-only, scrubbed env, timeout, no tools). The.claude/commands/slash commands are a legacy mirror ofsrc/job_applier/ai/prompts/, which is the source of truth. - No LinkedIn / Indeed scraping in source adapters.
- No
print()insrc/job_applier/library code (usetyper.echoin CLI, logging elsewhere); noconsole.login committed frontend code. - No raw client
fetchfor mutations — use SvelteKit form actions in+page.server.ts. web/src/lib/api.tsmust stay browser-safe (no$env/dynamic/private, nonode:/fsimports).
- No