document-review

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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: <recognized-value>` 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 <file>
```

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: <filename>
Lint: PASSED | SKIPPED (non-HOTL document)
AI Review: No issues found.

From yimwoo/hotl-plugin, MIT.

More from yimwoo/hotl-plugin