code-review

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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.

From yimwoo/hotl-plugin, MIT.

More from yimwoo/hotl-plugin