write-review

Article Review

Score an article against the rubric for the framework it was written in, and report findings the author can act on. Every rubric is bundled in references/; nothing is fetched at runtime.

A review never edits. The article file must be byte-identical before and after. Some rubric text talks about rewrites, diffs, or "conversion"; treat all of it as proposed text in the report, never as edits to the file, and run the review once (no loop toward a target score). Applying changes is the author's job, or a calling skill's (for example write-article-revision, or write-article's review loop, which re-runs this skill after each round of fixes; each run is still a single pass).

Usage

/write:review [article] [framework]

• article: a file path, pasted text, or URL. Omit it to review the last article created or adjusted (step 1).
• framework: optional. Any key or alias from the table below (how-to, fundamentals, diataxis-explanation, pas, a-list.md, ...). An explicit framework wins over detection. Callers such as write-article-revision pass the article's articletype here.

Frameworks

references/prompt-index.md is a one-line summary of what each rubric evaluates.

Workflow

1. Resolve the target article. Use what the user or caller gave you. Convert any path to an absolute path. If no article was given, stop at the first hit:

1. This conversation: the article file (a content/**/index.md, or Markdown with front matter) you created or edited most recently in this session. If you touched several, pick the last one edited and list the others so the user can redirect.
2. The blog repo: run scripts/last-article.sh (in this skill). It finds the blog repo even when the current directory is elsewhere ($BLOG_ROOT, the current git root if it has content/, else ~/Projects/websites/jeffbaileyblog), considers only content/**/index.md, checks the working tree first (newest uncommitted or untracked by mtime), then the last commit that touched an article (the most-changed article when a commit touched several), and prints an absolute path plus its source.
3. Ask the user only when both come up empty.

State the resolved absolute path and how you found it before reviewing.

1. Determine the framework. Take the first rule that decides it, and record which signal decided:

1. An explicit framework argument (match keys, aliases, or rubric filenames, case-insensitive).
2. Front matter articletype: (keys above).
3. Content directory fundamentals/, learn-x/, or x-vs-x/. These beat the diataxis field: a Fundamentals or comparison article also carries diataxis: explanation, but it gets its own rubric.
4. Front matter diataxis:, diataxis_type:, or documentation_type: (tutorial, how-to, reference, explanation).
5. The other directory and title signals in the table.
6. Structure signals in the table.
7. Still ambiguous between two rubrics: ask once, naming the two candidates and the signals for each.

1. Load the rubric. Read the rubric file for the framework. For fundamentals and comparison also read diataxis-article-explanation.md, and for learn also read diataxis-article-how-to-guides.md: the blog rubric's override block and extra checks apply on top of that base rubric, and the base rubric supplies the type gate and output format.

1. Fill the template variables. Rubrics open with fields like {{subject_area|default="technical concepts"}}. Pre-fill each from the article (subject from the title, audience from front matter or prerequisites), otherwise use the default. Do not stop to ask: the rubrics say to decide and proceed. The only field with an empty default is list_topic in a-list.md; take it from the title. List the values you used in one line of the report so the user can rerun with overrides.

1. Apply the review, read-only. Follow the loaded rubric: type gate, review mode, section checks, scoring. Quote the passage and give the heading or line number for each finding, with exact replacement text where the rubric asks for it. Do not edit the article and do not re-run the review to chase a score, whatever older copies of a rubric say. Do not invent facts, sources, resources, or URLs in recommendations; when a fix needs one, write [NEEDS FACT: ...] or [NEEDS RESOURCE: ...].

1. Blog checks (jeffbaileyblog only). Apply these when the article lives in the jeffbaileyblog repo or has its Hugo front matter (type: post, categories, cover):

• Read the blog's live hugo/content/prompts/writing-style.md (the bundled references/writing-style.md is only the fallback when the live file is missing; the live one is what the author edits, so the bundled copy drifts) and check: no emdashes; the banned-phrase list; voice (Diátaxis types and Learn X are second person and imperative; Fundamentals may use "I" for the author's judgments and experience, but their reader-facing scaffolding uses "you"; first person is right for thought pieces and opinion posts; never "we"/"our"; when the rubric and the live style guide disagree, the live style guide wins); link style. Profanity is intentional voice: never flag it.
• Check title:, description: (160 characters or fewer), and keywords: against seo-front-matter.md. Prefer the blog's own hugo/content/prompts/seo-front-matter.md when it exists; the bundled copy is the fallback.
• Invoke the ai-sanitize skill (jbb-skills:ai-sanitize when installed as a plugin) in report mode so it lists AI tells without editing. Triage its hits (link titles often trip the Title-Case check) and fold real ones into the issues with locations. If it is not installed, say so and skip it.

1. Score the blog-post checklist. The framework rubric judges whether the article does its type's job; it doesn't ask whether the piece is worth reading. write-article drafts against the "Pre-publish checklist" at the end of ${CLAUDE_SKILL_DIR}/../write-article/references/great-blog-post.md, so score every review against the same list; the writer and the reviewer then hold the same bar. Read that section (and the guidance above it when an item is unclear) and mark each item:

• PASS or FAIL, with a quoted passage or heading as evidence. A FAIL also becomes an issue in the issue list with its location and a proposed fix, so write-review-apply can act on it.
• N/A only when the item can't apply: no opinions to support, no statistics to source. "The draft got a step-away and a rewrite" can't be seen in the text; mark it N/A unless the author said so.
• The item on writing-style.md and seo-front-matter.md reuses step 6's result; on non-blog articles mark it N/A.

Report the score as Checklist: <passed>/<applicable> (<n> N/A). Keep it separate from the rubric score: callers such as write-article-revision loop on the rubric score, so folding the checklist into it would move their target. Where an item conflicts with a site rule, the site rule wins (see "Where site rules win" in the same file). If the file is missing (write-article not installed), say so and skip this step.

1. Deliver the review. Lead with three lines: article (absolute path), framework and the signal that decided it, rubric file(s) loaded. Then use the rubric's own output format: the JSON summary, the overall score, a PASS / NEEDS_IMPROVEMENT / FAIL status for each rubric section with its evidence, the issues with locations, the prioritized improvement plan, and strengths to keep. Add the blog rubric's extra section when it defines one ("Blog-Specific Fixes" for Fundamentals, "Learn X Launch Pad Fixes" for Learn X, "Comparison Fixes" for comparisons). After the rubric sections, add a "Blog-Post Checklist" section: the score line from step 7, then one line per item with its status and evidence. In the JSON summary, add "checklist": {"passed": <n>, "applicable": <n>, "na": <n>}. Do not invent numeric per-dimension scores the rubric does not define. End by confirming the article was not modified.

1. Save the review so write-review-apply can act on it later, even from another session. Write the full review you delivered (the three lead lines, JSON summary, and Markdown review) to the path this prints, outside the blog repo:

   python3 "${CLAUDE_SKILL_DIR}/../write-status/scripts/article_status.py" review new <article index.md>

Put the rules stamp right after the three lead lines, before the variables line and the JSON summary. It records which rule files the grades came from, so write-review-apply can tell later whether the rubric or style guide changed underneath the findings. Let the script compute it (hand-typed hashes are worse than none); pass the rubric file(s) loaded in step 3, and --no-blog when step 6 didn't apply:

   python3 "${CLAUDE_SKILL_DIR}/scripts/rules_stamp.py" stamp <article index.md> <rubric.md> [<base rubric.md>]

It prints Rubric: references/<file> @ <hash> per rubric, Style: and SEO: lines for the writing-style.md and seo-front-matter.md step 6 reads (live blog copy first, bundled fallback), and a Checklist: line for step 7's checklist. Paste its output verbatim.

Saving to that path does not touch the article, so the read-only rule still holds. If the script isn't installed, skip this step and say the review wasn't saved. End the reply with one line offering the follow-up: "Run /write:review-apply to apply these fixes."

Record the run

After finishing on a jeffbaileyblog article, append the run to the ledger that write-status reads, so later checks know this skill ran even after transcripts are cleaned up. Do this once per article, even when the result was a failure, and put the outcome in the note:

python3 "${CLAUDE_SKILL_DIR}/../write-status/scripts/article_status.py" record write-review <article index.md> --note "<one-line result>"

If the script isn't there (write-status not installed), skip this step.