Code review
Use after completing implementation steps and before merging — reviews against plan and HOTL contracts.From its SKILL.md
npx -y skills add yimwoo/hotl-plugin --skill code-reviewAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
SKILL.md
6.4 KB, as published. Nobody here has run it
HOTL Code Review
User-facing entry point for getting a code review. Dispatches the full code-reviewer agent by default; falls back to inline review when subagents aren't available.
Process
1. Gather Context
Resolve base branch (fallback ladder — use the first that succeeds):
- PR base branch:
gh pr view --json baseRefName - Repo default branch:
git symbolic-ref refs/remotes/origin/HEAD mainmaster
Resolve review scope:
- Feature branch: committed branch diff against base (
base...HEAD), plus staged and unstaged local changes when present - On base branch with staged changes: staged diff
- On base branch with unstaged changes: working tree diff
- On clean base branch:
HEAD~1..HEAD - Ambiguous (detached HEAD, no commits beyond base, no local changes): ask the user
Detect workflow file:
- First, glob for canonical workflows in
docs/plans/*-workflow.md - If one canonical match: use it
- If multiple canonical matches: prefer the most recently modified canonical workflow, unless the user named one
- If no canonical matches: glob for legacy
hotl-workflow-*.mdin project root - If one legacy match: use it
- If multiple legacy matches: prefer the most recently modified legacy workflow, unless the user named one
- If no matches: proceed without workflow context
Extract contracts from workflow frontmatter if available (intent, constraints, success_criteria, risk_level).
Gather verification evidence:
- Primary (deterministic):
.hotl/state/*.jsonand.hotl/reports/*.md— most recent artifacts if present - Best-effort: recent test/lint output if discoverable; if unavailable, report "not available"
2. Dispatch Review
If subagents are available (Claude Code, Codex):
Dispatch the code-reviewer role as a subagent via the Agent tool. Use the structured dispatch template from requesting-code-review:
- Review type:
direct - Git range: resolved scope from step 1
- Workflow and contracts: if available
- Verification evidence: if available
If subagents are not available (Cline, weaker runtimes):
Run inline review in the current session using the same output contract. See "Inline Fallback" below.
3. Return Findings
- Present the review output (findings + verdict) to the user
- Do NOT automatically invoke
receiving-code-review - Do NOT automatically implement fixes
- If the user asks to fix the findings ("fix them", "address these", "implement the fixes"): then invoke
receiving-code-review
Verdict Model
Direct reviews use the final-review verdict model:
- READY — safe to merge
- READY WITH WARNINGS — safe to merge but warnings should be addressed soon
- NOT READY — blocking issues must be resolved before merge
Review Lifecycle
code-review = user-facing entry point for getting a review
requesting-code-review = internal executor/orchestration entry point
receiving-code-review = follow-up handler for acting on findings
Output Contract
Both dispatched and inline reviews must conform to docs/contracts/code-review-output.md. Every review must contain these 6 sections in order: Scope (with verification evidence), Reviewed Dimensions, Findings, What Was Not Covered, Residual Risks, Verdict.
Platform-Native Annotation Dedup
When the platform emits platform-native annotations for localized findings (e.g., ::code-comment in Codex, inline GitHub review comments), do not restate those findings verbatim in the Findings section. Instead, use the grouped one-liner format defined in the output contract.
Inline Fallback
When subagents are not available, run the review inline using the same output contract. The inline review must produce identical 6-section structure — not a weaker format.
Dimensions
Plan alignment (when workflow provided):
- All steps in the workflow file completed
- success_criteria from frontmatter met
- No unplanned scope added (YAGNI)
When no workflow: state "Plan alignment: skipped (no workflow provided)"
Code quality and design:
- Tests exist and pass for all new behavior
- No code duplication introduced (DRY)
- Error handling at system boundaries only
- Reference
docs/checklists/architecture-and-design.mdfor SOLID and architecture smell heuristics. If the checklist file is not available, continue with best-effort review.
Security and reliability:
- Reference
docs/checklists/security-and-reliability.mdfor expanded security heuristics. - Check for injection, auth gaps, race conditions, secret leakage, unsafe patterns.
- If the checklist file is not available, continue with best-effort review.
Performance and boundary conditions:
- Reference
docs/checklists/performance-and-boundary-conditions.mdfor performance and boundary condition heuristics. - Check for N+1 queries, unbounded memory, off-by-one, null handling, swallowed exceptions.
- If the checklist file is not available, continue with best-effort review.
Removal and simplification:
- Reference
docs/checklists/removal-and-simplification.mdfor dead code and simplification heuristics. - Flag unused exports, dead branches, feature-flagged-off code. Classify as safe-delete-now or defer-with-plan.
- If the checklist file is not available, continue with best-effort review.
HOTL governance:
- risk_level: high steps had human gate approval
- No sensitive data (secrets, PII) in code, logs, or comments
- Security-sensitive paths (auth, encryption) have human review documented
Findings Format
Every finding must include:
- [SEVERITY]: file/path:line — description
Why: [why this matters]
Fix: [expected remediation direction]
For localized issues: file:line is required. For scope-level findings: provide the narrowest evidence available.
Severity Levels
- BLOCK: Must fix before merge (failing tests, security issues, missing gates on high-risk steps)
- WARN: Should fix soon (code quality, missing docs for public APIs)
- NOTE: Consider in future (style, minor improvements)
BLOCK issues must be resolved before claiming done.
Clean Review
Per the output contract, when a dimension has no findings it must still state what was checked, what was not covered, and residual risks. Additionally, the review must always include sections 4 (What Was Not Covered) and 5 (Residual Risks) even when no individual dimension has findings.