Fix GitHub Issue

You are fixing a GitHub issue for the jiki-education/api repository.

Issue details

!`gh issue view $ARGUMENTS --json number,title,body,labels,comments`

Issue number: !echo "$ARGUMENTS" | grep -oE '[0-9]+$'

Critical: Two phase.

Your work is split into two phases.

The first phase is purely planning. You must NOT make any changes to git state (switching branches, creating branches, creating worktrees, etc). You should presume that other work is SIMULTANEOUSLY happening WHILE you are planning.

Once the plan has been APPROVED by the user you should check the current git state:

• •Run git status to check for uncommitted changes.
• •If there are uncommitted or staged changes, STOP and ask the user how to proceed. Do NOT stash or discard anything.

Never destroy or discard existing work.

If the plan has been approved and the working tree is clean, continue with your work.

Workflow

Follow these steps in order. Do not skip any step.

Step 1: Understand the issue

Read the issue details above carefully. Identify:

• •What is broken or needs to change
• •Which parts of the codebase are likely affected
• •Any reproduction steps or error messages mentioned

Read the CLAUDE.md file for the area of the codebase involved.

Step 2: Plan the fix

Do NOT create a branch or worktree yet. Stay on the current branch while planning.

Use /plan to enter plan mode. Explore the codebase thoroughly:

• •Find the relevant files using Glob and Grep
• •Read the code to understand current behavior
• •Identify what needs to change and why
• •Check for existing test coverage
• •Look at similar patterns in the codebase for reference

Design a complete fix before writing any code.

Step 3: Create a worktree

Only create the worktree after the plan is approved. The issue number has been extracted above (works whether the argument was a full URL like https://github.com/jiki-education/api/issues/123 or just 123).

git pull --ff-only origin main
mkdir -p ../api-worktrees
git worktree add ../api-worktrees/fix-<issue-number> -b fix/<issue-number>
cd ../api-worktrees/fix-<issue-number>

Important: After creating the worktree, cd into it immediately. All subsequent work (file edits, bash commands, tests) happens inside the worktree. The main repo stays untouched on its current branch.

Step 4: Implement the fix

After the plan is approved and the worktree is created, implement the changes:

• •Follow existing patterns and conventions in the codebase
• •Business logic belongs in /app/commands/ using the Mandate pattern
• •Keep controllers thin — delegate to commands
• •Add or update tests as appropriate (Rails TestUnit, FactoryBot)
• •Keep changes minimal and focused on the issue

Step 5: Run tests

Run the relevant tests for the changes you made:

bin/rails test <test-file-or-directory>

If tests fail, fix the issues and re-run until all pass.

Rubocop and brakeman will be checked automatically by the pre-commit hook when you commit — you do not need to run them manually.

Step 6: Commit the changes

Stage only the files you changed (do not use git add -A or git add .). Write a clear commit message that describes the fix.

Step 7: Push and create a PR

Push the branch and create a pull request:

git push -u origin fix/<issue-number>

Create the PR using gh pr create. The PR body must include Closes #<issue-number> to auto-close the issue on merge:

gh pr create --title "<concise title>" --body "$(cat <<'EOF'
Closes #<issue-number>

## Summary
<bullet points describing what changed and why>

## Test plan
<checklist of how the fix was validated>

🤖 Generated with [Claude Code](https://claude.com/claude-code)
EOF
)"

Step 8: Clean up worktree

cd /Users/iHiD/Code/jiki/api
git worktree remove ../api-worktrees/fix-<issue-number>

This removes the worktree directory and returns you to the main repo. The branch remains on the remote for the PR.

Report the PR URL to the user.