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

• 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

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

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

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)

12. Use

    bool

    return type for boolean functions
    • If a function returns 0/1 for false/true, use

      bool

      not

      s32

13. 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

14. Keep temporary struct types instead of raw pointer arithmetic

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

15. Don't modify unrelated files

    • If a file shouldn't be in the PR (like

      .gitkeep

      ), revert it

16. Don't mess with NonMatching/symbols.txt incorrectly

    • Understand the matching/nonmatching workflow

17. 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

--branch

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