Skip to content

Skills · core

doc-critique

Review an existing document — ADR, design doc, runbook, exec summary, tech-comparison matrix, deck outline, decision log — and produce a structured critique against the same quality bars the skilldrop generators enforce. Categorizes findings by severity (blocker / major / minor / nit), points to the exact section/line, and suggests a concrete fix for each. Use when the user wants a second-pair-of-eyes review before sharing a doc, or has been handed someone else's artifact and wants to know what to push back on.

Pack coreTier heavyJob Get a draft ready to shipv0.1.1

npx skilldrop-cli install doc-critique
Other ways to install

With the sibling skills it hands off to:

npx skilldrop-cli install doc-critique --with-related

The whole pack it belongs to:

npx skilldrop-cli install --pack core

By hand, from a clone of the repo:

cp -R packs/core/skills/doc-critique ~/.claude/skills/

In Claude Code, with the core plugin installed, invoke it as:

/core:doc-critique

Try it

A realistic prompt from the skill's acceptance evals:

Critique this design doc before I circulate it to the team. [design doc: a TL;DR full of adjectives, an approach section that says 'industry standard', no SLOs, and a one-line rollout plan]

What a good result looks like

Example output

critique of a design-doc excerpt · the skill's own worked example, source

Input

TL;DR

We will build an innovative, scalable notification service to leverage our existing infrastructure and deliver best-in-class user engagement.

Approach

The service consumes events and sends notifications. It will be highly available and performant. We considered several options and chose a queue-based design because it is the industry standard.

Rollout

We will roll it out to all users.

Output

Verdict: not ready to circulate — 1 blocker, 2 major, 1 minor. The doc asserts conclusions it never earns; a reader can't tell what's being built or why this shape.

🟥 Blocker — the decision has no rationale (§ Approach). Quoted: "chose a queue-based design because it is the industry standard." "Industry standard" is not a reason; it hides the actual tradeoff. Fix: replace with the decision's real driver — e.g. "chose a queue so a downstream outage buffers events instead of dropping them; the alternative (synchronous fan-out) loses notifications when a provider is down." Name the alternative and why it lost.

🟧 Major — TL;DR is adjectives, not content (§ TL;DR). Quoted: "innovative, scalable … leverage … best-in-class user engagement." Five value-words, zero facts — a reader learns nothing about scope. Fix: state what it does and the one number that matters: "A queue-backed service that delivers email/push notifications from domain events, targeting < 5s p95 delivery for 1M events/day."

🟧 Major — unfalsifiable quality claims (§ Approach). Quoted: "highly available and performant." No SLO, so nothing can be reviewed or later checked. Fix: commit numbers — availability target (e.g. 99.9%), p95 latency, throughput — or move them to an explicit "Open questions" list if unknown.

🟨 Minor — rollout has no stages or guardrail (§ Rollout). Quoted: "roll it out to all users." No canary, no rollback trigger. Fix: a 2–3 line staged plan (1% → 10% → 100%) and the metric that halts it (delivery-failure rate > X%).

Why this passes the quality bar

Severity is calibrated (one blocker). Every finding is local and quotes the doc verbatim (the audit trail that it was actually read), the fixes are paste-able, and it critiques the doc's case-making — it does not re-argue whether a queue is the right architecture.

How it's checked

Measured against plain Claude Code (2026-10-23): it met 84% of its checks, against 63% without it, and a blind judge preferred the agent without it. How skills are checked

19 assertions across 3 acceptance evals, and 9 trigger queries. Every skill's checks

What the output must do
  • Every finding quotes the document verbatim rather than paraphrasing it — the quoted snippet is the audit trail
  • Findings are local and anchored to a section, not global judgments like 'the tone is off'
  • Severity is calibrated — blockers do not outnumber majors
  • Fixes are paste-able: when the fix is 'add a section', the critique shows what that section should contain
  • The critique reviews whether the doc made its case, and does not re-debate the underlying technical topic
  • The document archetype is identified and the critique is run against that archetype's quality bar
  • Catches that the phase totals (140 + 120 + 62 = 322) do not match the 312 homes stated
  • Challenges the 40% bill-cut claim as unsupported by a six-home pilot measured over one summer month
  • Spots that the January 2027 start contradicts the contractor being unable to start before April 2027
  • Notes that the summary never says what decision it needs from the board, or by when
  • Points each problem to where it sits in the document, by section or quoted text
  • Respects the length limit: fixes cut or replace existing text rather than only adding material, and the reply does not hand back a rewritten document
  • Does not invent figures or facts not in the document, such as a corrected savings figure
  • Gives three problems, as asked, not a longer list
  • Catches that £120 to £150 is a 25% rise, not 15%
  • Each problem comes with a concrete fix the committee could make
  • Answers without first asking questions
  • Uses plain language suited to a parent volunteer
  • Does not invent facts about the club, such as its actual costs, a payment date or a payment method
When it should and shouldn't activate

Should activate:

  • Critique this design doc before I share it
  • Review this ADR and tell me where it's weak
  • Is this runbook actually good? Give me a structured critique
  • Score this exec summary against a quality bar
  • Review my document and give me severity-tagged findings with fixes

Should leave to another skill:

  • Review this pull request for bugs
  • Write a new ADR for this decision
  • Get five senior personas to deliberate whether we should do this
  • Summarize this document for executives

Related skills

council-review, decision-log

Source

SKILL.md · the whole folder on GitHub.