PR Workflow

Complete workflow for taking local code changes through branch creation, PR, CI verification, failure fix, and merge.

Prerequisites

• Code changes are already made and tested locally
• Remote origin is configured
• gh CLI is authenticated

Steps

1. Pre-flight Check

bash
git status
git diff --stat
git log --oneline -5

Verify before proceeding:

• Only intended files are modified
• No sensitive files (.env, credentials) staged
• No temp artifacts (screenshots, logs) left behind

2. Create Branch

Branch from current HEAD. Naming convention:

| Type | Prefix | Example | |------|--------|---------| | Bug fix | fix/ | fix/remove-legacy-textarea | | Feature | feat/ | feat/structured-ac-editor | | Refactor | refactor/ | refactor/service-layer | | Test | test/ | test/e2e-proposal-flow | | Docs | docs/ | docs/api-reference | | Chore | chore/ | chore/bump-deps |

bash
git checkout -b {prefix}{short-description}

3. Stage and Commit

Stage specific files only — never use git add . or git add -A:

bash
git add path/to/file1 path/to/file2

Note: Next.js paths need shell escaping:

bash
git add src/app/\(dashboard\)/projects/\[uuid\]/file.tsx

Commit with HEREDOC for clean multi-line messages:

bash
git commit -m "$(cat <<'EOF'
{type}: {concise description of why, not what}

{Optional body explaining context or trade-offs}

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
EOF
)"

4. Push and Open PR

bash
git push -u origin {branch-name}

bash
gh pr create --title "{type}: {title under 70 chars}" --body "$(cat <<'EOF'
## Summary
- Change 1
- Change 2

## Changed files
| File | Change |
|------|--------|
| `path/file.ts` | What changed |

## Test plan
- [x] Automated test passed
- [ ] Manual verification needed

Generated with [Claude Code](https://claude.com/claude-code)
EOF
)"

5. Check CI

bash
gh pr checks {pr-number}

• All pass — report to user, ready for merge
• Any fail — proceed to Step 6

6. Fix CI Failures

Get the failed logs:

bash
gh pr checks {pr-number}                          # find failed run ID
gh run view {run-id} --log-failed 2>&1 | tail -80  # read failure details

Common failure types and fixes:

| Failure | Local repro | Fix | |---------|------------|-----| | Test assertion | npx vitest run path/to/test.ts | Update test expectations to match new behavior | | Type error | npx tsc --noEmit | Fix types; check only your errors with \| grep {keyword} | | Lint error | pnpm lint | Auto-fix or manual fix | | Missing test update | grep -r "changedField" src/**/__tests__/ | Update test fixtures/helpers using the old field |

After fixing:

bash
git add {fixed-files}
git commit -m "$(cat <<'EOF'
fix: {what was fixed in tests/types}

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
EOF
)"
git push

Re-check CI — repeat until green:

bash
gh pr checks {pr-number}

7. Merge

Only when user explicitly requests. Default to squash merge:

bash
gh pr merge {pr-number} --squash --delete-branch
git checkout main && git pull

Checklist

Before opening PR:

• ] npx tsc --noEmit passes (or no new errors)
• ] Related tests pass locally
• ] No screenshots, temp files, or debug logs in working tree
• ] Grep test files for any changed field/function names

Before merging:

• ] CI is green
• ] User has approved the merge