| name | pr-description |
| description | Write the PR body — Why / What / Risk / Test plan. Skip pleasantries. Link issue. Tag CHANGELOG entry. Use 'gh pr create --body' with HEREDOC. Use when the user asks to open a PR, create a pull request, or write a PR description. |
PR Description (Vixen)
Source: foxic + standard PR practice.
Title
Conventional Commits format. Under 70 chars. The body has details, not the title.
feat(captcha): add picture-pick modefix(spam): close timing window in dedup cacherefactor(api): extract auth middlewaredocs(server): document chat config transactional write
Scopes: server, api, db, auth, bot, captcha, spam, jobs, reports, config, website, ui, i18n, docker, ci, deps.
Body sections (in this order)
- Why (1-3 sentences): the problem this solves; link to issue if any (
Closes #42).
- What (3-7 bullets): the changes, in user-facing language. Not "renamed
foo to bar" — "rename callback type for clarity."
- Risk: what can break? Backwards-compat? Migration order? Performance impact? "None known" is acceptable when true.
- Test plan: what was verified locally; what reviewer should re-check. Concrete commands and steps, not "tested it."
- CHANGELOG: confirm
[Unreleased] was updated with (component) tag, or note "internal-only, no CHANGELOG entry."
Skip
- "This PR..." preamble. Start with content, not metadata.
- Emoji in titles unless explicitly requested.
- "Generated with Claude Code" footers in PR bodies (commits are fine; the PR description is for humans).
- Restating the diff line-by-line. Reviewers can read.
gh CLI pattern
Use HEREDOC for body — preserves Markdown formatting and avoids shell quoting hell.
gh pr create --title "feat(captcha): add picture-pick mode" --body "$(cat <<'EOF'
## Why
Some users find digit captchas frustrating; picture-pick lowers friction for legit users while keeping the spam-bot solve rate similar. Closes #87.
## What
- New `ChallengeKind::PicturePick` variant + asset set under `server/assets/captcha/picture/v1/`.
- Solver UI in the callback handler (single `pick_*` action with index).
- `chat_config.captcha_kind` column; defaults to `digits`; opt-in per chat via `PATCH /chats/{id}/config`.
- Admin dashboard toggle.
## Risk
- In-flight digit challenges unaffected — `ChallengeKind` discriminates on solve.
- New assets are immutable — never overwriting existing files; v1 path is new.
- Migration is additive with default; safe to deploy app before app uses the column.
## Test plan
- `cargo test captcha::picture_pick` — green.
- `cargo sqlx prepare --check` — green.
- Manual TG bot test in dev chat — works on iOS, Android, web client.
- Admin toggle round-trips through API — verified in browser.
CHANGELOG: entry added under `[Unreleased]` `Added` `(server)` and `(website)`.
EOF
)"
Linking issues
Closes #42 / Fixes #42 in the body auto-closes on merge. Put it in Why, not the title.- Cross-repo:
Closes plugfox/related-repo#42.
- "Related to #N" if the PR touches but doesn't fully resolve another issue.
After opening
- Return the PR URL to the user.
- Don't auto-merge. Let the user (or CI gates) decide.
- If review comments require non-trivial changes, run
plan-before-code again before pushing.
Related
commit-message — Conventional Commits scope reference.verifiable-goal — populates the Test Plan section.change-impact-assessment — populates the What / Risk sections.
