pull-request

name	pull-request
description	Use when opening a pull request for this repository. Enforces atomic commits, the required PR body shape (quick explainer of what we're doing + why), and the mandatory assignee.

Skill: Pull Request

Apply this whenever you run gh pr create. The user expects every PR to follow these rules.

Hard requirements

1. Always set an assignee. Default to @me (the authenticated user running gh). If the user has named a different assignee in the conversation, use that. Never open a PR with no assignee.
2. Quick explainer in the body. The PR body opens with a short "What & Why" paragraph (2–4 sentences) that someone can read in under 15 seconds and understand the change. No marketing fluff.
3. Atomic commits on a feature branch. One logical change per commit, Conventional Commit prefixes (feat:, fix:, chore:, docs:, test:, refactor:).
4. Reference the task ID from docs/10-tasks.md when applicable (e.g., Closes A2).
5. CI must pass. After opening, watch checks with gh pr checks <pr-number> --watch (or report status back to the user with gh pr checks <pr-number>). Do not declare the PR ready for review until all required checks are green. If a check fails, fix it on the same branch and push.

PR body template

## What & Why

<2-4 sentence explainer: what this changes and why it matters.>

## Commits (atomic)

1. **<conventional commit subject>** — <one-line summary>
2. **<conventional commit subject>** — <one-line summary>

## Tests

- <command run, e.g. `npm test --workspace server`>
- <result, e.g. `42 passed`>

## Tasks closed

- Closes <task-id> (e.g. `Closes B4`)

## Notes

<Optional: caveats, follow-ups, screenshots.>

Omit any section that genuinely doesn't apply (e.g., "Tasks closed" for a pure refactor that wasn't on the list). Never omit "What & Why".

Command shape

gh pr create \
  --assignee @me \
  --title "<conventional commit-style title>" \
  --body "$(cat <<'EOF'
## What & Why
...
EOF
)"

If the repo has a default base branch other than main, pass --base explicitly. Do not pass --draft unless the user asks.

Pre-flight checklist

Before running gh pr create:

• Branch is not main/master. Create one if needed: git checkout -b <type>/<short-slug>.
• All intended commits are present and atomic (git log --oneline).
• git status is clean OR remaining uncommitted files are explicitly out of scope (call this out in PR notes).
• Branch is pushed: git push -u origin <branch>.
• Tests pass for everything in the diff (npm test, etc.).
• docs/10-tasks.md checkboxes ticked for any tasks this PR completes.

After opening

• Print the PR URL back to the user.
• If gh warned about uncommitted changes, explain which files were intentionally excluded and why.

Anti-patterns

• Opening a PR with no assignee.
• "Misc updates" / "WIP" titles. Use a real Conventional Commit subject.
• Multi-purpose commits (mixing docs + feat + refactor). Split them.
• Force-pushing to a shared/base branch.
• Adding --no-verify to skip hooks.

Checklist before marking done

• Assignee set.
• Body has "What & Why" explainer.
• Title is Conventional Commit style.
• Atomic commits, each with a useful subject.
• PR URL reported back to the user.