MelvinBot (Melvin) is Expensify's AI agent for App GitHub issues. On many open-source jobs, Melvin posts the first proposal automatically. This guide explains how contributors, Contributor+ (C+), and internal engineers work together on those issues.
Clearly documenting the process helps us move efficiently by preventing all of us from wasting time on incorrect solutions. Internal engineering approval is required on Melvinbot proposals because we usually have the most context to know whether a solution aligns with our best practices.
For general contributor workflow (proposals, payment, PR standards), see CONTRIBUTING.md. For C+ responsibilities, see HOW_TO_BECOME_A_CONTRIBUTOR_PLUS.md.
| Role | Responsibility on Melvin issues |
|---|---|
| MelvinBot | Posts the first proposal on the issue. Implements the accepted solution when asked. Opens a draft PR with MelvinBot as the GitHub author. |
| Contributor | May submit their own proposal if they have a meaningfully different approach. Must not open a PR until a proposal is accepted and they are hired on the job. |
| Contributor+ (C+) | Reviews proposals (Melvin's and any contributor proposals) using the same standards as any other job. Recommends acceptance to the CME. After the CME approves, asks Melvin to implement, then owns the PR as the human author before sending it for final review. |
| Contributor Manager Engineer (CME) | Reviews and approves proposals (same as any other App job). After implementation, reviews and merges the PR. |
Only Expensify employees, C+ members, and backend contributors can trigger Melvin with @MelvinBot comments on GitHub.
Issue opened → Melvin posts proposal → C+ reviews proposal(s)
→ C+ recommends acceptance (🎀👀🎀) → CME approves proposal
→ C+ asks Melvin to implement (only after CME approval)
→ Not accepted: C+ or CME explains why
→ Melvin opens draft PR → C+ tweaks, tests, posts PR body/checklist in a PR comment, asks Melvin to apply it, self-reviews (including Reviewer checklist)
→ C+ submits PR for review as human author → CME reviews and merges (PR body and/or C+ PR comment)
Follow the same proposal review process as any other App job, but remember to review the MelvinBot proposal first, and then review in first-come-first-serve review order for proposals posted after the Help Wanted is applied (see CONTRIBUTING.md).
- Use the proposal template criteria: clear root cause, concrete solution, no code diffs.
- C+ reviews Melvin's proposal with the same rigor as a contributor proposal. Do not approve proposals that lack a satisfying root-cause explanation.
- Contributors may still post proposals if they have a meaningfully different approach (see CONTRIBUTING.md).
- No one opens a pull request until a proposal is accepted by the CME (same as any other App job; see CONTRIBUTING.md).
- If Melvin's proposal is not acceptable, the C+ can review proposals from other contributors, or iterate with Melvin by tagging
@MelvinBoton the issue, explaining the needed changes, and asking it to update its proposal or post a new one until it is satisfactory.
The C+ reviews Melvin's proposal with the same rigor as a contributor proposal. Follow the proposal template review instructions.
When the C+ is satisfied with Melvin's proposal, they recommend it to the CME by posting 🎀👀🎀 on the issue. That triggers CME assignment for the job.
Once the assigned CME has approved Melvin's proposal (the same acceptance step as for any contributor proposal), the C+ comments on the issue asking Melvin to implement. Include a link to the specific proposal comment so Melvin implements the latest version (Melvin may post a new proposal when asked to update). For example:
@MelvinBot please implement your proposal at https://github.com/Expensify/App/issues/12345#issuecomment-6789012345
Adjust the wording if needed, but the comment must mention @MelvinBot, link to the proposal comment, and clearly request implementation.
Melvin opens a draft PR linked to the issue. MelvinBot remains the GitHub author but the C+ is the human author. Most C+ members will not be able to edit the PR description directly (GitHub only allows the author or users with write access to edit a pull request body).
Before requesting final review, the assigned C+ must:
- Manually tweak the PR if Melvin's implementation needs corrections. Comment on the pull request, tag
@MelvinBot, and explain the needed changes so Melvin can update the code. - Test the change on all required platforms (see CONTRIBUTING.md).
- Complete every step in the PR Author Checklist (see Updating the PR description and checklist below). Screenshots and videos may live only in the Reviewer Checklist section of your PR comment; you do not need to duplicate them in the Author Checklist.
- Self-review the code against PR Review Guidelines, PR Authoring & Reviewing Best Practices, and complete the Reviewer Checklist as part of that self-review.
The C+ is accountable for the PR quality, the same as any contributor who authored a PR.
C+ members who cannot edit the PR body directly should use this workaround:
- On the pull request, post a comment with the exact content you want in the PR description. Put the full body inside a
<details>block so the PR thread stays readable. Include the complete PR template when possible: Explanation of Change, Fixed Issues, Tests, Offline tests, QA Steps, a fully checked PR Author Checklist, and Screenshots/Videos sections as needed. - In the same comment, ask Melvin to copy that content into the pull request body, for example:
@MelvinBot please set the PR body to the content in the details section above
To update only the checklist, etc, post the section in a <details> block and ask Melvin to set just that portion of the PR body.
- Confirm Melvin updated the PR description before marking the pull request ready for review.
The C+ PR comment is the source of truth for what was tested and checked. CMEs may review that comment directly when the PR body is incomplete, out of date, or hard to verify.
After the C+ submits the PR for review:
- A CME (internal engineer) is assigned to review and merge.
- The CME follows the normal internal review process. Review the PR body when Melvin has applied the C+ content, or failing that, review the C+ PR comment (with the
<details>block) directly for testing steps and checklist completion. - Payment and regression checklists follow the standard rules in CONTRIBUTING.md.
We intentionally do not add a second round of contributor or C+ PR review on top of the CME review. Prior discussions did not surface a problem that extra review would solve, and an additional review step would add cost and delay without clear benefit. The C+ self-review before submission, combined with CME review, is the intended quality gate.
- CONTRIBUTING.md — full contributor workflow
- PROPOSAL_TEMPLATE.md — proposal format and C+ review instructions
- Reviewer Checklist — C+ completes this during self-review before submitting for CME review
- AI Etiquette — accountability for AI-assisted work
- AI Reviewer philosophy — automated PR feedback vs human review