| name | prose-pass |
| description | Two-step cross-model prose pass for design docs and other authored prose — Gemini simplifies via the headless prose_pass.py script, then Claude verifies every fact-guard held and applies. The prose sibling of code-review's cross-review.sh. |
| kind | skill |
| supported_hosts | ["claude-code","antigravity"] |
| version | 0.2.0 |
You are applying the prose-pass skill: a two-step cross-model readability pass over a finished document. Gemini simplifies, Claude verifies. A simplification pass run by the model that wrote the prose is an echo chamber — it cannot see the sentences only the author can parse. A different model's read finds them; your job is to keep its edit honest.
This is the prose sibling of code-review's cross-review.sh, and the headless sibling of the /design command's interactive external-review handoff (see Relationship to /design external review below).
When to run it
Run the pass on a document whose content is settled — a design doc at or near Status: final, a wiki page after a truth audit, any authored prose about to publish. The pass improves readability; it must never be the step that decides what the document says. Do not run it mid-authoring.
Step 1 — Gemini simplifies (the script)
Author the fact-guard list first
Before running anything, enumerate the specific truths in this document that a simplifier could plausibly invert — semantics that sound interchangeable to a reader who doesn't know the system. Three to eight lines, each a complete claim. From the proving run (2026-07-16, agentm's capture design):
- volatile decay only lowers retrieval rank — nothing is deleted
- inbox triage auto-applies, it is not a review gate
- re-audit triggers are conditions to revisit, never commitments
- single-operator system — no teams or users
The script refuses to run without a fact-guard list: the first un-guarded pass introduced exactly these inversions.
Run the script
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/prose_pass.py" path/to/doc.md \
--fact-guard guards.txt \
-o /tmp/doc.revised.md
The script assembles a four-block prompt — task header, your fact-guard list, the operator's voice pack (the always-load voice kernel plus the genre overlay, inlined verbatim from the vault), the document — and sends it to agy in one shot. For a genre other than design docs, point --overlay at the matching file under projects/_global/wiki-style/. The vault resolves at runtime; never pass a remembered absolute path.
| Exit | Meaning | What you do |
|---|
| 0 | revised document produced; structure verified | proceed to Step 2 |
| 1 | agy missing/unauthenticated, or voice pack unreachable | fall back to a Claude-only pass (below) |
| 2 | usage error, or structural contract violated twice | read stderr; fix the invocation or fall back |
On exit 1 or 2 the script prints a PROSE-PASS-DEGRADED: ... marker on stdout. Relay it verbatim — never paraphrase a degraded pass into a clean-sounding one.
The script already enforces structure mechanically: frontmatter, headings, table layout, the Document History section, and FACT-GUARD leakage (a guard line stapled into the document as new content, not just held as a truth) must come back clean, with one retry. What it cannot check is meaning — that is Step 2, and Step 2 is not optional.
If a call looks like a stream cutoff (agy's print-mode misreading a literal <thought>/<thinking>/<answer> token in the document as its own reasoning-tag opener — a real failure mode, not hypothetical), the script does not just retry the identical call; it redirects to a section-by-section pass and reports on stderr which sections, if any, it had to leave unrevised. A stderr line naming that fallback is informational, not an error — check the diff same as any other run.
Step 2 — Claude verifies and applies
Diff the revised document against the original, then work this checklist. Every item, every time:
- Fact-guards held — and not leaked as new content. Re-read each guard line against the revised text. A guard that now reads "roughly equivalent" has drifted — restore the original sentence. Separately, check that no guard line got stapled into the document as its own new sentence: a real pass produced ~10 such insertions in one run, including the same guard verbatim in three places and a meta-sentence explaining what a re-audit trigger is. The FACT-GUARD list is verification context, not draftable prose — the script's own mechanical check catches most of this and retries, but a paraphrased insertion can still slip through.
- Spot-check technical claims against the code they describe. Follow the revised text's claims into the implementation. The proving run caught Gemini asserting staging writes go through
save_entry when the design's whole point is that they bypass it — plus a security overclaim. Plausible is not true.
- Operator-authored lines restored verbatim. Hand-written sections must never be reworded, however awkward the simplifier found them. If you cannot tell whether a line is operator-authored, treat it as if it is.
- Banned-vocabulary scan. Check the revision against the voice kernel's strip-on-sight list and the overlay's banned vocabulary.
- Table cells stayed terse; structures actually identical. The script checked this mechanically — re-confirm on the diff before you overwrite anything.
Apply your corrections to the revised file. Then — and only then — deploy it over the original, and record the pass in the document's Document History: one row per day, consolidated (a second pass the same day amends that day's row rather than adding another).
Fallback: the Claude-only pass
When the script exits 1, run the same discipline yourself: read the voice kernel and genre overlay from the vault, hold the fact-guard list in front of you, and make one simplification edit pass — improve existing sentences, never regenerate, structure untouched. You lose the cross-model read, not the standard. Say so in the Document History row ("Claude-only; agy unavailable").
Relationship to /design external review
The /design command's interactive external-review handoff (transfer-context file → Antigravity/Gemini reshape → resume diff-review) is deferred to follow-on #5b — see the External review is deferred (#5b) section in commands/design.md. This skill is the headless sibling: one script call, one verify pass, no session handoff. It does not replace #5b and #5b does not replace it; when the interactive flow ships, the two share the fact-guard and voice-pack discipline defined here.
No PII
This is a public repo pattern: the vault path is resolved at runtime (--vault-path → $MEMORY_VAULT_PATH → .agentm-config.json), never committed, never echoed into the revised document or the Document History row.
