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 N to adjust the limit
• •Use --no-limit to 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:

1. •Create a new branch from upstream/master (named batch/lb-YYYYMMDD)
2. •Cherry-pick pending commits from the specified subdirectory
3. •Push the branch to origin
4. •Create a GitHub PR with organized commit listing
5. •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:

1. •Note which subdirectories have conflicts
2. •The commits remain on their subdirectory branches
3. •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:

1. •Fix the issues on the appropriate subdirectory worktree
2. •Push fix commits to the PR branch
3. •Re-run melee-agent pr feedback to 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:

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-dir to 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 --force to remove with uncommitted changes
• •Use --max-age N to 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 --json for 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:

1. •

   Use true/false not TRUE/FALSE

   • •Lowercase boolean literals are required
2. •

   Float literals need F suffix

   • •Use 1.0F not 1.0 for f32 values
3. •

   Hex literals use uppercase

   • •Use 0xABCD not 0xabcd
4. •

   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
5. •

   Don't add unnecessary extern declarations

   • •BAD: extern UNK_T lbl_804D1234; at file top
   • •GOOD: Include the proper header or create one
6. •

   Don't rename descriptive symbols to address-based names

   • •BAD: Renaming ItemStateTable_GShell → it_803F5BA8
   • •GOOD: Keep meaningful names
7. •

   clang-format must pass

   • •Run git clang-format before committing
8. •

   symbols.txt must be updated

   • •New functions need corresponding symbols.txt entries
9. •

   No implicit function declarations

   • •All functions must have proper prototypes
10. •

    Header signatures must match implementations

    • •No UNK_RET/UNK_PARAMS mismatches
11. •

    No local scratch URLs in commits

    • •Commit messages must use production decomp.me URLs
    • •Run melee-agent sync production before committing to sync scratches
    • •Local URLs like nzxt-discord.local, 10.200.0.1, localhost:8000 will be rejected

Manual Review Required (not yet automated)

1. •

   Use bool return type for boolean functions

   • •If a function returns 0/1 for false/true, use bool not s32
2. •

   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
3. •

   Keep temporary struct types instead of raw pointer arithmetic

   • •If m2c created a temp struct for field access, keep it
4. •

   Don't modify unrelated files

   • •If a file shouldn't be in the PR (like .gitkeep), revert it
5. •

   Don't mess with NonMatching/symbols.txt incorrectly

   • •Understand the matching/nonmatching workflow
6. •

   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

1. •Don't create PRs with 1-2 commits unless work has completely stopped
2. •Don't skip the dry run on large batches
3. •Don't force-prune worktrees with uncommitted changes without checking first
4. •Don't create multiple overlapping PRs - wait for CI on previous PR
5. •Don't ignore cherry-pick failures - note them for future resolution
6. •Don't skip the quality checklist - reviewers will request changes

Troubleshooting

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