I mentioned the pre-merge SEO gate in one paragraph in my routines roundup post, trigger type, what it checks, a short code block. That was the summary version. This is the full breakdown: the exact prompt I run today (not the first draft), the trigger config, three things that broke in production, and the one change that cut false positives by more than half.
If you're new to routines as a concept, Claude Routines vs n8n covers the mechanics and when to reach for one over a workflow tool. This post assumes you already know what a routine is and want to see one actually running.
What the gate does and why it exists
Every blog post and service page on this site goes through the same pre-launch checklist before it ships, I wrote the full checklist out separately. For two years I ran it by re-reading the diff myself before every merge. I'd skip steps when I was tired. I'd approve my own PRs at 11pm and miss a missing FAQ schema that I'd have caught at 9am.
The gate is a Claude routine with a GitHub trigger. It fires on pull_request.opened and
pull_request.synchronize, reads every changed .astro file under
src/pages/blog/, and leaves one summary comment on the PR. It does not fix anything, it
does not approve anything. It reports, I decide.
The prompt, in full
This is the current version, after three rounds of editing against real false positives. The first version was four lines shorter and missed half of what matters, more on that below.
You are reviewing a pull request against johnarce.com, a static Astro
blog and service site. Only look at changed files under
src/pages/blog/*.astro and src/data/posts.ts. Ignore every other
changed file in the diff.
For each changed .astro blog post file, check:
1. Schema: an Article JSON-LD block is present (inherited from
BlogPost.astro, confirm the slug prop matches the filename).
If the post has a <div class="faq-list">, confirm an FAQPage
JSON-LD block exists too.
2. Answer-first: read the first two sentences after the opening
<p> tag. They must state a concrete fact or outcome, not a
rhetorical question or a scene-setting sentence with no claim in
it.
3. FAQ completeness: if a faq-list exists, it has at least 4
<details class="faq-item"> entries, and no <div class="faq-a">
is under 20 words (that's a placeholder, not a real answer).
4. Internal links: at least 2 <a href="/slug"> links to other
posts, and every linked slug must exist in src/data/posts.ts.
Flag any link to a slug that isn't registered there.
5. posts.ts sync: if this PR adds a new post, confirm a matching
entry exists in posts.ts with today's date and a slug that
matches the filename exactly, case-sensitive.
6. Banned phrases: flag "delve," "elevate," "leverage," "seamlessly,"
"it's worth noting," "in conclusion," or any sentence using an
em dash where a period or comma would read more naturally.
Leave exactly one summary comment on the PR, formatted as a
checklist, pass or fail per item, with the specific line number for
every failure. Do not leave separate inline comments. Do not push
any commits, do not edit any files, do not approve or request
changes on the PR itself.
If a changed file isn't a blog post (e.g. a style file or a shared
layout), skip it and say so in one line, don't apply the checklist
to it. Trigger config, and the one setting that actually matters
The trigger is a GitHub event, filtered to this one repo, on pull_request.opened and
pull_request.synchronize. I don't fire it on pull_request.reopened, a reopened
PR almost always already has a stale comment from the first pass sitting above it, and I'd rather
re-trigger that manually than get a duplicate.
The setting that mattered most wasn't in the trigger config, it was scoping the repo access. The routine only needs read access to this one repository. I built it without thinking about that at first, then narrowed it, because a routine with write access to every repo under the account is a bigger blast radius than the task needs, and GitHub-sourced text in a routine run should be treated as data to react to, not an instruction to obey blindly.
| Setting | Value | Why |
|---|---|---|
| Trigger events | pull_request.opened, pull_request.synchronize | Covers new PRs and pushed fixes, skips reopens to avoid duplicate comments |
| Repo scope | johnarce.com only, read access | No write access needed for a report-only routine, smaller blast radius if the token ever leaks |
| Path filter | src/pages/blog/*.astro, src/data/posts.ts | Keeps the routine from reviewing CSS or layout changes it has no checklist for |
| Output action | One PR comment, no file edits, no approve/request-changes | Keeps a human in the merge decision until the routine has a track record |
What broke running this for real
Three things went wrong in the first month that the first draft of the prompt didn't anticipate. None of them were infrastructure failures, the trigger fired every time, the routine ran every time, and the comment landed on the PR every time. The failures were all in what the prompt actually told the routine to check, which is the part that's on me, not the platform.
That distinction matters more than it sounds. A routine that silently fails to fire is easy to notice, the PR just sits there with no comment. A routine that fires, runs clean, and reports confidently on the wrong thing is harder to catch, because everything looks like it worked. I only caught two of these three issues because I happened to disagree with a specific flag, not because anything in the run itself looked broken.
The first prompt didn't say "ignore every other changed file in the diff." A PR that touched both a blog post and a shared CSS file got a checklist comment applied to the CSS file too, which has no FAQ section, no schema, nothing the checklist checks for. The routine dutifully reported six failures on a file the checklist was never meant to grade. Adding the explicit scope line in item zero of the prompt fixed it in one edit.
Early runs flagged several FAQ answers as "too generic" based on vibes, no measurable rule, just the model's judgment call on quality. That judgment disagreed with mine about a third of the time, and I couldn't tell from the comment why it disagreed. I replaced the vague instruction with a concrete word-count floor, "no faq-a is under 20 words." It's a blunter rule and it misses some genuinely thin answers that happen to hit 22 words, but I can see exactly why it passed or failed now, and false positives dropped from roughly a third of flags to close to zero.
Not literally, the routine can't approve PRs, but an early version of the prompt only checked that
linked slugs "looked like real pages." A post linked to /claude-routine instead of
/claude-routine-production-breakdown, close enough that the routine's summary just said
"internal links present," and I merged it. The fix was checking the linked slug against the actual
list in posts.ts rather than eyeballing whether it looked plausible, item 4 in the
current prompt above. That's a mechanical check now, not a judgment call, which is exactly the kind
of thing a routine should be doing instead of me.
What this actually catches now, after the fixes
Across the last batch of posts that went through this gate, it's caught a missing FAQPage schema block on a post that had a visible FAQ section but no matching JSON-LD, two internal links pointing at slugs that didn't exist yet (I'd written the anchor text before the post it pointed to), and one post where the opening two sentences were a rhetorical question with no actual claim in them. All three are the kind of thing that's easy to miss skimming your own draft and obvious once someone else, human or not, points at the line number.
It has not caught, and I don't expect it to catch, whether a post is actually good. It can tell me the FAQ has four entries over 20 words each. It can't tell me whether those four answers are the right four questions a reader actually has. That line between mechanical compliance and editorial judgment is where I draw the boundary for every routine I run, not just this one.
Key takeaways
- A routine prompt that says "check SEO quality" will drift and disagree with you. One that says "flag any faq-a under 20 words" gives you a result you can audit from the comment alone.
- Scope the repo access to what the task needs, not what's convenient. A report-only routine never needed write access, and narrowing it shrinks the damage if a token ever leaks.
- Explicitly tell the routine which files are in scope. Without it, the checklist gets applied to files it was never written for.
- Checking a linked slug against the actual posts.ts list is mechanical and catches real broken links. Checking whether a link "looks plausible" is a judgment call the routine will get wrong.
- Report-only output (one summary comment, no auto-fix, no auto-approve) keeps a human in the merge decision, which is where I still want to be after three rounds of tuning.
What I'll do next
I'm watching false-positive and false-negative rates over the next batch of posts before I consider letting this routine push a draft fix for the mechanical failures, a missing JSON-LD block, a wrong slug, rather than just flagging them. The editorial checks (answer-first, banned phrases) stay report-only regardless, those are calls I want to keep making myself.
FAQ
Why report-only instead of letting the routine fix issues directly? +
How many false positives did the original prompt produce?
Does scoping the routine to one repo actually matter for security?
Why does the prompt explicitly say what files to ignore?
Would this same pattern work for a site with multiple writers?
Want this built for your team?
I design AI agents and growth automation that run without babysitting. If that sounds useful, let's talk.
Get in touch โ