fix-issue
fix-issue
End-to-end workflow: GitHub issue → implementation → quality gates → PR.
Quick start
/fix-issue 42
Workflow
1. Fetch & understand the issue
gh issue view <number> --json title,body,labels,assignees,comments
- Extract: title, description, acceptance criteria (look for checkboxes
- [ ]), labels - If no explicit acceptance criteria exist, derive them from the description
- State your understanding before writing any code
2. Branch
git checkout -b fix/issue-<number>-<slug>
# slug = kebab-case of issue title, max 5 words
Never work directly on main/master.
3. Implement
- Scope the fix to exactly what the issue describes — no extra refactors
- Read relevant files before editing
- Make commits as you go with clear messages referencing
#<number>
4. Pre-PR quality gates (ALL must pass)
Run these in order. Stop and fix before moving on if any fail.
# a. Type checking (if applicable)
npx tsc --noEmit # TS projects
# or: mypy . # Python projects
# b. Lint
npm run lint # JS/TS
# or: ruff check . # Python
# c. Tests
npm test # or: pytest, go test ./..., cargo test
Then manually verify each acceptance criterion from the issue:
- For each
- [ ]checkbox in the issue body: confirm it is satisfied - If the feature has a UI: start dev server, exercise the golden path
Do not open the PR if any gate fails.
5. Open the PR
gh pr create \
--title "<issue title>" \
--body "$(cat <<'EOF'
## Summary
<bullet list of changes>
## Closes
Closes #<number>
## Acceptance criteria
<copy each criterion with ✅ next to each completed one>
## Test plan
<how a reviewer can verify this works>
🤖 Generated with [Claude Code](https://claude.com/claude-code)
EOF
)"
Return the PR URL to the user.
Edge cases
| Situation | Action |
|---|---|
| Issue not found | Report gh issue view error, stop |
| No test suite exists | Note it, proceed, flag in PR body |
| Tests fail after fix | Fix tests or the implementation — never skip |
| Issue is ambiguous | Ask one clarifying question before branching |
| Issue already has a branch/PR | Check with user before creating a new one |
See REFERENCE.md for language-specific quality gate commands.
More from rockclaver/systemcraft
code-graph
Builds and maintains a `.claude/codegraph.md` index of a codebase — a structured map of every module with purpose, key exports, and dependencies — so the agent can navigate any repo by reading one file instead of scanning dozens. Use when starting work on an unfamiliar codebase, when asked to index a repo, when context costs are high from repeated scans, or at the start of any task that will touch multiple files.
14find-code
Locate files and code using grep and shell scripts — never by AI scanning. Returns exact file paths and line numbers so the agent can jump directly to the location. Use whenever the agent needs to find a function, class, variable, import, file, or any pattern in the codebase. Code and file discovery must always be a tool call, never an AI guess.
14grill-me
Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".
13prd-to-plan
Turn a PRD into a multi-phase implementation plan using tracer-bullet vertical slices, saved as a local Markdown file in ./plans/. Use when user wants to break down a PRD, create an implementation plan, plan phases from a PRD, or mentions "tracer bullets".
13write-a-prd
Create a PRD through user interview, codebase exploration, and module design, then submit as a GitHub issue. Use when user wants to write a PRD, create a product requirements document, or plan a new feature.
13design-api
Design and implement consistent, DRY REST API endpoints for database models — handlers, routing, validation, error responses, and shared utilities — then generate test coverage for every endpoint. Use when the user asks to write an API, add endpoints for a model, build a REST layer, or create CRUD routes.
13