github-pr-workflow

name	github-pr-workflow
description	Code-delivery skill. Use only when the user explicitly asks for branch/commit/push/PR delivery workflow for finished code changes in this repo.
metadata	{"family":"code","owner":"engineering","last_reviewed":"2026-04-30T00:00:00.000Z","version":"1.0.0"}

GitHub PR Workflow

This is a code-generation family skill. It is only for shipping finished code work.

Strict Trigger Rule

Use this skill only if at least one is true:

1. the user explicitly asks to create/open/make a pull request
2. the user explicitly says to use this skill
3. the user explicitly says the feature is finished and wants it pushed as a PR

Do not use this skill automatically just because code changes exist.

Goal

Publish a finished feature to GitHub with a clean branch, commit, push, and PR workflow using:

• git
• gh

Remote currently expected in this repo:

• origin [e-mail]:Adrienenjalbert/flex-carrer-hub.git

Reviewability Priorities

Optimize for a reviewer who is checking AI-generated PRs and wants:

• one feature per PR
• minimal change scope
• easy-to-understand PR summaries
• as few review corrections as possible

These priorities override convenience.

Branch And PR Scope Rules

Branch Creation Rule

If the work is finished but there is no suitable feature branch yet, create one before committing or pushing.

Do not keep finished feature-delivery work on main or master.

Before creating or switching delivery branches, fetch the latest remote state for:

• develop
• the current source branch, when it has a remote branch
• main, only when origin/develop does not exist and must be created from latest origin/main

New delivery branches must start from up-to-date remote state, not stale local refs.

Branch Naming Rule

Preferred branch pattern:

• feature/<slug>
• fix/<slug>
• docs/<slug>
• refactor/<slug>
• chore/<slug>
• test/<slug>
• build/<slug>
• ci/<slug>
• deps/<slug>
• launch/week-<N>-<pillar> — reserved for the 8-week phased SEO launch. Follow the dedicated template at nextjs-app/docs/launch-plan/PR_TEMPLATE.md.

Choose the prefix that matches the actual delivery scope.

Use a short, reviewer-readable slug that describes one feature or one fix.

Examples:

• feature/paycheck-calculator-state-pages
• fix/canonical-city-role-metadata
• refactor/tool-registry-selectors

Do not create vague branch names like:

• feature/stuff
• fix/misc
• test/changes

One Feature Per PR

Mandatory rule:

• never combine multiple features in one PR

If the branch contains unrelated work, do not create the PR until scope is reduced or the user explicitly decides otherwise.

Base Branch Rule

Default base branch:

• develop

If develop does not exist on origin at PR creation time, create it from the latest origin/main before creating the PR.

Exception:

• if the current feature explicitly depends on another unfinished feature branch, and this feature directly derives from that branch, create the PR against that feature branch instead

Do not guess this dependency. Use a base other than develop only when:

1. the user explicitly says so, or
2. the branch relationship is explicit and necessary for stacked feature delivery

Zero-Conflict PR Rule

Mandatory rule:

• do not create a PR that GitHub would report as conflicting with its base branch

Before PR creation, update the source branch against the latest base branch and resolve conflicts locally. If conflicts occur and cannot be resolved cleanly, stop before PR creation and report the blocker.

Minimal Diff Rule

The PR should contain only the files needed for the finished feature.

Do not include:

• opportunistic refactors
• unrelated cleanup
• formatting-only churn outside touched files
• separate features bundled for convenience

Preconditions

Before creating a PR, confirm all are true:

1. the requested feature/change is finished
2. the user asked for delivery workflow explicitly
3. local changes are reviewed
4. appropriate verification has run, or skipped status is clearly stated
5. PR scope is limited to one feature

Required Sequence

1. Sync Remote Branches

Always sync before branch creation, commit finalization, push, and PR creation:

• git fetch origin develop
• git fetch origin <source-branch> when the source branch exists on origin

If develop does not exist on origin, create it from the latest origin/main:

• git fetch origin main
• git push origin refs/remotes/origin/main:refs/heads/develop
• git fetch origin develop

Do not create develop from a stale local main.

2. Review Working Tree

Check:

• git status --short
• git diff --stat
• git diff for changed files if needed

Goal:

• confirm only intended changes are included
• identify unrelated dirty files before committing
• verify the diff represents one feature only

3. Verify Changes

Use verification-checklist logic.

Default checks for code changes:

1. pnpm check
2. pnpm typecheck
3. pnpm build

Also run when relevant:

• pnpm smoke
• pnpm seo:audit

If checks are skipped or failing, say so explicitly before PR creation.

4. Review Branch State

Check:

• current branch name
• whether branch already has an upstream
• what the correct PR base branch should be
• that origin/develop and the source branch were fetched before creating any new branch
• that develop exists remotely, creating it from latest origin/main only if needed

Useful commands:

• git branch --show-current
• git status -sb
• git rev-parse --abbrev-ref --symbolic-full-name @{upstream} when useful

If the current branch is unsuitable for delivery, create a new correctly named branch before committing:

• git switch -c <type>/<slug> origin/develop

Suitability rules:

• not main
• not master
• not develop
• not a vague or unrelated branch name
• clearly scoped to one feature/fix

5. Commit Intentionally

Stage only intended files.

Use:

• git add <paths>
• git commit -m "<type>: <summary>"

Commit rules:

• keep the message specific to the finished feature
• prefer conventional-style prefixes such as feat:, fix:, refactor:, docs:, chore:
• do not amend old commits unless the user explicitly asks
• do not include unrelated changes

6. Reconcile With Base Branch

Before pushing or creating a PR:

1. fetch the latest base branch again
2. merge or rebase the delivery branch onto origin/<base-branch>
3. resolve any conflicts locally
4. rerun relevant verification after conflict resolution

Acceptable commands:

• git fetch origin <base-branch>
• git merge --no-edit origin/<base-branch>
• or git rebase origin/<base-branch> when the branch is not shared

If this step reports conflicts, do not create the PR until the conflicts are resolved and verification has been rerun.

7. Push Branch

Use:

• git push -u origin <branch> if upstream is missing
• otherwise git push

8. Create Pull Request With gh

Preferred flow:

• gh pr create --fill --base <base-branch> --head <branch>

If --fill is weak, provide explicit title/body:

• gh pr create --base <base-branch> --head <branch> --title "<title>" --body "<body>"

Base branch rule:

• use develop by default
• use another feature branch only for explicit stacked feature work

Before running gh pr create, confirm:

• develop exists on origin, creating it from latest origin/main if needed
• the delivery branch is reconciled with the latest origin/<base-branch>
• the PR is expected to have zero merge conflicts

PR Body Standard

Keep the PR body practical and short.

Include:

• the single feature delivered
• what changed
• why it changed
• verification run
• notable risks or follow-ups

Also include, when useful:

• explicit statement that the PR is intentionally limited to one feature
• explicit base branch choice if not develop

Suggested structure:

## Summary
- ...

## Verification
- `pnpm check`
- `pnpm typecheck`
- `pnpm build`

## Notes
- ...

Safety Rules

• Do not create a branch, commit, push, or PR without explicit user intent for delivery workflow.
• Do not combine multiple features in one PR.
• Do not target a base branch other than develop unless explicitly required by stacked feature work or the user says so.
• Do not create a delivery branch before fetching latest origin/develop and the source branch.
• Do not create a PR until the source branch is reconciled with the latest base branch and has zero expected merge conflicts.
• Do not commit unrelated dirty files.
• Do not use git add . blindly in a dirty tree.
• Do not force-push unless the user explicitly asks.
• Do not amend or rewrite history unless the user explicitly asks.
• Do not deliver from main, master, or develop.

Reviewer-Friendly PR Rules

• Prefer the smallest reviewable diff that completes the feature.
• Prefer explicit titles over clever titles.
• Prefer a short, factual PR body over long prose.
• Mention any intentionally excluded follow-up work so the reviewer knows the scope is controlled.
• If scope drift is detected, stop and split the work rather than bundling it.

Output Standard

When done, report:

1. branch name
2. branch creation status
3. base branch
4. commit created
5. push status
6. checks run
7. PR URL
8. confirmation that the PR targets develop unless an explicit stacked base was required
9. confirmation that the PR contains one feature only and is expected to have zero merge conflicts

If blocked, report the exact blocker:

• gh auth missing
• push failed
• checks failed
• working tree contains unrelated changes needing user direction
• branch contains multiple features and should be split before PR creation