PR Workflow Skill

Degree of freedom: MIXED. Feedback judgment [HIGH freedom]; validations, poll loop, and merge-only-if-asked [LOW freedom — run exactly].

Full checklist for an already-committed branch or an open PR.

Uncommitted / staged / untracked working tree that still needs review, commit, and a merge-ready PR is `workflow-release-prep`. This skill does not own that sequence.

This skill vs neighbors

How to reason

1. Validate — repo commands green; no secrets in the branch
2. Open — template + complete description
3. Drive — poll checks; address every thread
4. Gate — mergeable_state clean AND threads 0; merge only if asked

Worked example

Validate: pnpm typecheck && pnpm test green; no .env in the diff. Open: PR uses the repo template; title fix(checkout): handle deleted SKU. Drive: CI red on lint → fix, push, re-poll; reply + resolve the bot thread. Gate: mergeable_state=clean, 0 threads; user did not ask to merge → report merge-ready and stop.

Self-critique before reporting

• Already committed — dirty tree was routed to workflow-release-prep
• Both gates — never treat mergeable: true as approval
• Merge gated — no merge unless the user explicitly asked
• Right owner — uncommitted pile → workflow-release-prep; keep-green loop after open → babysit

Invocation boundary

• Standalone: open or manage the PR. Merge only when the user explicitly

asked to merge.

• Called by `workflow-release-prep`: open the PR and return its URL.

babysit owns the green loop; the caller stops before merge.

Phase 1: Before Creating PR [LOW freedom — run exactly]

1. Run Validations

JavaScript/TypeScript:

pnpm typecheck && pnpm build && pnpm test
# or: npm run typecheck && npm run build && npm test

Python:

mypy . && python -m pytest && ruff check .

With Makefile:

make typecheck && make build && make test

2. Security Scan

Before committing, verify:

• [ ] No hardcoded paths (/Users/username/...)
• [ ] No secrets, API keys, or tokens
• [ ] No machine-specific values
• [ ] Environment variables for sensitive data

3. Create PR

1. Search for pull_request_template.md in repo
2. Use template structure for PR description
3. Create PR with clear title and description

Phase 2: Monitor PR [LOW freedom — run exactly]

4. Poll Status

Check every 60-90 seconds until checks complete:

Understanding Check Status:

• mergeable: true → Only means no git conflicts
• mergeable_state: "clean" → ALL checks passed, safe to merge

Mergeable State Values:

5. Address Bot Feedback

When reviews complete:

1. Read every comment - Track unresolved threads
2. For each issue:

• Analyze feedback
• Implement fix
• Commit and push
• Reply confirming fix
• Mark thread resolved

1. Address every comment — an unresolved thread fails Gate 2

6. Wait for Re-validation

After pushing fixes:

1. Poll status again
2. All checks must show SUCCESS
3. Re-fetch comments for NEW feedback
4. Repeat until clean

Phase 3: Merge Criteria [LOW freedom — run exactly]

7. Final Checklist

Two gates must pass:

Both must be TRUE to merge.

8. Execute Merge

Only after both gates pass and the user explicitly asked to merge:

gh pr merge --merge

Otherwise report that the PR is merge-ready and stop.

9. Verify Success

Confirm merge was successful and report status.

Error Handling

Common Mistakes

❌ Merging when mergeable_state is "unstable"

Fix: Always check mergeable_state, poll again if unstable

❌ Treating mergeable: true as approval

Fix: mergeable ≠ mergeable_state. Check the latter.

❌ Not re-checking comments after push

Fix: After every push, re-fetch comments for new threads

❌ Not marking threads resolved

Fix: After addressing each comment, mark thread resolved

Quick Reference

# Check PR status
gh pr status

# View checks
gh pr checks <number>

# View comments
gh pr view <number> --comments

# Merge (only when both gates pass)
gh pr merge <number> --merge