Skip to content

Open source alternative to Semrush and Ahrefs

Simplify merge-ready skill instructions (#851)

Ben Senescudace7e2fbfcd
diff --git a/.agents/skills/merge-ready/SKILL.md b/.agents/skills/merge-ready/SKILL.md
index f09bab16..9238710a 100644
--- a/.agents/skills/merge-ready/SKILL.md
+++ b/.agents/skills/merge-ready/SKILL.md
@@ -1,71 +1,26 @@
---
name: merge-ready
-description: Take a branch from "code exists (or is about to)" to "ready for the maintainer's final review" — multi-axis subagent review with verified findings, fixes, ci:check, checkpoint commits, and an updated PR. Use whenever the user says a feature/fix/branch should be "merge ready", asks to get changes ready for review, or appends this to a build request ("build X and make it merge-ready").
+description: Get a branch ready for the maintainer's final review: review it for security, simplicity, and billing abuse, fix what's real, get checks passing, and open or update the PR. Use whenever the user says a feature, fix, or branch should be "merge ready", asks to get changes ready for review, or appends this to a build request ("build X and make it merge-ready").
metadata:
internal: true
---
-# Merge ready
+Get this branch ready for the maintainer's final review. If you were also asked to build something, build it first.
-Drive the current work to the point where the only remaining step is the maintainer's own review and merge. The deliverable is a pushed branch with a clean `pnpm ci:check`, checkpoint commits along the way, and an open PR with a high-level description plus review instructions.
+Fetch and merge `origin/main` if the branch is behind. Then review everything on the branch against it, including uncommitted and untracked files. Make sure you understand every product decision and change in functionality.
-**Never merge the PR. The maintainer always reviews last.**
+Is it secure?
-## 0. Figure out the starting point
+Is it as simple as it can be? What can be deleted or simplified given the end state of the branch? Did an unlikely edge case lead to overengineering? We prefer to delete code.
-This skill composes with feature work — it is not only a review pass:
+Does it use APIs and SDKs (TanStack, DataForSEO, Autumn, Cloudflare) idiomatically? Watch for code that reinvents what they already do, works around limits they don't have, or pays for more than it needs. Check the docs only when something looks off.
-- **Invoked alongside a build request** ("build X, make it merge-ready"): implement the feature/fix first, committing as you go, then continue below. The review phases cover _all_ changes on the branch vs `origin/main`, not just the last edit.
-- **Invoked on existing work** ("make this branch merge-ready"): start directly at step 1. The scope is `git diff origin/main...HEAD` plus anything uncommitted.
+Is there a significant way to abuse billing, like getting credits, paid features, or provider calls without paying? Ignore small leaks nobody would bother exploiting.
-## 1. Sync with main
+Beyond that, review it however you think best. Work out which parts could do the most damage if they're wrong and spend your time there. `docs/maintainers/review-guidelines.md` lists the repo's invariants and the things that look wrong but are intentional.
-- `git fetch origin main`. If the branch is behind, merge `origin/main` in and resolve conflicts (favor main's version for code this branch didn't intentionally change).
-- **Checkpoint:** commit the merge before starting review, so conflict resolution is auditable separately from review fixes.
+Fix what's real. Commit as you go. Get `pnpm ci:check` and `pnpm test` passing locally, then push. Those local runs stand in for CI, so don't wait for GitHub CI to finish.
-## 2. Multi-axis subagent review
+Open or update the PR against `main` with a high-level description: what changed and why, what to look at first, and anything you left for the maintainer's judgment. No per-file changelog.
-Spawn independent review subagents **in parallel**, one per axis, each given repo access, `docs/maintainers/review-guidelines.md` as required reading (hard invariants plus the false-positive controls for deployment modes, fixtures, and generated files), and the complete branch scope:
-
-- committed changes: `git diff origin/main...HEAD`
-- staged changes: `git diff --cached`
-- unstaged changes: `git diff`
-- untracked files: `git status --short`, followed by reading every in-scope untracked file
-
-Do not let an uncommitted or newly created file escape review merely because it is absent from `origin/main...HEAD`.
-
-1. **Unnecessary complexity** — thin wrappers, needless indirection, single-use abstractions, defensive guards for impossible states, dead config. This codebase deliberately stays simple.
-2. **Security** — authz on new endpoints (org/project scoping), SSRF, injection, secrets handling, anything user-input-shaped reaching D1/R2/external APIs.
-3. **Billing & metering** — ways a user could trigger DataForSEO/provider spend without being metered, charged-but-failed paths, retry/loop amplification, endpoints with unexpectedly high per-call user cost. Credits are billed via Autumn; uncounted spend is a revenue leak.
-4. **Library & project idioms** — TanStack (Router/Query/Start) used idiomatically; patterns match how the rest of the codebase already does it (shared application/provider error boundaries, db/schema conventions, existing component patterns). Flag novel patterns where an established one exists.
-5. **Vibe-coded cruft** — leftover scaffolding, stale comments narrating the edit history, console.logs, TODO-without-owner, copy-pasted near-duplicates, files/exports nothing uses.
-
-Each reviewer returns findings with file:line, severity (`blocker` / `should-fix` / `nitpick`), and a one-line rationale. Tell reviewers explicitly: this is an early-stage product — do not chase theoretical edge cases; mark anything debatable as `nitpick`.
-
-## 3. Verify findings — never blindly accept
-
-For each `blocker` and `should-fix` finding, spawn verification subagents (in parallel) that adversarially check the finding against the actual code and verdict **APPLY / APPLY-MODIFIED / REJECT** with reasoning. Drop rejected findings. Nitpicks don't need verification — they're reported, not necessarily fixed.
-
-### Preserve review learnings
-
-After verification, route durable learnings without forcing every review to change policy:
-
-- If an **APPLY** or **APPLY-MODIFIED** finding reveals a recurring or high-risk repository invariant that `docs/maintainers/review-guidelines.md` and CI do not capture, add a short paragraph there. A finding is evidence to evaluate, not automatically a rule.
-- Keep one-off bugs as code fixes and regression tests. Put deterministic mechanical checks in CI or lint instead of review prose.
-- When a small tooling, documentation, or workflow frustration occurs, use `papercuts` to append it to `.agents/PAPERCUTS.md`; do not derail merge-ready work to fix it.
-
-## 4. Fix, check, loop
-
-- Apply verified `blocker`/`should-fix` fixes. Apply nitpicks only when trivial and clearly right; otherwise list them in the PR for the maintainer to judge.
-- **Checkpoint:** commit fixes in logical groups (e.g. one commit per axis or per concern) so the fix history is reviewable on its own.
-- Run `pnpm ci:check` (prettier, knip, tsc, oxlint). Fix failures and re-run until clean. If a fix was substantial (not formatting/lint), run a quick re-review of just that change.
-- Loop until ci:check passes and no verified findings remain unaddressed.
-
-## 5. Push and open/update the PR
-
-- Push the branch. Open a PR against `main` if one doesn't exist; otherwise update the existing PR's description.
-- PR description requirements:
- - **High-level** — what changed and why, written for a human skimming. No file paths, no per-file changelog.
- - **How to review** — a short ordered guide: what to look at first, what the risky/judgment-call areas are, what was deliberately left out of scope.
- - **Review notes** — unfixed nitpicks and any REJECT verdicts worth a second opinion, clearly labeled as such.
-- Report back: PR link, one-paragraph summary, and anything that still needs the maintainer's judgment. Do not merge.
+Never merge. The maintainer reviews last.
diff --git a/docs/maintainers/review-guidelines.md b/docs/maintainers/review-guidelines.md
index 04121a8e..9f4c8d16 100644
--- a/docs/maintainers/review-guidelines.md
+++ b/docs/maintainers/review-guidelines.md
@@ -1,7 +1,7 @@
# Review guidelines
-Context for anyone or any agent reviewing an OpenSEO change: the merge-ready
-subagents, `/code-review`, and human reviewers. It began life as the
+Context for anyone or any agent reviewing an OpenSEO change: merge-ready,
+`/code-review`, and human reviewers. It began life as the
repository's Greptile configuration; Greptile is no longer wired to this
repository, but the invariants and the false-positive controls still describe
how the codebase is meant to work. Keep this file high-signal: a review finding