/pr-workflow

name: pr-workflow
description: Complete workflow for submitting code changes — create branch, commit, open PR, check CI, fix failures, and merge.
license: AGPL-3.0
metadata:
  author: chorus
  version: "0.1.0"
  category: development

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

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` |

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

3. Stage and Commit

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

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

**Note**: Next.js paths need shell escaping:

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

Commit with HEREDOC for clean multi-line messages:

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

git push -u origin {branch-name}

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

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:

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:

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:

gh pr checks {pr-number}

7. Merge

Only when user explicitly requests. Default to squash merge:

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