/reviewing-docs

name: reviewing-docs
description: Use when the user has a finished or near-finished document (memo, business review, PRD, decision doc, briefing, comms, framework, talking points, post-mortem) and wants it pressure-tested before it ships, such as "review this doc", "poke holes in this", "is this ready to send". Works on any doc, not just mindpowers-drafted ones. Not for code review.

Reviewing Docs

Overview

A standalone red-team pass for a finished (or nearly finished) piece of writing. It works whether or not the doc was made with mindpowers: a pasted memo, a doc someone else wrote, a file on disk, all fine. It is the "review" step of the mindpowers loop (shape → draft → review → remember), but it doesn't require the other steps to have happened.

The job is not to improve the prose. It's to find the places where the doc will get punctured in the room it's headed for, before that room punctures it: the exec meeting, the regulator's inbox, the Slack thread. Track the steps below as todos if your harness has a task list.

**When this fires:** "review this doc," "poke holes in this," "is this ready to send," "what am I missing before I ship this," or being handed a file/pasted text and asked whether it holds up. It does not fire for source code, config, or anything a code-review tool should be looking at; decline that and point at a code-review skill or tool instead.

User-Facing Language

Think precisely; respond plainly. Use common words and short sentences. Explain an unavoidable technical term the first time it appears, and give one short example when a rule could be misunderstood. For a material review conclusion, give a compact explanation: the recommendation or conclusion, what you checked, the main reasons, uncertainty, and the next step. Do not dump internal machinery. If the user says the explanation is unclear, explain it again from scratch.

Step 1: Find the spec

Check the doc for a paper trail before reviewing it blind.

1. Look at the doc's own frontmatter for a `spec:` link. 2. If there's none, scan `docs/mindpowers/specs/` (and legacy `docs/brainstorm/` if it exists) for a spec with a matching filename stem or topic.

**If a spec exists:** do a fidelity check before anything else.

• Is every section the spec called for actually present in the doc?
• Did anything make it into the doc that the spec didn't scope in?
• Has the claim or recommendation drifted between spec and doc: softened, hedged, or quietly changed?

Fidelity problems are worth surfacing on their own, separate from the lens panel below, because they mean the doc stopped tracking its own plan somewhere along the way.

**If no spec exists:** offer to write down the document's intended audience, main claim, and shape before reviewing.

> "There's no spec for this doc. Want me to first write down its audience, main > claim, and shape so we can check that it says what you intended?"

This is worth doing even when it feels like a formality: it's often where the real problem surfaces, because writing down "here's the claim this doc is actually making" tends to expose that the claim isn't the one the author intended. A doc that reads fine sentence-by-sentence can still imply a claim nobody signed up for once you state it plainly. If the user declines, proceed straight to the template rubric and lens panel without it.

Either way, don't skip Step 1 to save time. A doc that fails its own spec is a different, more useful finding than a doc that merely reads weak; surface it first so the rest of the review has the right frame.

Also check `docs/mindpowers/reviews/` for a prior review of this doc (same filename stem). If one exists, load its findings ledger before assigning any IDs: existing findings keep their `R-###`, new findings continue the sequence, and the re-review updates statuses per the Output section.

Step 2: Load the template rubric

1. Identify the doc's type from its content and shape (business review, decision doc, PRD, briefing doc, comms draft, framework, talking points, post-mortem) or from its frontmatter `type:` field if present. 2. Load `skills/mindstorming/references/<type>.md`. 3. Treat that file's **Standards baked in** and **Anti-patterns** sections as the objective rubric, not your own taste. Check the doc against them directly (e.g., for a decision doc: is the recommendation up front? Is a real counter-argument engaged, or a strawman?). 4. If the doc doesn't match any of the nine templates, treat it as self-shape: there's no reference file to load, so the rubric is whatever structure the (reverse-engineered or real) spec implies, plus general clarity and completeness.

Treat frontmatter `readiness` as the canonical binary field: `readiness: ready | not-ready`. Never put a type-specific label such as `build-ready` in frontmatter. For a PRD, canonical `ready` means the body must satisfy and show the user-facing `Readiness: build-ready` bar. Treat any missing evidence boundary, untraceable requirement, unverifiable acceptance criterion, incomplete triggered conditional module, or blocking open decision as a blocker and report any mismatch with canonical `ready`. Canonical `not-ready` must retain its named material blockers. For other document types, apply the same rule using the selected template's type-specific ready label or readiness bar where one exists.

Do not invent a rubric when a template exists. The template encodes standards someone already learned the hard way; skipping it means re-deriving from scratch and probably missing something the template would have caught.

For example: a decision doc gets checked against `decision-doc.md`'s standards directly: is the recommendation in the first section rather than the last, is there a real counter-argument rather than a strawman, is the ask explicit. A comms draft gets checked against `comms-draft.md`: is the key message identifiable on a skim, is the tone calibrated to the stated audience. Use the rubric file's own