collect-for-pr
Collect pending worktree commits into a PR for review. Use this skill when subdirectory worktrees have accumulated 4-7+ commits that should be batched together and submitted for review. Invoked with /collect-for-pr or automatically when monitoring worktree status.
When & Why to Use This Skill
The collect-for-pr skill is a specialized Git workflow automation tool designed to streamline the transition from local development to code review. It automates the process of gathering pending commits from multiple subdirectory worktrees, batching them into logical units, and creating structured GitHub Pull Requests. By integrating automated quality checks and consolidating CI/CD feedback, it significantly reduces the manual overhead of managing complex code submissions.
Use Cases
- Batching multiple function-level commits (typically 4-7) into a single, organized Pull Request to optimize reviewer time and CI resources.
- Automating the creation of standardized feature branches and GitHub PRs directly from a CLI-based development environment.
- Consolidating fragmented feedback from CI status reports, compiler errors, and reviewer comments into a single, actionable list of tasks.
- Enforcing pre-submission quality standards, such as formatting rules, naming conventions, and symbol updates, to ensure a high PR approval rate.
- Managing complex cherry-picking workflows across different subdirectories while automatically handling and reporting conflicts.
| name | collect-for-pr |
|---|---|
| description | Collect pending worktree commits into a PR for review. Use this skill when subdirectory worktrees have accumulated 4-7+ commits that should be batched together and submitted for review. Invoked with /collect-for-pr or automatically when monitoring worktree status. |
Collect Commits for PR
You are a coordinator agent that gathers matched function commits from subdirectory worktrees into PRs for review. Your job is to batch commits efficiently and create well-organized pull requests.
When to Use This Skill
Use /collect-for-pr when:
- Subdirectory worktrees have accumulated commits ready for review
- You want to batch 4-7+ commits into a single PR (flexible threshold)
- After a decomp session to collect completed work
Workflow
Step 1: Check Worktree Status
melee-agent worktree list --commits
This shows all subdirectory worktrees with their pending commits. Look for:
- Pending commits: How many commits are waiting on each worktree
- Total across worktrees: Whether there's enough work to batch
Automatic limits: The collect command now automatically limits PRs to 7 function match commits by default. Fix-up commits (build fixes, header updates, etc.) don't count toward this limit.
- Use
--max-functions Nto adjust the limit - Use
--no-limitto collect all pending commits - Deferred commits remain on worktree branches for the next PR
Step 2: Dry Run First
Always preview what will be collected. The --source-dir parameter is required:
melee-agent worktree collect --source-dir lb --dry-run
This shows:
- Which commits will be cherry-picked from that subdirectory
- Total commit count
Review the output for:
- Build fix commits that should go together with function matches
- Logical groupings within the subdirectory
Step 3: Collect and Create PR
If the dry run looks good, collect and create the PR:
melee-agent worktree collect --source-dir lb --create-pr
This will:
- Create a new branch from
upstream/master(namedbatch/lb-YYYYMMDD) - Cherry-pick pending commits from the specified subdirectory
- Push the branch to origin
- Create a GitHub PR with organized commit listing
- Reset pending commit counts in the database
Custom branch name (optional):
melee-agent worktree collect --source-dir lb --create-pr --branch "batch/lb-module-cleanup"
Step 4: Handle Conflicts
If cherry-picks fail:
- The command aborts the cherry-pick automatically
- Failed commits are listed with error details
- Successful commits are still collected
For failed commits:
- Note which subdirectories have conflicts
- The commits remain on their subdirectory branches
- They can be collected in a future PR after resolving
Step 5: Monitor PR and Fix Issues
After creating the PR, use the feedback command to monitor for issues:
# Get all PR feedback in one call
melee-agent pr feedback https://github.com/doldecomp/melee/pull/XXXX
# JSON output for automated processing
melee-agent pr feedback https://github.com/doldecomp/melee/pull/XXXX --json
This command consolidates:
- CI check status - Pass/fail with parsed error messages (compile errors, linker errors)
- Review comments - Both inline and PR-level comments from reviewers
- decomp-dev report - Regressions and improvements detected by the bot
- Action items - Generated list of what needs to be fixed
If issues are found:
- Fix the issues on the appropriate subdirectory worktree
- Push fix commits to the PR branch
- Re-run
melee-agent pr feedbackto verify fixes
Step 6: Post-PR Cleanup
After the PR is merged, clean up empty worktrees:
melee-agent worktree prune --dry-run # Preview
melee-agent worktree prune # Execute
Decision Framework
Should I Create a PR Now?
Each subdirectory worktree is collected separately. Consider each subdirectory independently:
| Situation | Recommendation |
|---|---|
| 5-7 function matches in a subdirectory | Yes, good batch size (default limit) |
| 8+ function matches | Run collect (it will auto-limit to 7, defer the rest) |
| 2-4 function matches but work has stopped | Yes, ship what's ready |
| 1-2 function matches with active work ongoing | Wait for more |
| Many fix-up commits | Include them - they don't count toward limit |
Note: The --max-functions limit only counts function match commits. Fix-up commits
(build fixes, header updates, signature changes) are always included and don't count.
PR Timing
- End of work session: Collect all completed work
- Before switching focus: Don't leave commits unbatched
- Module completion: When finishing a focused module push
- CI keeps up: Don't create multiple PRs faster than CI can process
What the Commands Do
worktree list
Shows all subdirectory worktrees with status:
- Commits pending (ahead of upstream/master)
- Lock status
- Last activity time
- Uncommitted changes (work in progress)
worktree collect --source-dir <subdir>
Cherry-picks commits from a specific subdirectory branch:
- Requires
--source-dirto specify which subdirectory to collect - Creates new branch from upstream/master (named
batch/<subdir>-YYYYMMDD) - Cherry-picks commits from that subdirectory
- Tracks success/failure per commit
- Optionally creates GitHub PR with
--create-pr
worktree prune
Removes worktrees with no pending commits:
- Only removes fully merged worktrees
- Use
--forceto remove with uncommitted changes - Use
--max-age Nto only prune old worktrees
pr feedback <url>
Gets all feedback on a PR in one call:
- CI check status with parsed build errors
- Review comments (inline and PR-level)
- decomp-dev bot regression reports
- Generated action items list
- Use
--jsonfor agent-friendly output
Example Session
# Check what's available
melee-agent worktree list --commits
# Output shows:
# lb: 6 commits (match, match, match, fixup, match, match)
# ft-chara-ftFox: 2 commits (match, fixup)
# gr: 2 commits (match, match)
# Preview collection for lb subdirectory
melee-agent worktree collect --source-dir lb --dry-run
# Shows commits from lb that will be cherry-picked
# Classifies each as [match] or [fixup]
# Create the PR for lb
melee-agent worktree collect --source-dir lb --create-pr
# Creates batch/lb-20241230 branch, cherry-picks commits, creates PR
# Returns PR URL: https://github.com/doldecomp/melee/pull/XXXX
# Monitor PR for issues
melee-agent pr feedback https://github.com/doldecomp/melee/pull/XXXX
# Shows CI status, review comments, decomp-dev report, action items
# If CI fails or reviewers request changes, fix and push
# Then re-check:
melee-agent pr feedback https://github.com/doldecomp/melee/pull/XXXX
# After PR merges, clean up
melee-agent worktree prune
PR Quality Checklist
IMPORTANT: Before creating a PR, you MUST review ALL commits in the batch against this checklist. These are common issues identified from doldecomp/melee PR reviews:
Automated Checks (ALL are errors that block commits)
Run melee-agent hook validate - ALL issues below will block the commit:
Use
true/falsenotTRUE/FALSE- Lowercase boolean literals are required
Float literals need F suffix
- Use
1.0Fnot1.0for f32 values
- Use
Hex literals use uppercase
- Use
0xABCDnot0xabcd
- Use
Don't use raw struct accesses/pointer arithmetic
- BAD:
*(s32*)((u8*)ptr + 0x10) - GOOD: Use
M2C_FIELD(ptr, 0x10, s32)or fill in actual struct fields
- BAD:
Don't add unnecessary extern declarations
- BAD:
extern UNK_T lbl_804D1234;at file top - GOOD: Include the proper header or create one
- BAD:
Don't rename descriptive symbols to address-based names
- BAD: Renaming
ItemStateTable_GShell→it_803F5BA8 - GOOD: Keep meaningful names
- BAD: Renaming
clang-format must pass
- Run
git clang-formatbefore committing
- Run
symbols.txt must be updated
- New functions need corresponding symbols.txt entries
No implicit function declarations
- All functions must have proper prototypes
Header signatures must match implementations
- No UNK_RET/UNK_PARAMS mismatches
No local scratch URLs in commits
- Commit messages must use production decomp.me URLs
- Run
melee-agent sync productionbefore committing to sync scratches - Local URLs like
nzxt-discord.local,10.200.0.1,localhost:8000will be rejected
Manual Review Required (not yet automated)
Use
boolreturn type for boolean functions- If a function returns 0/1 for false/true, use
boolnots32
- If a function returns 0/1 for false/true, use
Change argument/field types instead of casting
- BAD: Adding casts to work around type mismatches
- GOOD: Change the actual type in the struct or function signature
Keep temporary struct types instead of raw pointer arithmetic
- If m2c created a temp struct for field access, keep it
Don't modify unrelated files
- If a file shouldn't be in the PR (like
.gitkeep), revert it
- If a file shouldn't be in the PR (like
Don't mess with NonMatching/symbols.txt incorrectly
- Understand the matching/nonmatching workflow
Always use m2c first
- Don't try to one-shot decompile without using m2c
- m2c output should be the starting point, then cleaned up
Pre-PR Review Process
Before running melee-agent worktree collect --create-pr:
# 1. Run automated checks
melee-agent hook validate -v
# 2. Review each commit's diff for manual issues
git log upstream/master..HEAD --oneline # List commits
git show <hash> # Review each commit
# 3. Search for common issues
grep -r "TRUE\|FALSE" melee/src/ # Boolean literals
grep -rn "0x[0-9a-f]*[a-f]" melee/src/ # Lowercase hex
# 4. If issues found, fix them BEFORE creating PR
# Make fix commits on the subdirectory worktrees
What NOT to Do
- Don't create PRs with 1-2 commits unless work has completely stopped
- Don't skip the dry run on large batches
- Don't force-prune worktrees with uncommitted changes without checking first
- Don't create multiple overlapping PRs - wait for CI on previous PR
- Don't ignore cherry-pick failures - note them for future resolution
- Don't skip the quality checklist - reviewers will request changes
Troubleshooting
| Issue | Solution |
|---|---|
| Branch already exists | Use --branch to specify different name |
| Cherry-pick conflict | Commits stay on subdirectory branch for later |
| No pending commits | Nothing to collect - keep working |
| Push failed | Check git remote auth, push manually if needed |
| PR creation failed | Branch is ready, create PR manually via GitHub |
Integration with Other Skills
- After
/decomp: Commits accumulate on subdirectory worktrees - Before
/decomp-fixup: Check if fixes should go in same batch - Coordination: Each subdirectory is collected separately, avoiding cross-subdirectory conflicts