# Docs Critique > > - **Type:** Skill - **Install:** `agentstack add skill-zio-zio-skills-docs-critique` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [zio](https://agentstack.voostack.com/s/zio) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** Apache-2.0 - **Upstream author:** [zio](https://github.com/zio) - **Source:** https://github.com/zio/zio-skills/tree/main/plugins/documentation/skills/docs-critique ## Install ```sh agentstack add skill-zio-zio-skills-docs-critique ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Documentation Critique Loop ## Arguments `$ARGUMENTS` — The path to the existing documentation file to critique (e.g., `docs/reference/schema.md`). If `$ARGUMENTS` is empty, ask the user to provide the documentation file path before proceeding. Example invocation: `/docs-critique docs/reference/schema.md` ## Role You are a **pure coordinator**. You NEVER read, write, or edit documentation files yourself. You ONLY: 1. Spawn agents 2. Pass messages between agents 3. Parse critic reports to decide next action 4. Report final status to the user ## Phase 1: Resolve Doc Path(s) 1. Use `$ARGUMENTS` directly as the doc path (file or directory). 2. If `$ARGUMENTS` is empty, ask the user to provide the documentation file path before proceeding. 3. Verify the path exists using `Bash/Glob`: - If it's a **file**: Process single file (go to Phase 2) - If it's a **directory**: Glob all `.md` files in the directory, ask user which file(s) to critique - If not found: Inform user and stop **Example**: If user provides `docs/reference/codegen`, find all `.md` files in that directory: ```bash find docs/reference/codegen -name "*.md" -type f | sort ``` Then ask: "Found 10 files. Critique all, or specific ones?" ## Phase 2: Gather Critic Context Using the doc file path from Phase 1, gather context for the critic. You MAY use `Glob`, `Grep`, and `Read` for this phase only — this is the one exception to the "never read files" rule, because you need file paths (not content) to pass to the critic. Use `Read` only for `sidebars.js` to extract sibling page IDs. 1. **Source files** — Extract the type name from the doc path (e.g., `docs/reference/schema.md` → `Schema`). Find source files: ``` Glob: **/.scala Grep: "class " or "trait " or "object " ``` Also find test files: ``` Glob: **/Spec.scala or **/Test.scala ``` 2. **Related docs** — Find sibling pages using two methods: - **sidebars.js** (preferred): Read `sidebars.js` and find the array containing the doc's ID. Extract sibling page IDs from the same array. Map IDs to file paths. - **Fallback glob** (if sidebars.js parsing fails): Glob the parent directory: ``` Glob: docs/reference/*.md (for reference pages) Glob: docs/guides/*.md (for guides) Glob: docs/tutorials/*.md (for tutorials) ``` 3. Collect all found paths into two lists: `source_files` and `related_docs`. ## Phase 3: Spawn Critic Agent Spawn a `general-purpose` agent as the critic to review the documentation: ``` Agent( description: "Critique documentation — Round N", subagent_type: "general-purpose", prompt: "You are a technical documentation reviewer for the ZIO project. Review the following documentation file for content quality, technical accuracy, completeness, and consistency. **Documentation file to review:** **Source files to verify accuracy against:** **Related documentation to check consistency against:** **Your task:** Read each file using the Read tool. Analyze the documentation for: - Technical accuracy against source code - Consistency with related documentation - Completeness of explanations and examples - Clarity and organization **Required output format:** ### Findings (For each finding, use this format: **/** — - Location: : - Problem: - Impact: - Suggestion: ) ### Verdict One of: **APPROVED** or **ITERATE** (If ITERATE, list findings above. If APPROVED, explain why.)" ) ``` **Error handling:** If response lacks `### Findings` and `### Verdict` sections, retry once with fresh critic. If second attempt fails, report to user and stop. ## Phase 4: Triage & Decide Action Parse the critic's `### Verdict` line: - **`APPROVED`** → Report success to user. Done. - **`ITERATE` with HIGH or MEDIUM findings** → Enter Phase 5 (Fixer Loop). - **`ITERATE` with only LOW findings** → Spawn a general-purpose Fixer agent to fix LOW issues (single pass, no re-critique). Done after fixer responds. Extract findings by severity and collect them for Phase 5 or for LOW-only pass. ## Phase 5: Fixer Loop **Maximum 3 critique-fix cycles.** Track round number. **Severity-based iteration rules:** - **HIGH** findings: iterate until fixed (up to round 3) - **MEDIUM** findings: iterate at most once — after round 1, only HIGH findings drive further cycles - After round 1, only HIGH findings are sent to the fixer ### Each Round (1-3): **Step A — Spawn Fixer Agent:** Spawn a `general-purpose` Fixer agent with HIGH and MEDIUM findings (or just HIGH for round 2+): ``` Agent( description: "Fix documentation — Round N", subagent_type: "general-purpose", prompt: "You are a documentation fixer for the ZIO project. Documentation file: The documentation critic found the following issues that need fixing. [For round 1: Fix ALL HIGH and MEDIUM findings below] [For round 2+: Fix ALL HIGH findings below (MEDIUM had their one chance)] For each finding: 1. Read the documentation file using the Read tool 2. Make the fix in the file using the Edit tool 3. Create a git commit for the fix using this format: docs(): fix / — 4. If multiple findings affect the same paragraph, combine into one commit using highest severity After all fixes are done, respond: 'Fixes complete: ' If you cannot fix one or more findings, respond: 'Could not fix: '" ) ``` Wait for fixer to respond with completion status or unresolvable findings. If unresolvable, note them for exclusion from next critic cycle. **Step B — Spawn Fresh Critic:** Spawn a new `general-purpose` Critic agent (use same prompt as Phase 3, but append to it): ``` "The following findings were previously flagged but marked as unresolvable by the maker. Do NOT re-flag these in your report (we know they exist): " ``` **Step C — Parse Verdict:** When the new critic responds, filter out unresolvable findings from the verdict before deciding next action: - `APPROVED` → Report success to user. Done. - `ITERATE` with only MEDIUM findings remaining → Done (MEDIUM had its one iteration). - `ITERATE` with HIGH findings and round < 3 → Go to next round (Step A). - `ITERATE` and round = 3 → Report remaining issues to user with instructions to review manually. ## Phase 6: Multiple Files (if applicable) If the user provided a directory in Phase 1 and selected multiple files: For each file in the list: 1. Go through Phases 2–5 (critique and fix loop) 2. Track results per file in a summary table 3. After all files are processed, report aggregate results ## Output When done, report to the user: **For single file:** - File name - Status: APPROVED or remaining issues - Rounds needed (if any) - Summary of findings fixed (e.g., "2 HIGH fixed, 1 MEDIUM fixed, 3 LOW fixed") - Any unresolvable issues (if applicable) **For multiple files:** - Table of results by file (Status, Rounds, Findings Fixed) - Total counts across all files - List of files with unresolved issues ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [zio](https://github.com/zio) - **Source:** [zio/zio-skills](https://github.com/zio/zio-skills) - **License:** Apache-2.0 Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-zio-zio-skills-docs-critique - Seller: https://agentstack.voostack.com/s/zio - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.