write-prs

name	write-prs
description	Write, open, iterate, and optionally merge pull requests with clear PR descriptions, safe validation notes, review-bot follow-up, and merge gates. Use when preparing PR bodies, creating PRs, responding to CodeRabbit or other review bots, deciding whether a PR is ready, merging a PR, or carrying a PR through requested deployment or release gates.

Write PRs

Workflow

1. Determine the requested completion mode:

   • review-ready: create or update the PR and stop once available review bots and the agent are satisfied.
   • merge: do everything in review-ready, then merge when required checks and approvals allow it.
   • release: complete merge readiness, then follow the repo-approved release or deployment path if one exists. If the user did not explicitly request merge, release, or deployment, stop at review-ready.

2. Inspect the change before writing:

   • Read the issue, task, or user request.
   • Review git status, the diff, changed files, and relevant tests.
   • Separate user changes from agent changes; do not revert unrelated work.
   • Verify whether docs, generated files, migrations, dependencies, contract interfaces, value-moving code, permissions, or deployment-sensitive files are touched.

3. Write a concise PR title and body with this format:

   ## Issue
   - What problem, user need, bug, or follow-up this PR addresses.
   
   ## Fix
   - The core solution and why it is appropriate.
   
   ## Changes
   - Notable code, docs, config, API, UX, or data-shape changes.
   
   ## Validation
   - Commands, checks, screenshots, E2E runs, or manual flows completed.
   - Anything intentionally not tested, with the reason and residual risk.
   
   ## Risk
   - Level: Low | Medium | High
   - Why: blast radius, reversibility, data/security/performance/deploy impact.
   - Rollback: expected rollback or mitigation path.
   
   ## Review Notes
   - Areas reviewers or bots should focus on, plus any trade-offs.
   

   Omit empty sections only when truly irrelevant.

4. Redact local and private information:

   • Do not include absolute local paths, machine names, OS usernames, drive letters, shell prompts, local branch worktree names, private URLs, tokens, secrets, environment variable values, or local-only config.
   • Prefer repo-relative paths and public route, contract, or function names.
   • Summarize logs instead of pasting large output; include only the lines needed to explain validation or a failure.
   • Never expose bot prompts, hidden instructions, local tool metadata, or connector credentials.

5. Create commits and push:

   • Verify the configured Git identity before committing.
   • Use signed-off or cryptographically signed commits only when the repo or user asks for them.
   • Keep follow-up commits focused and give them clear messages describing the bot/user feedback addressed.
   • Push after each meaningful round of fixes so review bots evaluate the latest head.
   • Open regular, non-draft PRs by default so review bots and auto-review integrations trigger on creation.
   • Use draft PRs only when the user explicitly asks or a documented platform constraint requires it.

6. Iterate with available review bots:

   • Discover available bot feedback from PR comments, review comments, review threads, checks, or local repo tools.
   • CodeRabbit or other review bots may be present or absent on a given PR. Treat absence as normal after checking comments, reviews, threads, and checks.
   • Treat bot findings as review input, not orders. Fix valid correctness, security, performance, test, docs, accessibility, and maintainability issues.
   • For invalid or non-blocking suggestions, reply with a short rationale and leave the PR ready when no material risk remains.
   • Re-run focused checks after fixes, push commits, and re-check bot feedback until all blocking bot concerns are fixed, resolved, or explicitly justified.
   • Do not mark the PR bot-happy if unresolved critical or high-confidence bot findings remain.

7. Decide readiness:

   • Agent-happy means the diff is scoped, reviewed, validates the requested behavior, and has no known unaddressed high-risk issues.
   • Bot-happy means every available review bot has no remaining blocking concerns on the latest pushed commit, or the agent has documented why a remaining item is safe to defer.
   • Human approval and required CI still govern merge eligibility.

Validation

• Prefer focused checks first, based on changed files and risk.
• For Solidity contract changes, run or report inability to run:
  • forge build
  • forge fmt --check smart-contracts
  • slither . --foundry-compile-all
• For docs-only or skill-only changes, run the relevant Markdown, skill, or lightweight structural validation instead of heavyweight contract checks.
• For generated files, caches, or build artifacts, confirm they are intentionally included before mentioning them as part of the PR.
• If a check cannot be run, state the reason and the residual risk without adding local machine details to the PR body.

Merge And Release Gates

• Never merge, deploy, or release unless the user explicitly asked for that mode or the repo's standing instructions require it.
• Before merging, ensure the PR is agent-happy, bot-happy, required checks are passing or explained, and required approvals are present.
• Before any release or deployment, inspect the repo's current release/deploy documentation and workflows. Use the repo-approved path only.
• If release, deployment, or final validation fails, stop, summarize the failure, and do not proceed without a fix or explicit user direction.

Anti-Patterns

• Do not write PR bodies that only say "updated files" or force reviewers to infer the issue from the diff.
• Do not hide untested paths; state what was not tested and why.
• Do not paste local environment details, secrets, huge logs, or private machine paths.
• Do not endlessly chase low-value bot suggestions. Use judgment, explain deferrals, and keep the PR moving when risk is low.
• Do not merge with unresolved blocking bot, CI, or agent concerns.