AGENT SKILL

review-doc

Use when the user asks to review, critique, score, grade, or "how good is this doc" for a Markdown doc or pasted text. Read-only. Scores it on the 20 Practical Prose dimensions and emits a findings table. Does not edit; fix-doc applies the findings next.

License 许可
MIT
最近更新
2026-11-14
Stars
★ 1
Forks
0

01 前言 Front Matter

name
review-doc
description
Use when the user asks to review, critique, score, grade, or "how good is this doc" for a Markdown doc or pasted text. Read-only. Scores it on the 20 Practical Prose dimensions and emits a findings table. Does not edit; fix-doc applies the findings next.

03 SKILL.md 正文

Reviewing Docs

Review stage of generate, review, fix. Read the doc, score it against the Practical Prose rubric, and emit a findings table that fix-doc consumes. Change nothing: no edits to the doc, no side files. Grading is done by you against the rubric; there is no scoring CLI.

Input is a file path or inline text. For inline text, review it the same way; Location uses heading names and paragraph ordinals ("para 3") since there are no lines.

References, relative to this skill:

  • ../../references/pprose-rubric.md: score anchors, NA/ERR decision tree, cascades, justified deviations.
  • ../../references/pprose-guidelines.md: the rules cited as "missed rule".
  • ../../references/common-doc-guidelines.md: structure, style, and Markdown formatting.
  • ../../references/diagrams.md: when a diagram is warranted.
  • ../../references/ai-tells.md: machine-written patterns; report them under Expression or Form.

Vendored files keep upstream names in their text: practical-prose-guidelines.md is pprose-guidelines.md, practical-prose-rubric.md is pprose-rubric.md, ai-prose-corrections.md is ai-tells.md. Principles, metrics, and runbooks are not vendored; ignore links to them.

Steps

  1. Refuse generated files. If the file carries a DO NOT EDIT, @generated, or "generated by" marker, or sits in a generated-output path, stop. Name the generator or source file and say to review that instead.

  2. Orient. Identify the reader, the doc type, the task the reader will do with it, and the risk level. Read the doc in full before scoring. Frontmatter and HTML comments are metadata, not prose defects.

  3. Score all 20 dimensions per the decision tree in pprose-rubric.md: NA if the per-dimension NA anchor fits, ERR only for a procedural failure, else 1-5. Honor the cascades (Verifiability to Factuality, Suitability to Relevance, Soundness to Parsimony). For every score below 5, cite the specific guideline rule missed from pprose-guidelines.md. A documented justified deviation (see rubric) is not a defect; note it and do not penalize it.

  4. Check common-doc-guidelines.md. File structure, headings, lists, links, and Markdown formatting problems become Form findings (Organization, Consistency, Formatting). Heading-case and list-punctuation rules yield to the doc's or repo's existing consistent convention; raise only inconsistency.

  5. Check diagrams per diagrams.md. Where the doc describes architecture, a flow, states, or more than three interacting components in prose and has no figure, add a finding with class diagram. Use the dimension the gap hurts most, usually Clarity or Organization.

  6. Classify each finding with pprose's apply-vs-flag rule:

    • apply: safe and meaning-preserving. Expression and Form findings, including tells from ai-tells.md, whose fix cannot change meaning, claim strength, or scope. fix-doc auto-applies these rows.
    • flag: substantive and judgment-bearing. Every Purpose, Reasoning, Grounding, and Judgment finding. Also any Expression or Form finding whose fix would alter meaning, claim strength, or scope (for example, a Concision cut that removes a caveat). Needs the author or new facts; never present as decided.
    • diagram: a figure to add (step 5).

    When a defect fits two classes, file it at the shallowest class that fully fixes it, but a possible meaning change always makes it flag. When unsure whether a fix preserves meaning, use flag.

Rules

  • No footer. Ignore footer-presence criteria when scoring; never mark a dimension NA for that reason. Never raise a footer finding.
  • Every score below 5 has a Missed rule; every finding names a concrete, locatable Fix. No generic advice ("improve clarity").
  • Each Findings row ties to a Scores row below 5. One dimension may have several findings.
  • Quote or point to the actual text in Location. Format: <heading › paragraph or line>, for example Rollout › para 2 or Setup › L41.
  • For flag findings, Fix states what the author must supply or decide, not an invented fact.
  • Do not invent dimension names; use exactly the 20 in the table below.

Output

Print exactly two tables, ## Scores then ## Findings, with these column names and class values. Other skills parse them.

## Scores
| Group | Dimension | Score | Missed rule |
|---|---|---|---|
| Purpose | Suitability | 4 | <guideline rule, required when < 5> |

## Findings
| ID | Dimension | Location | Class | Issue | Fix |
|---|---|---|---|---|---|
| F1 | Clarity | Setup › para 2 | apply | <what is wrong> | <concrete change> |

Scores has 20 rows, grouped in this order. Score is 1-5, NA, or ERR; Missed rule is - when the score is 5, NA, or ERR.

Group Dimensions
Purpose Suitability, Scope, Breadth, Depth
Expression Clarity, Coherence, Concision
Form Organization, Consistency, Formatting
Reasoning Discipline, Soundness, Precision, Parsimony
Grounding Verifiability, Factuality, Relevance
Judgment Calibration, Fairness, Robustness

Findings IDs run F1, F2, ... in document order. Class is exactly apply, flag, or diagram. If there are no findings, print the Scores table and a Findings table with header only.

End with: "Run fix-doc to apply these findings?"

04 同仓库更多 Skills

ozzycodes2
ozzycodes2/claudellum

writing-design-docs

Use when the user wants to write a problem-statement design doc, says "let's plan a feature properly" / "write a design doc" / "I'm thinking about how to do X" for a non-trivial X, or before committing to a non-obvious technical direction

★ 1
ozzycodes2
ozzycodes2/claudellum

write-doc

Use when the user asks to write or draft a README, ADR, runbook, tutorial, how-to, explanation, or reference doc, or a caller passes "type ADR" or "type README". Picks the type, fills a template, adds diagrams. RFCs and design docs belong to writing-design-docs.

★ 1
ozzycodes2
ozzycodes2/claudellum

fix-doc

Use when the user asks to fix, edit for prose quality, polish, tighten, humanize, or de-slop a Markdown doc or pasted text, or says "make this read less AI". Applies review-doc findings, generates flagged diagrams, lists substantive issues for the author, then runs the AI-tell pass last. Modifies the target.

★ 1
ozzycodes2
ozzycodes2/claudellum

create-slides

Use when the user asks for a slide deck, presentation, talk, or slides from a document, report, PR, notes, or topic. Builds one self-contained Machinify-branded HTML deck in a minimalist style, with headline-plus-visual slides, speaker notes, and every diagram drawn by architecture-design:create-diagram.

★ 1
ozzycodes2
ozzycodes2/claudellum

start-session

Open a Claude Code working session in a fresh, isolated git worktree, so the user can start a task with a single /start-session <name>. Use at the START of a session when the user says "start session", "start a worktree", "spin up a worktree for ABC-123", "begin work on <ticket>", or passes a name/ticket to work under. Creates and ENTERS a worktree via the EnterWorktree tool (never `git worktree add`) under .claude/worktrees/, named exactly after the argument, on a local branch `worktree-<argument>`. Reports what the worktree inherited (`.worktreeinclude` copies, symlinked node_modules) and whether its `.env` still points at the main checkout's stack. If the argument is a JIRA key (e.g. ABC-123, PROJ-1505), also loads that story with the Atlassian CLI (`acli`) when available and summarizes the implementation ask. Also renames the session to the argument (the same effect as `/rename <NAME>`) so it's easy to find in `/resume`. Then stops and waits — it sets up the workspace and context, it does not implement.

★ 1
ozzycodes2
ozzycodes2/claudellum

exit-session

Tear down the ephemeral resources a Claude Code working session created, then quit the CLI — so the user can wrap up with a single /exit-session. Use when the user says "exit session", "clean up this session", "tear down everything", "wrap up and clean up resources", "remove the worktree and scratch", "stop the background processes", "shut down the stack", "clean up the agent worktrees", or asks to clean up after finishing a task — even if they only name one resource (assume they want the full sweep unless they scope it). Runs teardown permission-free: stops background processes and dev servers, Docker/compose stacks plus their volumes, networks and images, local Tilt/Kubernetes, git worktrees, merged local branches, and temp/scratch files without prompting, then exits the CLI. Covers the worktrees and Docker resources left behind by subagents spawned during the session, not just the primary agent's own worktree — both determined from git locks and Docker labels rather than from recall. Never touches resources a still-live session holds.

★ 1