# Document Review > Optional utility for reviewing existing docs, external specs, hand-authored notes, or non-HOTL documents. HOTL design docs and workflows get structural lint + AI review; other documents get AI-only review with a generic rubric. - Skill: `thedixitjain/document-review` (Agent Skill) - Install (CLI): `npx skillmds add thedixitjain/document-review` - Raw SKILL.md: https://api.skillmd.com/api/skills/thedixitjain/document-review/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: thedixitjain (https://skillmd.com/u/thedixitjain) - Updated: 2026-09-08 - Page: https://skillmd.com/skills/thedixitjain/document-review --- # HOTL Document Review ## Overview Optional utility for ad hoc document review. Use this to review existing docs, external specs, hand-authored plans, or any non-HOTL document. HOTL documents get structural lint (hard gate) followed by AI review. Non-HOTL documents skip lint and go straight to AI review with a generic rubric. **Note:** This skill is not required in the standard HOTL flow. Writing-plans includes a built-in self-check, and execution preflight runs structural lint automatically. Use this skill when you want to review a document outside of the normal plan-then-execute cycle. **Announce:** "Running document review. Classifying input..." ## Step 0 — Classify the Input Before doing anything else, classify the input into one of four categories: | Category | Detection | Review Path | |---|---|---| | **HOTL workflow** | Canonical `docs/plans/*-workflow.md` or legacy `hotl-workflow-*.md` | Phase 1 (HOTL lint, hard gate) → Phase 2 (HOTL AI review) | | **HOTL design doc (marked)** | A design-doc-shaped file (canonical `docs/designs/*.md` or legacy `*-design.md` / `*-plan.md`) whose YAML frontmatter declares `design_type:` (one of `feature \| phase \| initiative \| architecture \| contract \| reference`) OR `hotl_managed: true` | Phase 1 (HOTL lint) → Phase 2 (HOTL AI review) | | **Generic text/markdown** | Any other `.md`, `.txt`, or pasted text — including design-shaped files in `docs/designs/` that lack an HOTL marker | Skip Phase 1 → Phase 2 (generic AI review) | | **PDF** | `.pdf` extension | If the current runtime can read/extract the content, treat as generic text and review. Otherwise, ask the user for a text, markdown, or PDF-text export. | | **DOCX / PPTX / binary** | `.docx`, `.pptx`, or other binary formats | **STOP.** Ask the user for a markdown, plain text, or PDF export. Do not attempt conversion. | **Phase 1.6 opt-in rule:** Path alone does NOT classify a file as HOTL. A design-shaped Markdown file in `docs/designs/` without an HOTL frontmatter marker (`design_type:` or `hotl_managed: true`) is treated as generic markdown — `document-lint.sh` will SKIP it cleanly, and this skill routes it through Phase 2's generic-rubric AI review. To opt a hand-authored design doc into HOTL strict review, add `design_type: ` or `hotl_managed: true` to its frontmatter. **Announce the classification:** e.g., "Classified as HOTL design doc (marked via design_type) — running lint + HOTL review." or "Classified as generic markdown — skipping lint, running generic review." ## Phase 1: Structural Lint (HOTL Documents Only) **Skip this phase entirely for non-HOTL documents.** If the input was classified as generic text/markdown or PDF, go directly to Phase 2 (generic AI review). For HOTL documents only, run the deterministic lint script: ```bash bash scripts/document-lint.sh ``` Resolve `document-lint.sh` in this order: 1. If you are working in the `hotl-plugin` repo itself, use `scripts/document-lint.sh` 2. Codex native-skills install: `~/.codex/hotl/scripts/document-lint.sh` 3. Codex plugin install: `~/.codex/plugins/hotl-source/scripts/document-lint.sh` 4. Codex plugin cache fallback: `~/.codex/plugins/cache/codex-plugins/hotl/*/scripts/document-lint.sh` 5. Cline install fallback: `~/.cline/hotl/scripts/document-lint.sh` 6. Claude Code plugin fallback: `~/.claude/plugins/hotl/scripts/document-lint.sh` Do not assume `scripts/document-lint.sh` exists in the repo being reviewed. The lint script lives in the HOTL install, not in arbitrary user projects. #### Resolving `hotl-config.sh` `hotl-config.sh` (the canonical reader for `.hotl/config.yml`) follows the same six-location resolution order as `document-lint.sh`: 1. If you are working in the `hotl-plugin` repo itself, use `scripts/hotl-config.sh` 2. Codex native-skills install: `~/.codex/hotl/scripts/hotl-config.sh` 3. Codex plugin install: `~/.codex/plugins/hotl-source/scripts/hotl-config.sh` 4. Codex plugin cache fallback: `~/.codex/plugins/cache/codex-plugins/hotl/*/scripts/hotl-config.sh` 5. Cline install fallback: `~/.cline/hotl/scripts/hotl-config.sh` 6. Claude Code plugin fallback: `~/.claude/plugins/hotl/scripts/hotl-config.sh` Do not assume `scripts/hotl-config.sh` exists in the repo being reviewed. Callers that do not know their install location should invoke `scripts/hotl-config-resolve.sh` (a thin command proxy that locates `hotl-config.sh` and forwards argv). **If lint FAILS:** STOP. Show all errors. The author MUST fix structural issues before AI review runs. Do not proceed. **If lint PASSES:** Continue to Phase 2 (HOTL AI review). ### What Lint Checks **Design docs (canonical `docs/designs/*.md`, plus legacy `*-design.md` / `*-plan.md` tactical docs):** - Intent Contract with intent, constraints, success_criteria, risk_level - Verification Contract with at least one verify step - Governance Contract with approval_gates and rollback - risk_level is low, medium, or high **Workflow files (canonical `docs/plans/*-workflow.md`, plus legacy `hotl-workflow-*.md`):** - YAML frontmatter with intent, success_criteria, risk_level - Every step has action and loop fields - Every looped step (loop: until) has verify and max_iterations - Preferred workflow step syntax is `- [ ] **Step N: ...**`, though legacy `### N.` headings may still appear - High-risk steps with security keywords have gate: human ## Phase 2: AI-Driven Review (Soft Gate) Read the full document and evaluate using the rubric that matches the classification: ### For Design Docs 1. **Internal consistency** — Do the three contracts align with each other? Does the verification contract actually test the intent? 2. **YAGNI** — Is anything speculative, overbuilt, or solving problems that don't exist yet? 3. **Risk assessment** — Is the risk_level appropriate? Are high-risk areas (auth, encryption, billing) correctly identified? 4. **Success criteria** — Are they concrete and testable, or vague? 5. **Scope** — Does this cross too many subsystems? Should it be decomposed? ### For Workflow Files 1. **Step sizing** — Are steps atomic (2-5 minutes each)? Flag steps that are too large or vague. 2. **Verify coverage** — Do verify commands actually test what the step claims to do? 3. **Gate placement** — Are human gates placed at the right points? Any risky steps missing gates? 4. **Loop safety** — Are max_iterations reasonable? Any infinite-loop risks? 5. **Ordering** — Do steps build on each other logically? Any missing dependencies? ### For Generic Documents 1. **Clarity** — Is the writing clear, specific, and unambiguous? 2. **Completeness** — Are important details, assumptions, or decisions missing? 3. **Internal consistency** — Does the document contradict itself anywhere? 4. **Actionability** — Are decisions, next steps, owners, or open questions clearly stated? 5. **Risk / Ambiguity** — Are there risky assumptions, vague areas, or likely points of confusion? ## Review Outcomes After completing the review, output exactly one of the following. Use `Lint: PASSED` for HOTL documents or `Lint: SKIPPED (non-HOTL document)` for all other inputs. ### PASS All checks satisfied. Document is ready. ``` REVIEW: PASS Document: Lint: PASSED | SKIPPED (non-HOTL document) AI Review: No issues found. Ready for execution. ``` ### REVISE Issues found that should be fixed. List each with a specific suggestion. ``` REVIEW: REVISE Document: Lint: PASSED | SKIPPED (non-HOTL document) AI Review: issue(s) found. Issues: 1. [ISSUE]: Suggestion: 2. [ISSUE]: Suggestion: Fix these issues and re-run document review. ``` ### HUMAN_OVERRIDE_REQUIRED Serious concerns that the AI cannot resolve. Human must decide whether to proceed. ``` REVIEW: HUMAN_OVERRIDE_REQUIRED Document: Lint: PASSED | SKIPPED (non-HOTL document) AI Review: Serious concern(s) requiring human judgment. Concerns: 1. [CONCERN]: Risk: 2. [CONCERN]: Risk: Do not continue until a human explicitly says to override these concerns. ``` ## Rules - Always classify the input before choosing a review path. - For HOTL documents: never skip lint; never continue to execution when lint fails. - For non-HOTL documents: skip lint entirely (no structural validation). - For DOCX/PPTX/binary: do not attempt conversion; ask for an export. - If review outcome is `REVISE`, the author fixes the document first. - If review outcome is `HUMAN_OVERRIDE_REQUIRED`, only an explicit human decision allows execution to proceed. --- **Source:** [`hashgraph-online/awesome-codex-plugins`](https://github.com/hashgraph-online/awesome-codex-plugins) → `plugins/yimwoo/hotl-plugin/skills/document-review/SKILL.md`