write-prs - SKILL.md Agent Skill

name: write-prs description: Write, open, iterate, and prepare pull requests for merge or deployment with clear PR descriptions, safe validation notes, review-bot follow-up, signed commits, readiness gates, and deployment handoff notes. Use when preparing PR bodies, creating PRs, responding to CodeRabbit or Claude review bots, deciding whether a PR is ready, or preparing a PR for merge, staging, or production rollout; use deploy-6529 for actual deployment execution.

Write PRs

Workflow

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 hand off to ops/skills/deploy-6529/SKILL.md for merge execution when required checks and approvals allow it.
- staging: prepare the release notes and hand off to ops/skills/deploy-6529/SKILL.md for merge, staging deployment, and E2E or smoke validation.
- prod: prepare the release notes and hand off to ops/skills/deploy-6529/SKILL.md for staging verification, production deployment, and production E2E or smoke validation. If the user did not explicitly request merge or deployment, stop at review-ready.
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, routes, dependencies, auth, payments, analytics, or deployment-sensitive code are touched.

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. Add screenshots or short videos for visual UI changes when available.

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 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.
Create commits and push:
- Verify the configured Git identity before committing.
- In this repo, use signed commits: git commit -s ....
- 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.
- After the initial PR push, keep the agent/thread open until every tracked bot or status check triggered for that head commit reaches a terminal state.
Iterate with available review bots:
- Discover available bot feedback from PR comments, review comments, review threads, checks, or local repo tools.
- In this repo, CodeRabbit and Claude can both appear as PR review bots, but either one may be absent on a given PR. Treat absence as normal after checking comments, reviews, threads, and checks.
- Recognize bot authors or display names that include CodeRabbit, coderabbitai[bot], Claude, or claude[bot].
- Track repo PR review bots and status checks by exact check name when present:
  - Code scanning results / CodeQL
  - CodeQL / Analyze (actions) (dynamic)
  - CodeQL / Analyze (javascript-typescript) (dynamic)
  - CodeQL / Analyze (python) (dynamic)
  - CodeRabbit
  - DCO
  - security/snyk (6529)
  - SonarCloud Code Analysis
- For each tracked bot or status check, verify the latest pushed commit, capture the current state, and inspect any failure, skipped review, alert, or warning details before deciding readiness.
- After every follow-up commit, repeat the wait: keep the agent/thread open until all tracked bots and checks for the new head commit are done, including success, failure, skipped, or cancelled states.
- Review every new bot comment or finding and make an explicit fix-or-defer decision. The default is to address it; defer only when the comment is wrong, inapplicable, duplicative, or lower value than the churn it would create, and document the rationale.
- For local CodeRabbit review in this repo, use 6529 run cr or the quality:cr scripts when they fit the change scope.
- 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 signed 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/high-confidence bot findings remain.
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 repo checks first, such as 6529 run lint:changed, 6529 run typecheck:changed, 6529 run check:changed, or targeted 6529 run test -- <pattern>.
Use 6529 run build for build-time, generated API model, Next.js config, route, or deployment-sensitive changes.
Use 6529 run test:e2e for local Playwright E2E when relevant; this repo's default Playwright config starts the app locally on port 3001.
For staging or production validation, inspect the repo's current deploy and E2E configuration before running. If no target-specific E2E command exists, run the strongest available smoke checks and report the gap clearly.

Merge And Deploy Gates

Never merge, deploy staging, or deploy production unless the user explicitly asked for that mode or the repo's standing instructions require it.
Use ops/skills/deploy-6529/SKILL.md for actual merge execution, staging deployment, production deployment, backend deployment coordination, cross-agent coordination, and deployed-environment E2E validation.
Before merging, ensure the PR is agent-happy, bot-happy, required checks are passing or explained, and required approvals are present.
Before staging deploy, confirm the merge commit/ref, use the repo-approved staging deployment path, then validate the deployed target. In this repo, the documented fresh-clone staging refresh path is ./bin/6529 staging.
Before production deploy, require successful staging validation unless the user explicitly overrides it. Use the repo-approved production deployment path and verify the deployed version or visible behavior afterward. In this repo, production deploy is the Web Deploy - PROD workflow in .github/workflows/build-upload-deploy-prod.yml.
If deployment or E2E fails, hand off to ops/skills/deploy-6529/SKILL.md to diagnose, fix, redeploy, and rerun validation before proceeding.

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.