Update PR

Important

• NEVER push to main. Never checkout main. Never modify main. Only push the current feature branch. If on main, stop immediately.
• NEVER force push. If a push is rejected after rebase, tell the user to run the force push manually outside Claude Code (supply-chain-guard blocks it).
• Auto-commit is the default. If there are uncommitted changes, commit them automatically. Do not ask, do not stop.
• Commits use Co-Authored-By — PR descriptions do NOT.

Instructions

Step 1: Validate Branch

1. Run git branch --show-current.
2. If the branch is main or master, STOP. Tell the user: "You're on main. Check out a feature branch first."

Step 2: Refresh Project Docs

1. Run git diff origin/main...HEAD --name-only and git diff --name-only to understand all changes in this branch + uncommitted work.
2. Check which of these files exist at the project root: CLAUDE.md, TASKS.md, SESSION.md, ARCHITECTURE.md.
3. For each file that exists, read it and update based on what changed:
   • CLAUDE.md: Add new patterns, dependencies, or workflow notes introduced this branch. Remove stale instructions that no longer apply.
   • TASKS.md: Mark completed tasks as done. Add any new tasks discovered during the session.
   • SESSION.md: Overwrite with a concise summary of what was done this session (what changed, decisions made, blockers hit).
   • ARCHITECTURE.md: Update only if structural changes were made (new modules, changed data flow, new integrations).
4. Skip any file where nothing meaningful changed. Don't touch files that don't exist — never create them.

Step 3: Auto-Commit

1. Run git status --short.
2. If the working tree is clean (no output), skip to Step 4 (Rebase).
3. If there are changes: a. Review the list of changed/untracked files. Skip any that look like secrets (.env, *.pem, credentials, tokens). b. Stage relevant files by name — do NOT use git add -A or git add .. c. Read the staged diff to understand what changed. d. Generate a concise commit message (imperative mood, focused on why not what). e. Commit with the Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> trailer. f. Report: "Committed: <message> (<N> files)"

Step 4: Rebase on Main

1. Run git fetch origin main.
2. Run git rebase origin/main.
3. If conflicts occur, STOP. List conflicting files. Tell the user to resolve (git rebase --continue or git rebase --abort).

Step 5: Push to Remote

1. Run git push -u origin <branch-name>.
2. If rejected (non-fast-forward — typical after rebasing a previously-pushed branch):
   • Do NOT attempt force push.
   • Tell the user: "Push rejected — rebase rewrote history. Run this manually: git push --force-with-lease origin <branch>"
   • STOP.

Step 6: Gather Context

Run these in parallel:

1. git log origin/main..HEAD --format="%h %s" --reverse — commit list since branching.
2. git diff origin/main...HEAD --stat — file-level diffstat.
3. git log origin/main..HEAD --format="%b" --reverse — commit bodies for detail.
4. gh pr view --json number,title,url,state 2>/dev/null — check for existing open PR.

Analyze the commits to understand the overall change.

Step 7a: Update Existing PR

If gh pr view found an open PR:

1. Generate an updated title (under 70 characters) reflecting ALL commits, not just the latest.
2. Generate a PR body using the format below. Incorporate the argument context if provided.
3. Run gh pr edit <number> --title "<title>" --body "$(cat <<'EOF' ... EOF)".
4. Report: "PR #N updated: <url>"

Step 7b: Create New PR

If no open PR exists for this branch:

1. Generate a title (under 70 characters) from the full commit history.
2. Generate a body using the format below. Incorporate the argument context if provided.
3. Run gh pr create --base main --title "<title>" --body "$(cat <<'EOF' ... EOF)".
4. Report: "PR created: <url>"

PR Description Format

## What & Why

<1-3 sentences: what changed and why it matters. Lead with impact, not implementation.>

## Changes

- <structural change 1 — what component/layer was affected>
- <structural change 2>

## Blast Radius

- <what systems/workflows this touches>
- <downstream effects or dependencies affected>

## Test Plan

- [ ] <concrete verification step>

Rules for the PR body

• What & Why: One breath. No "This PR..." openers.
• Changes: Structural, not per-commit. Group related commits logically.
• Blast Radius: Think like an operator. What could break?
• Test Plan: Actionable. Not "it works."
• No "Generated by Claude" or "Co-Authored-By" lines in PR descriptions.

Error Handling

1. On main/master: Stop. Tell user to create a feature branch.
2. Rebase conflicts: Stop. List files. Provide resolve/abort commands.
3. Push rejected: Stop. Provide manual force-push command.
4. gh not authenticated: Tell user to run gh auth login.
5. No commits ahead of main: Tell user branch is up to date with main, nothing to PR.
6. PR already merged/closed: Tell user. Offer to create a new PR if there are new commits.