From 1a401357224f1c6c7ae0b5033ce6696416b9613e Mon Sep 17 00:00:00 2001 From: Martin Janse van Rensburg Date: Thu, 9 Jul 2026 09:51:18 +0200 Subject: [PATCH 1/3] skills: add mandatory adversarial review to content-write-blog Every finished draft gets reviewed by fresh-context agents with refutation missions (fact/code/reader/positioning lenses) before any PR; implementer fixes, reviewers re-review, loop until a round returns zero confirmed findings. Version 2026.7.9. Co-Authored-By: Claude Fable 5 --- .claude/skills/content-write-blog/SKILL.md | 27 ++++++++++++++++++++-- 1 file changed, 25 insertions(+), 2 deletions(-) diff --git a/.claude/skills/content-write-blog/SKILL.md b/.claude/skills/content-write-blog/SKILL.md index 88ee826a64..bef8425406 100644 --- a/.claude/skills/content-write-blog/SKILL.md +++ b/.claude/skills/content-write-blog/SKILL.md @@ -2,7 +2,7 @@ name: content-write-blog description: Use when the operator wants to write a blog post, draft a blog article, start a new post for the Prisma blog, or publish to prisma.io/blog. metadata: - version: "2026.7.8" + version: "2026.7.9" --- # Write Blog Post @@ -146,10 +146,33 @@ End by giving the operator, in a short block: - The path to the post file (within their checkout). - The author profile path, if one was scaffolded. - A reminder that the repository workflow is theirs: create a feature branch, commit the skeleton (and author profile), push, and open the pull request following the blog repo's contribution process. The pull request should be opened as a **draft** until the post is fleshed out. -- A clear next-step instruction: _"Edit the post to flesh out each section, keep it consistent with positioning and free of AI slop (see Writing quality), run the `content-seo-geo` skill in this repo to optimize the finished draft for search engines and AI answer engines, then branch, commit, push, and open a draft PR per the blog repo's contributing guide."_ +- A clear next-step instruction: _"Edit the post to flesh out each section, keep it consistent with positioning and free of AI slop (see Writing quality), run the `content-seo-geo` skill in this repo to optimize the finished draft for search engines and AI answer engines, run the Adversarial review below on the finished draft, then branch, commit, push, and open a draft PR per the blog repo's contributing guide."_ Do not claim the post is "done" or "ready" — it is a skeleton handed back to the operator. +## Adversarial review (required before any PR) + +Every finished draft is reviewed by agents that did not write it, in separate context windows, before it goes anywhere near a pull request. The author (human or agent) wants the post to ship; a reviewer with a fresh context and a refutation mission does not share that bias. A blog post is a set of falsifiable claims — prices, version numbers, benchmark figures, API behaviors, links — and the reviewers' job is to falsify them. + +Run this after the draft is complete and the `content-seo-geo` pass is done, and re-run it after fixing what it finds. + +### How to run it + +Spawn at least two reviewer agents (Claude Code subagents, or a review workflow for larger posts). Rules that make the isolation real: + +1. **Reviewers receive only the draft file path and their mission.** Never include the writing conversation, the pitch, the outline, or any statement of what the post intends or why it is correct. A prompt that says "review this post, which correctly explains X" has already contaminated the reviewer. +2. **Each reviewer gets a refutation mission, and skepticism is the default.** "Find reasons this is wrong" outperforms "check whether this is right." +3. **Distinct lenses, one per reviewer** — diversity catches what redundancy misses. Pick from: + - **Fact refuter**: attack every number, price, version, date, and named behavior. Verify each against the live primary source (vendor pricing page, official docs), not from memory. Report any claim whose source does not say what the post says. + - **Code refuter** (posts with code): run every sample fresh against the stated versions. Report anything that does not compile, run, or produce the shown output. + - **Reader skeptic**: where does the post confuse, overclaim, contradict itself, or read like marketing? Where would a knowledgeable reader stop trusting it? + - **Positioning refuter**: report claims that contradict the positioning doc or overstate product status (GA claims, superlatives, unverified benchmarks). +4. **The implementer fixes; reviewers re-review.** Findings come back to the authoring session, which applies fixes. Re-run the reviewers on the fixed draft. Repeat until a round produces no confirmed findings. The implementer never marks its own finding as resolved without a reviewer pass confirming it. + +### Completion criterion + +The draft is ready for the operator's PR when the most recent review round returned zero confirmed findings, and the operator has been given the final round's summary (findings found and fixed per round) so they can judge the review's depth, not just its verdict. + ## Writing quality The lead you draft, and the prose the author later writes over your stubs, ship to prisma.io/blog as public content. Draft the lead to this bar, and name the same bar in the hand-off so the author holds it: From f0317d459a66df579abf178557cfbdaa78d6f2b1 Mon Sep 17 00:00:00 2001 From: Martin Janse van Rensburg Date: Thu, 9 Jul 2026 10:47:54 +0200 Subject: [PATCH 2/3] skills: adversarial review runs every applicable lens, regardless of post size One reviewer per applicable lens (fact/reader/positioning always, code when present) replaces the 'at least two' floor; subagents-vs-workflow named as an implementation choice, not a review-depth choice. Co-Authored-By: Claude Fable 5 --- .claude/skills/content-write-blog/SKILL.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.claude/skills/content-write-blog/SKILL.md b/.claude/skills/content-write-blog/SKILL.md index bef8425406..5db284e596 100644 --- a/.claude/skills/content-write-blog/SKILL.md +++ b/.claude/skills/content-write-blog/SKILL.md @@ -158,11 +158,11 @@ Run this after the draft is complete and the `content-seo-geo` pass is done, and ### How to run it -Spawn at least two reviewer agents (Claude Code subagents, or a review workflow for larger posts). Rules that make the isolation real: +Spawn one reviewer agent per applicable lens, every lens that applies, regardless of post length. The fact, reader, and positioning lenses apply to every post; the code lens applies whenever the post contains runnable code. Whether the reviewers run as plain subagents or as an orchestrated review workflow is an implementation choice, not a review-depth choice: a workflow's vote-counting and automated re-review loops pay off when findings are numerous, but the lenses and rules are identical either way. Rules that make the isolation real: 1. **Reviewers receive only the draft file path and their mission.** Never include the writing conversation, the pitch, the outline, or any statement of what the post intends or why it is correct. A prompt that says "review this post, which correctly explains X" has already contaminated the reviewer. 2. **Each reviewer gets a refutation mission, and skepticism is the default.** "Find reasons this is wrong" outperforms "check whether this is right." -3. **Distinct lenses, one per reviewer** — diversity catches what redundancy misses. Pick from: +3. **Distinct lenses, one per reviewer** — diversity catches what redundancy misses. The lenses: - **Fact refuter**: attack every number, price, version, date, and named behavior. Verify each against the live primary source (vendor pricing page, official docs), not from memory. Report any claim whose source does not say what the post says. - **Code refuter** (posts with code): run every sample fresh against the stated versions. Report anything that does not compile, run, or produce the shown output. - **Reader skeptic**: where does the post confuse, overclaim, contradict itself, or read like marketing? Where would a knowledgeable reader stop trusting it? From 2d8183e2f3d0d0697fdbe662c192eef8a492c0e1 Mon Sep 17 00:00:00 2001 From: Martin Janse van Rensburg Date: Thu, 9 Jul 2026 10:54:19 +0200 Subject: [PATCH 3/3] skills: adversarial review is Step 10 of the process, not an appendix Numbered into the step sequence as the final gate before any PR; Step 9 hand-off now points to it as 'complete Step 10 before opening any PR'. Co-Authored-By: Claude Fable 5 --- .claude/skills/content-write-blog/SKILL.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/.claude/skills/content-write-blog/SKILL.md b/.claude/skills/content-write-blog/SKILL.md index 5db284e596..10bdb78e8a 100644 --- a/.claude/skills/content-write-blog/SKILL.md +++ b/.claude/skills/content-write-blog/SKILL.md @@ -146,15 +146,13 @@ End by giving the operator, in a short block: - The path to the post file (within their checkout). - The author profile path, if one was scaffolded. - A reminder that the repository workflow is theirs: create a feature branch, commit the skeleton (and author profile), push, and open the pull request following the blog repo's contribution process. The pull request should be opened as a **draft** until the post is fleshed out. -- A clear next-step instruction: _"Edit the post to flesh out each section, keep it consistent with positioning and free of AI slop (see Writing quality), run the `content-seo-geo` skill in this repo to optimize the finished draft for search engines and AI answer engines, run the Adversarial review below on the finished draft, then branch, commit, push, and open a draft PR per the blog repo's contributing guide."_ +- A clear next-step instruction: _"Edit the post to flesh out each section, keep it consistent with positioning and free of AI slop (see Writing quality), run the `content-seo-geo` skill in this repo to optimize the finished draft for search engines and AI answer engines, then complete Step 10 before opening any PR."_ Do not claim the post is "done" or "ready" — it is a skeleton handed back to the operator. -## Adversarial review (required before any PR) +## Step 10: Adversarial review -Every finished draft is reviewed by agents that did not write it, in separate context windows, before it goes anywhere near a pull request. The author (human or agent) wants the post to ship; a reviewer with a fresh context and a refutation mission does not share that bias. A blog post is a set of falsifiable claims — prices, version numbers, benchmark figures, API behaviors, links — and the reviewers' job is to falsify them. - -Run this after the draft is complete and the `content-seo-geo` pass is done, and re-run it after fixing what it finds. +The final step of the process, and the gate to a pull request: once the skeleton has been fleshed into a finished draft and the `content-seo-geo` pass is done, the draft is reviewed by agents that did not write it, in separate context windows. The author (human or agent) wants the post to ship; a reviewer with a fresh context and a refutation mission does not share that bias. A blog post is a set of falsifiable claims — prices, version numbers, benchmark figures, API behaviors, links — and the reviewers' job is to falsify them. ### How to run it