gh-pr-writing

name	gh-pr-writing
description	Write and update GitHub PR titles and PR bodies with repository templates and local conventions. Use when creating PRs with `gh pr create`, revising PR text, choosing a conventional title prefix (for example `feat(web):`), or ensuring ticket suffix rules.

GH PR Writing

Workflow

1. Inspect changed files (git show --name-only --oneline HEAD or git diff --name-only).
2. Choose title type and scope from the mapping below.
3. Build title in Conventional Commit PR style.
4. Run bun run format manually before commit/push to avoid push-time formatter diffs.
5. Load PR template from .github/pull_request_template.md when present.
6. Fill the template with concrete user-facing behavior, implementation details, and executed validation commands.
7. Create or update the PR using gh pr create or gh pr edit.

Title Rules

• Format: <type>(<scope>): <summary>.
• Keep summary imperative and specific.
• Do not omit scope unless scope is truly cross-cutting.
• If user requires a ticket marker at the end, append exactly as requested (for example ... WOR-2610).

Type And Scope Mapping

See the following example:

• feat(web): for user-visible frontend behavior in apps/dashboard, packages/ui, routing/UI/UX changes.
• fix(web): for frontend bug fixes.
• feat(server): for backend/API behavior changes in packages/server.
• fix(server): for backend/API bug fixes.
• feat(db): or fix(db): for schema/query/migration behavior in packages/db.
• chore(repo): for tooling/config/lockfile/CI/repo maintenance.
• refactor(<scope>): for structural code changes without behavior change.
• test(<scope>): for test-only changes.
• docs(<scope>): for documentation-only changes.
• ...

When multiple scopes are touched, choose the dominant user impact scope.

PR Body Rules

• Use the repository PR template verbatim section structure when it exists.
• Prefer concrete, observable outcomes over abstract summaries.
• Include exact command lines used for validation.
• Explicitly note excluded items (for example: "README unchanged") when relevant.

Commands

# Inspect latest commit

git show --name-only --oneline HEAD

# Format before push

bun run format

# Create PR from template body file

gh pr create --base main --head <branch> --title "<title>" --body-file <body.md>

# Update title/body later

gh pr edit <pr-number-or-url> --title "<title>" --body-file <body.md>