---
name: style-review
type: workflow
description: "Reviews Markdown prose against the pinned agent-style v0.3.5 rules and optionally writes a polished copy beside the source. Use for specs, ADRs, PR bodies, release notes, and technical docs when prose quality or evidence discipline matters."
argument-hint: "[file.md | before.md after.md]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Bash
effort: 3
context: main
agent: technical-writer
when_to_use: "Use as an opt-in REVIEW or SHIP gate for important prose artifacts. Do not use for every response, source code, casual chat, or non-English prose unless the user asks for style review."
---
# Style Review
Opt-in prose review for SDD artifacts using the portable `agent-style` v0.3.5
skill bundle. This skill is a second-pass review gate, not a global writing
mode. It does not edit `AGENTS.md`, `CLAUDE.md`, or any source document in
place.
## Source and Scope
- Rule pack: `.claude/skills/agent-style/references/RULES.md`
- Upstream note: `.claude/skills/agent-style/references/UPSTREAM.md`
- Attribution: `.claude/skills/agent-style/references/NOTICE.md`
- Detector reference: `.claude/skills/agent-style/references/rule-detectors.md`
- Revision prompt: `.claude/skills/agent-style/references/revision-prompt.md`
Use this skill for English technical prose where clarity, evidence, and review
readability matter:
- Specs and design docs
- ADRs and decision records
- PR titles and descriptions
- Release notes and changelog entries
- Runbooks, postmortems, and technical documentation
Do not use this skill for routine chat, code, generated logs, or prose where the
user's requested voice intentionally overrides formal technical style.
## Required CLI Check
Before any audit, check whether the CLI is available:
```bash
agent-style --version
```
If the command is missing, do not claim style review has run. Report this exact
fallback:
```text
style-review not run: `agent-style` CLI is not on PATH. Install with `pip install agent-style` or `npm install -g agent-style`, then rerun `/style-review <file>`.
```
Do not install dependencies unless the user explicitly asks.
## Single-File Workflow
Invocation:
```text
/style-review FILE.md
```
1. Read `FILE.md` and confirm it is prose that fits this skill's scope.
2. Run the deterministic audit:
```bash
agent-style review --audit-only FILE.md
```
3. Add semantic judgment for rules the CLI marks as skipped because they need
host-model context: RULE-01, RULE-03, RULE-04, RULE-08, RULE-11, RULE-F, and
RULE-H. Use the bundled `agent-style` rules and detector reference as the
source of truth.
4. Report a compact scorecard with per-rule counts and the first few examples.
5. Ask the user before writing any revised copy:
```text
Produce a polished draft at FILE.reviewed.md?
```
6. On yes, compose the revision using the vendored revision prompt and write
only `FILE.reviewed.md`. Never modify `FILE.md`.
7. Re-run the audit on `FILE.reviewed.md`.
8. Show before/after scorecard and a diff so the user can merge hunks manually.
## A/B Compare Workflow
Invocation:
```text
/style-review BEFORE.md AFTER.md
```
Run:
```bash
agent-style review --mechanical-only --compare BEFORE.md AFTER.md
```
Report the per-rule delta. Do not ask for polish and do not write files.
## Polish Invariants
The polished draft must obey these hard constraints:
- No new facts, metrics, citations, links, code behavior, or claims.
- Preserve Markdown structure unless the structure is the violation.
- Preserve meaning and approximate length budget.
- Resolve only flagged style issues.
- Write beside the source as `FILE.reviewed.md`.
- Never mutate or overwrite the source file.
If RULE-H flags unsupported claims, do not invent evidence. Keep the claim
flagged or ask the user for the missing source.
## SDD Integration
- In REVIEW, use this skill when a prose artifact is important enough that
clarity or citation discipline affects review quality.
- In SHIP, use this skill before final PR bodies, release notes, or docs when
the user asks for polish or when the agent claims prose quality.
- In verification-before-completion, a style-quality claim requires fresh audit
evidence from this skill or a clear statement that style review was skipped.
## Self-Verification
When asked "is style-review active?", reply:
```text
style-review active: audit 21 rules from agent-style v0.3.5 (deterministic via CLI; semantic via host for RULE-01, 03, 04, 08, 11, F, H); workflow at .claude/skills/style-review/SKILL.md.
```