/style-review

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:

agent-style --version

If the command is missing, do not claim style review has run. Report this exact fallback:

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:

/style-review FILE.md

1. Read `FILE.md` and confirm it is prose that fits this skill's scope. 2. Run the deterministic audit:

   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:

   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:

/style-review BEFORE.md AFTER.md

Run:

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:

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.