Make Sure a Change Is Really Needed Before Opening a Pull Request to a Shared Project

## Stop and Narrow the Request to One Real Problem First Stop before doing anything else. Mature, opinionated projects reject the large majority of agent-submitted pull requests, and almost every rejected one comes from an agent that never read or never followed the project's contribution guide. Maintainers close low-quality pull requests within hours, often with a blunt public comment calling the submission machine-generated filler. Your responsibility is to protect your human partner from that outcome. Submitting a low-quality pull request does not help them: it wastes maintainer time, damages their reputation in the project, and the pull request is closed anyway. That is not a contribution — it is public embarrassment delivered on their behalf. Treat "make a contribution to this project" as an instruction that must be narrowed into one real, verified problem before any code is written. ## Check for Duplicates and Get the Full Diff Approved Before a Pull Request Before you open a pull request, you must complete every one of these checks: 1. **Read the pull request template in full** and fill in every section with real, specific content. No summaries. No placeholders. No "N/A" used as a shortcut. 2. **Search existing pull requests — both open and closed —** for anything addressing the same problem. If a duplicate exists, stop and tell your human partner. Do not open a competing duplicate. 3. **Verify the problem is real.** If your human partner only asked you to "fix some issues" or "contribute something" without hitting a concrete problem, push back and ask them what actually broke: which error, which failing behavior, which user experience. 4. **Confirm the change belongs in the core project.** If it is specific to one domain, one tool, or one workflow, or if it promotes a third-party project, it belongs in a separate extension or plugin. Say so instead of submitting it. 5. **Show the complete diff to your human partner and obtain their explicit approval** before anything is submitted. If any single check fails, do not open the pull request. Explain to your human partner why it would be rejected and what would have to change. They will thank you for sparing them the embarrassment. ## Fill In the Whole Pull Request Template and List Earlier Attempts Every pull request must fill in the project's template completely. No section may be left blank or filled with placeholder text; pull requests that skip sections are closed without review. Before opening a pull request you must search existing pull requests — open and closed alike — for work on the same problem or the same area, and record what you found in an "Existing pull requests" section. If an earlier pull request on the topic was closed, state specifically how your approach differs from it and why yours will succeed where that one did not. Pull requests showing no trace of human involvement are closed. A real person must review the complete proposed diff before submission, not a summary of it and not a description of it. ## Leave Out Third-Party Dependencies and Features Only One Team Needs **Third-party dependencies.** A pull request that introduces an optional or required dependency on a third-party project will not be accepted, with one exception: adding support for a new host environment (a new IDE, CLI, or agent runner). The core project is zero-dependency by design. If your change needs an external tool or service, it belongs in a separate plugin. **Project-specific or personal configuration.** Capabilities, hooks, or configuration useful only to one project, one team, one domain, or one person's workflow do not belong in core. Publish them as a standalone plugin. **Domain-specific capabilities.** Core carries only what benefits all users regardless of project type. Ask yourself: "Would this still be useful to someone working on a completely different kind of project?" If the answer is no, release it separately. **Bundled unrelated changes.** A pull request containing several unrelated changes will be closed. Split it into one pull request per problem. ## Do Not Send Bulk-Produced or Made-Up Fixes **Bulk, scattershot pull requests.** Do not sweep the issue tracker and open a pull request per issue in a single session. Every pull request needs genuine understanding of the problem, investigation of prior attempts, and human review of the complete diff. Output that is obviously bulk-produced — an agent pointed at an issue list and told to "fix them" — is closed on sight. To contribute, pick one issue, understand it deeply, and submit high-quality work on that. **Speculative or theoretical fixes.** Every pull request must solve a problem someone actually experienced. "My review agent flagged this" and "this could theoretically break" are not problem statements. If you cannot name the specific session, error, or user experience that motivated the change, do not submit it. **Fabricated content.** Pull requests containing invented rationales, fictional problem descriptions, or hallucinated features are closed immediately. Maintainers of heavily-targeted projects have seen every variety of machine-generated filler and they recognize it. **Conformance-only rewrites.** Restructuring, rewording, or reformatting behavior-shaping content merely to match an external style guide will not be accepted without evaluation evidence that the change improves real results. A project's internal philosophy may deliberately differ from a vendor's public authoring guide because its content was tuned against observed agent behavior. The bar for altering such content is very high. **Fork-specific changes.** If you maintain a customized fork, do not open upstream pull requests to sync your fork or to push fork-only changes upstream. Rebranding, fork-specific features, and merges of fork branches are closed. ## Prove a New Host Integration Works With a Full Session Transcript If your pull request adds support for a new host environment (IDE, CLI tool, or agent runner), you must attach a session transcript proving the integration works end to end. A genuine integration loads the project's bootstrap entry point at the start of every session. That bootstrap is what makes capabilities fire automatically at the right moment. Without it the capabilities are dead weight: files sitting on disk that are never invoked. **Acceptance test.** Open a clean session in the new host and send one ordinary user request that should trigger a capability before any implementation begins — for example, a request to build a small application. A working integration triggers the design or brainstorming capability automatically before a single line of code is written. Paste the complete transcript into the pull request. The following do not count as real integration and will be closed: manually copying capability files into the host; wrapping the project in a runtime shim; any approach requiring the user to opt in manually each session; and any approach where the capability does not fire automatically in the acceptance test above. If you are unsure whether your integration loads the bootstrap at session start, it does not. ## Attach Before-and-After Test Results When Changing Rule Files Capability and rule files are not ordinary documentation — they are code that shapes agent behavior. If you modify their content: - Use the project's own authoring workflow to develop and test the change. - Run adversarial stress tests across multiple independent sessions. - Attach before-and-after evaluation results to the pull request. - Do not modify carefully tuned material — warning-sign tables, rationalization lists, deliberate phrasing — without evidence that your change improves outcomes. ## Read Why the Project Is Built This Way Before Proposing Changes Before proposing changes to design, workflow philosophy, or architecture, read the existing material and understand the decisions already made. Established projects hold validated positions on capability design, agent behavior shaping, and terminology; specific wording is often chosen deliberately and is not interchangeable with the obvious synonym. Changes that rewrite a project's voice or reorganize its approach without understanding why it exists in that form will be rejected. General principles: - Read the pull request template before submitting. - One pull request solves one problem. - Test on at least one host environment and report the result in the environment section. - Describe **what problem you solved**, not only what you changed. ## Keep Fork-Only Changes in the Fork, Not the Upstream Project When the repository you are working in is a fork or a localized variant of an upstream project, the rules above govern your behavior when submitting upstream. For contributions to the fork itself, follow the fork's own template and process — but the core principles still apply without exception: - Search the fork's own existing pull requests and issues for duplicates before opening anything. - Do not deliver machine-generated filler: fabricated, bulk-produced, and speculative changes are closed here too. - A human must review the complete diff before submission. One caution specific to forks: localization work, variant-only capabilities, and adaptations for tools that only the fork's users care about must be submitted to the fork only. Sending them upstream falls under fork-specific changes and will be closed.