diff --git a/.claude/commands/fix-issue.md b/.claude/commands/fix-issue.md new file mode 100644 index 00000000..f6caed82 --- /dev/null +++ b/.claude/commands/fix-issue.md @@ -0,0 +1,143 @@ +--- +description: Pull the next `ready-for-agent` issue, branch off main, implement it, and open a PR. +argument-hint: "[issue number | empty to auto-pick]" +--- + +You are picking up a labelled GitHub issue in this Next.js 16 (App Router) + React 19 + TypeScript (strict) + Tailwind CSS 4 frontend and taking it all the way to an open pull request. + +Argument from the user: `$ARGUMENTS` + +Repo: `ProjectTech4DevAI/kaapi-frontend`. + +## Guardrails + +- You push a **branch** and open a **PR**. Never push to `main`, never merge, never `--force`, never touch `.releaserc` or the workflows in `.github/`. +- `cd-dev.yml` / `deploy-staging.yml` deploy from this repo — a bad merge to `main` ships. Branch + PR only, always. +- One issue per run. Don't batch several issues into one branch. +- If the issue is ambiguous, under-specified, or would touch auth / middleware gating / the BFF contract, **stop and ask** rather than guessing. Say what's unclear. + +## 1. Select the issue + +If `$ARGUMENTS` is an issue number, use it directly: + +```bash +gh issue view +``` + +Otherwise list the queue: + +```bash +gh issue list --label ready-for-agent --state open --json number,title,labels,body +``` + +No open issues carry the label → say so plainly and stop. Don't invent work. + +Several are queued → pick one by this priority order: + +1. **Critical bugfixes** — broken behaviour users hit today +2. **Development infrastructure** — types, lint, CI, test scaffolding, dev scripts (these unblock everything after them) +3. **Tracer bullets for new features** — the thinnest end-to-end slice through every layer (route → BFF handler → client fetch → component), so the shape is validated before the feature is built out +4. **Polish and quick wins** +5. **Refactors** + +Say which issue you picked and why it outranked the others. + +## 2. Branch + +```bash +git status # never clobber uncommitted work — stash -u or stop +git checkout main && git pull +git checkout -b / +``` + +Branch naming follows this repo's existing convention (`git branch -r` to confirm): `/`, where type maps from the issue's label: + +| Issue label | Branch prefix | Commit type | +| --------------- | -------------- | ----------- | +| `bug` | `fix/` | `fix:` | +| `enhancement` | `enhancement/` | `feat:` | +| `documentation` | `docs/` | `docs:` | +| _none / other_ | `feat/` | `feat:` | + +Slug from the issue title, not the issue number: `fix/eval-card-mobile-overflow`, not `fix/issue-42`. + +## 3. Understand before you edit + +- Read `CLAUDE.md` for architecture, then `Grep`/`Glob` for the actual code paths involved. Read whole files at change sites, not just the lines you think you need. +- **Grep for existing solutions first.** `app/components/`, `app/hooks/`, `app/lib/utils/`, `app/lib/constants.ts`, `app/components/icons/`. Reusing `Button`/`Modal`/`useToast`/`clientFetch` beats authoring a new one — re-implementing what already lives two files over is the most common failure here. +- Trace the full flow before choosing a fix. A bug report names a symptom; fix the root cause where every caller routes through, not just the path the issue mentions. +- Smallest diff that actually solves it. No speculative abstractions, no scaffolding "for later", no new dependency for what a few lines cover. + +Conventions that apply to whatever you write (`/pr-review` has the full list): + +- Import alias `@/...`, never relative `../../` chains +- `"use client"` only where state / effects / handlers / browser APIs demand it +- Design-system colour tokens (`text-text-primary`, `bg-accent-primary`), not raw `text-gray-500` or hex +- No `any`; no file over 500 LOC +- BFF handlers use `apiClient(...)`; browser calls use `clientFetch(...)` +- Loading, error, and empty states all handled + +## 4. Verify + +```bash +npm run lint +npm run build +``` + +Both must pass before you commit. If the change is user-visible, run `npm run dev` and exercise the golden path **and** a failure path — report what you actually saw. Never tick a checklist box for a step you didn't run. + +## 5. Commit + +`semantic-release` reads commit messages (`.releaserc`: `feat` → minor, `fix`/`chore`/`docs`/`refactor` → patch), so **conventional commits are required** — a non-conforming subject silently breaks versioning. + +```bash +git diff # review before staging +git add # never `git add .` +git commit -m "fix: correct eval card overflow on mobile" +``` + +`.husky/pre-commit` runs `lint-staged`, which reformats staged files — if it rewrites anything, re-check `git diff HEAD` before pushing. + +Scan the diff for anything that shouldn't ship: `.env*`, tokens, keys, `console.log`, commented-out code, stray lockfiles (`package-lock.json` is the only valid one here). + +## 6. Push and open the PR + +```bash +git push -u origin +``` + +Fill `.github/PULL_REQUEST_TEMPLATE.md` — use its headings verbatim, don't invent your own: + +```bash +gh pr create --title "" --body "$(cat <<'EOF' +## Issue + +Closes # + +## Summary + + + + + +## Checklist + +Before submitting a pull request, please ensure that you mark these task. + +- [ ] Ran `npm run dev` and `npm run build` in the repository root and test. +- [ ] If you've fixed a bug or added code that is tested + +## Notes + + +EOF +)" +``` + +`Closes #` is what makes GitHub auto-close the issue on merge — don't drop it or reword it. + +Tick a checklist box only if you ran that command and it passed. If you couldn't run `npm run dev` (no browser, headless), leave it unchecked and say so in `## Notes`. + +## 7. Report back + +State: the issue picked, the branch, files touched, `lint`/`build` results, the PR URL, and anything you deliberately left out of scope.