# Ponylang Prose Review

> Review for ponylang prose

- Skill: `ponylang/ponylang-prose-review` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add ponylang/ponylang-prose-review`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ponylang/ponylang-prose-review/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ponylang (https://skillmd.com/u/ponylang)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ponylang/ponylang-prose-review

---


# Review for ponylang prose

The review that applies the ponylang Last Week in Pony house style and the craft rules to a
draft with fresh, decorrelated eyes. A single generic copy-editor pass collapses every
concern into "looks fine" and misses the failures that matter — enumeration instead of
narrative, prose reproduced from a linked source, an invented framing, an unearned promise, a
fabricated characterization, a wrong technical claim. This decomposes the review so each gets
its own lens.

This skill is **self-contained** — it loads no other skill. All the ensemble mechanics it
needs are inlined below; nothing comes from `pony-ensemble` / `pony-synthesize` or any
personal skill. A contributor with only this repo's `.claude/` can run it.

## When to run

After a draft of ponylang prose exists, before it ships:

- Last Week in Pony posts (the main case).
- Other ponylang blog posts.
- The Pony Development Sync issue comment produced by `dev-sync-summary`, if you want more
  than its built-in self-review.

## Two rulebooks this skill reads

- **The AGENTS.md "Last Week in Pony" section** — the house voice (tone, em-dash frugality,
  backtick technical terms, Office Hours singular, `owner/repo` naming, conversational not
  clipped). The House-voice persona reads it.
- **`references/craft-rules.md`** (alongside this skill) — narrative, reader-orientation,
  tightness, content-honesty/source-fidelity. The other craft personas read the relevant
  sections.

## Mode selection by size

Count the draft's **prose paragraphs**: blank-line-separated blocks of running prose. Do not
count fenced code blocks, YAML front matter, headings, or list items.

```
PARAGRAPH_THRESHOLD = 2
```

- **> 2 prose paragraphs → full review.** The six-lens ensemble below — seven when the draft
  has code or technical claims, where the conditional Accuracy lens joins. A post is always
  full.
- **≤ 2 prose paragraphs → cheap inline pass.** No subagents. The orchestrator reads the
  draft once against the AGENTS.md house style and the content-honesty section of
  `craft-rules.md` (pulling the source bundle if a claim needs checking), plus the mechanical
  pre-check, and returns Fix/Park findings directly.

`PARAGRAPH_THRESHOLD` is one line on purpose — move it when the size heuristic misjudges an
artifact.

## Source bundle

The content-honesty and tightness personas can only catch fabricated claims, flattened source
voice, and reproduced-source if they have the source. Assemble it per artifact and hand it to
**both** of those personas (the house-voice, narrative, and orientation personas work from the
draft and their rulebook):

| Artifact | Source bundle |
|---|---|
| LWIP post | the rotated issue + all its comments; linked prior posts; release notes (`gh release view`); linked PRs/issues (`gh`) |
| other blog post | linked posts; release notes / `gh release view`; the originating discussion or issue |
| dev-sync comment | the raw summary; the linked PRs/issues/RFCs (`gh`) |

A raw meeting summary and machine-generated recaps are leads to verify, not copy — pull facts
from them, never trust their wording or their number-to-title mapping.

## Mechanical pre-check (scripted, not an agent)

Run before spawning personas; feed results to synthesis. LWIP and blog posts live in this
repo's buildable, cspell'd site, so all of these apply:

- **cspell** over the file.
- **`mkdocs build --strict`** (set up the venv per the project README/CLAUDE.md if needed).
- **em-dash count** (flag heavy use).
- **link-target sanity** — does each link's text match what it points at?

For a dev-sync issue comment (not a repo file): em-dash count + link sanity only.

## Full process

1. **Identify the artifact and assemble the source bundle** (tables above).
2. **Run the mechanical pre-check.** Capture results.
3. **Make an evidence dir:** `~/tmp/prose-review-<timestamp>/`. Each persona writes its
   detailed evidence to a file there; pass the path in the prompt.
4. **Spawn the lens personas in parallel**, each a fresh-context subagent on your most capable
   model. Six always run: House-voice, Agency, Narrative, Orientation, Tightness,
   Content-honesty. A seventh, **Accuracy**, joins **only when the draft has code or makes
   technical/behavioral claims about a system** (compiler internals, an API, a release); skip
   it otherwise. Each prompt includes:
   - The persona document, read from `personas/<lens>.md`.
   - Its rulebook slice: the **House-voice** persona gets the AGENTS.md "Last Week in Pony"
     section and 2–3 recent posts from `docs/blog/posts/` for calibration; the Narrative,
     Orientation, Tightness, and Content-honesty personas get the relevant sections of
     `references/craft-rules.md`. The **Agency** persona needs no rulebook slice — its rule is
     self-contained in its persona doc, and it works from the draft alone. The **Accuracy**
     persona reads the actual source instead.
   - The draft in full.
   - For the **Content-honesty** and **Tightness** personas: the full source bundle.
   - For the **Accuracy** persona: the source the draft describes (the repo/files, release
     notes, the version it targets).
   - The shared persona output format (below).
   - "You are an ensemble agent — return findings to the orchestrator, take no external
     actions, edit nothing."
5. **Triage persona outputs** — confirm each addressed the actual draft and stayed on its
   lens. Drop nothing silently. Hold the **enumerative lenses to a higher bar**: the Agency
   lens must return its subject–verb table for the whole draft, and the Narrative lens the
   numbered idea-sequence for each section. A holistic verdict from either — "no
   anthropomorphizing," "reads fine" — with no enumeration behind it is not a pass; it is a
   lens that skipped the work. Re-run it and demand the enumeration.
6. **Synthesize** (inlined below).
7. **Triage into Fix / Park** and act (below).

## Shared persona output format

Include in every persona prompt. Each persona produces two artifacts.

**Evidence file** (written to the provided path): every finding with the exact quoted text
from the draft, what's wrong, the rule it violates, and the concrete rewrite.

**Summary** (returned to the orchestrator):

- **Findings**, ordered by severity (Blocking > Should-fix > Minor). Each:
  - **Quote**: the exact span from the draft.
  - **Lens**: this persona.
  - **Problem**: what's wrong (concise — full reasoning is in the evidence file).
  - **Fix or Park**: is the right change obvious (Fix), or does it need the author's judgment
    (Park)? With the suggested rewrite (Fix) or the question (Park).
- **Passes**: key things checked that read true. Brief.
- **Uncertainties**: anything the persona couldn't judge without the author or more source.

**Enumerative lenses must show their work.** Agency and Narrative are enumeration lenses,
not judgment lenses. Their summary carries the enumeration itself — Agency's subject–verb
table for the whole draft, Narrative's numbered idea-sequence for each section — even when
the verdict is clean. "None found" is credible only with the enumeration that proves every
subject, and every section's order, was actually looked at. A summary without it goes back.

## Synthesis (inlined)

The synthesizer is a fresh-context agent (or the orchestrator) given all persona summaries and
the mechanical-check results, with these instructions:

**Job:** integrate the persona findings into one deduplicated list. You are not averaging
opinions — you are assembling the strongest, non-redundant set of findings.

**Focus:**
- **Don't drop anything.** Every persona finding appears in the output or is explicitly merged
  into another. A review that surfaces a real problem and then loses it has wasted the
  discovery.
- **Cross-persona corroboration is high-confidence.** When two personas flag the same span
  from different angles, merge them into one finding marked high-confidence — never let each
  assume the other owns it and drop both.
- **Clusters signal structure.** Several small findings in one section often mean the section's
  shape is wrong (an enumeration, a reproduced source, a missing on-ramp). Call out the
  structural problem, not just the symptoms.
- **Severity stands.** If one persona says Blocking with evidence and another didn't mention
  it, it's Blocking. Don't soften by consensus.

## Fix / Park triage

Categorize every finding. Nothing is silently dropped.

- **Fix** — the right change is obvious: a misspelling, an unclear antecedent, a term used
  before it's introduced, an enumeration to reweave, prose reproduced from the linked source,
  an unbackticked technical term, an em-dash glut, a fabricated characterization to cut.
  Apply these directly.
- **Park** — needs the author: a framing or thesis the draft asserts that no source supports,
  a thematic hook, a tone call, a metaphor to keep or cut. **Never ship a parked call as
  final.** Batch parked items and present them as questions.

When run inside the `lwip` pipeline: apply the Fix items, list the Park items for the author,
and proceed. When run standalone: return both lists.

## Output format

```
## Prose review — <artifact>  (<full | inline pass>, N findings)

### Applied (Fix)
- <quote> → <change>  [lens]
...

### Raise with the author (Park)
- <quote> — <the question>  [lens]
...

### Mechanical
- cspell: <clean | issues>   build: <pass | fail>   em-dashes: <count>   links: <ok | …>

### Passes
- <brief confidence notes>
```

## The lenses

| Persona | Catches |
|---|---|
| `house-voice.md` | ponylang LWIP house style: tone (Hemingway, conversational not clipped), em-dash frugality, backtick technical terms, Office Hours singular, `owner/repo` naming, AI tells, clipped-imperative cadence. Reads the AGENTS.md guidelines; calibrates on recent posts. |
| `agency.md` | the enumerative anthropomorphizing pass: every clause whose subject is not a person, tabled and judged person / literal-op / AGENCY. Catches a library, release, change, or version given an action it can't take, and a machine given cognition. Deliverable is the table, not a verdict. |
| `narrative.md` | enumeration vs story, at section **and** prop level (a snippet/line-count/parenthetical can be dead cargo inside a good section); **and idea-order within each section** — a conclusion before its setup, a paragraph doubling back, a stranded sentence. Deliverable includes each section's numbered idea-sequence. |
| `orientation.md` | concept-before-use, unclear antecedents, missing on-ramps, offloaded context, compressed recaps that strip framing, missing prerequisites. |
| `tightness.md` | reproduced linked source, props that don't earn their place, filler, wrong altitude for the artifact. **Gets the source bundle.** |
| `content-honesty.md` | unsourced or fabricated claims, invented framing, invented quantitative characterizations, unearned promises, flattened source personality, lifted wording from unvetted sources, authorship/tense honesty. **Gets the source bundle.** |
| `accuracy.md` | **conditional** — runs only when the draft has code or technical/behavioral claims. Verifies code, API signatures, behavior and version claims, PR/issue numbers and titles against the actual source. |