# Code Review

> Use after completing implementation steps and before merging — reviews against plan and HOTL contracts.

- Skill: `thedixitjain/code-review-5` (Agent Skill)
- Install (CLI): `npx skillmds add thedixitjain/code-review-5`
- Raw SKILL.md: https://api.skillmd.com/api/skills/thedixitjain/code-review-5/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-09
- Page: https://skillmd.com/skills/thedixitjain/code-review-5

---



# 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):

1. PR base branch: `gh pr view --json baseRefName`
2. Repo default branch: `git symbolic-ref refs/remotes/origin/HEAD`
3. `main`
4. `master`

**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-*.md` in 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/*.json` and `.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.md` for 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.md` for 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.md` for 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.md` for 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.

---

**Source:** [`hashgraph-online/awesome-codex-plugins`](https://github.com/hashgraph-online/awesome-codex-plugins) → `plugins/yimwoo/hotl-plugin/skills/code-review/SKILL.md`