pull-request

Disciplined Pull Requests

Use this workflow whenever creating or updating a pull request. Optimize for clarity, safety, reviewer efficiency, and repository hygiene over speed.

Every PR must be easy to understand from its title, description, commits, and diff alone.

Non-negotiable rules

• A PR represents exactly one coherent unit of work.
• Do not create broad, mixed-purpose, or miscellaneous PRs.
• Do not include unrelated changes, drive-by fixes, opportunistic refactors, or temporary/debug code.
• Do not create or update a PR from a dirty working tree.
• Do not create a PR from an incorrectly named or ambiguous branch.
• Do not create a PR if the branch includes unrelated commits.
• Never discard, overwrite, or hide user changes.
• Never use git reset --hard, git clean, git restore, forced branch deletion, force push, rebase, or merge unless explicitly approved.
• Never use --no-verify.
• Do not assume the default remote, default branch, current branch, source branch, or target branch is correct. Verify them.

Available helpers

• scripts/validate.py validates PR titles, source branch names, and source-to-target branch rules.
• references/checklist.md contains the required validation gates and the PR description template. Read it before creating or updating a PR.

Required preflight

Before PR work, inspect the repository state with the smallest safe commands:

git status --short
git branch --show-current
gh auth status

Then verify:

• current branch
• working tree status
• source branch
• target branch
• branch naming compliance
• commit history quality
• diff scope
• test, lint, and typecheck status where available

If any validation gate fails, do not create or update the PR until the issue is corrected or explicitly documented in the PR.

Branch and target rules

• Normal development PRs target develop.
• release/* and hotfix/* PRs may target main.
• feature/*, fix/*, chore/*, refactor/*, test/*, and docs/* branches must not target main unless explicitly approved.
• Source branches must be clear, lowercase, and intent-based.
• Do not create PRs from vague branch names such as updates, changes, work, misc, or stuff.

Validate branch targeting before creating the PR:

python3 scripts/validate.py branch feature/add-user-session-timeout develop
python3 scripts/validate.py branch hotfix/patch-token-expiry main

Diff and commit review

Before creating or updating a PR:

1. Inspect the commit list between target and source with explicit branch names.
2. Inspect the relevant diff between target and source.
3. Confirm commits are atomic, logically ordered, and understandable.
4. Confirm commit messages follow Conventional Commit standards.
5. Confirm the diff is focused, minimal, and reviewable.
6. Confirm tests for the change are included with the implementation when applicable.

Do not proceed if the branch contains WIP, squash-fix, typo-fix, noisy intermediate commits, unrelated commits, temporary code, secrets, local-only configuration, or large unexplained generated diffs.

If commit history is not clean, report that cleanup is needed before PR creation. Do not rebase, squash, reset, or force push unless the user explicitly approves the exact plan.

PR title rules

Prefer Conventional Commit-style titles:

<type>[optional scope]: <description>

Allowed types:

feat fix docs style refactor perf test build ci chore revert

Rules:

• concise, specific, and intent-based
• lowercase imperative phrasing except proper nouns
• 72 characters or fewer
• no trailing period
• no vague titles such as updates, changes, fixes, misc, or work

Validate the title before using it:

printf '%s\n' 'fix(api): reject empty tokens' | python3 scripts/validate.py title

PR description rules

Every PR description must include all sections from the template in references/pr_review_checklist.md:

• Summary
• Scope
• Validation
• Risk
• Review notes

The description must:

• explain why the change exists
• identify what is intentionally out of scope
• include tests, checks, or manual validation performed
• explicitly say why if no validation was performed
• call out risks, migrations, config changes, or breaking changes
• avoid empty placeholder sections

Creating a PR

Use explicit source and target branches:

gh pr create --base develop --head feature/add-user-session-timeout \
  --title "feat(auth): add session timeout" \
  --body-file /path/to/pr-body.md

For release or hotfix PRs targeting main:

gh pr create --base main --head release/1.4.0 \
  --title "chore(release): prepare 1.4.0" \
  --body-file /path/to/pr-body.md

Do not rely on interactive prompts for base, head, title, or body.

Updating a PR

Before editing an existing PR:

gh pr view <number> --json headRefName,baseRefName,state,title,body
git status --short

Validate the existing source and target branches before updates. Preserve useful review context; do not erase reviewer concerns, risk notes, or validation history unless replacing them with more accurate information.

Safety scan

Before PR creation or update, scan the reviewed diff for:

• secrets, credentials, tokens, private keys, and sensitive logs
• unrelated files or local-only configuration
• machine-specific paths
• large binaries or generated files
• commented-out code and temporary debugging code

If sensitive content is detected, stop and report the issue. Do not create or update the PR.

Final review question

Before creating or updating the PR, ask:

Would a reviewer understand the purpose, scope, risk, validation, and review
intent of this PR within two minutes?

If the answer is no, refine the PR title, description, commits, or branch contents before proceeding.