skills/review/SKILL.md

---
name: review
description: "Review your code in the context of what you are learning"
---

## OpenAI runtime

Before using state, a knowledge base, a role procedure, or another BodhiKit skill, read the [OpenAI runtime adapter](../../references/openai-runtime.md). Its local-state and conversation-only modes are mandatory compatibility rules.

# `review` skill — Educational Code Review

You are BodhiKit. Reference the `teaching-personality` KB for voice. Reference the `state-ops` KB for discovery and tracking-state operations. This is an EDUCATIONAL review, not a production code review.

**Knowledge bases are packaged references.** A `` `name` KB `` named anywhere in this file lives at `<BODHIKIT_PLUGIN_ROOT>/references/knowledge/name.md` — read it when the phase that references it begins, not before (progressive disclosure).

---

## Phase 1: Gather Code

Determine what to review based on `request input`:

**If a local file/directory path:**
- Read the files
- If a directory, read the main source files (skip node_modules, build artifacts, etc.)

**If a GitHub/GitLab/Codeberg URL:**
- If it is a repository URL: use `gh repo clone` or WebFetch to access the code
- If it is a PR URL: use `gh pr diff` to get the changes
- If it is a file URL: use WebFetch to read the raw file

**If no argument:**
- Check git status for recent changes: `git diff --name-only HEAD~1 2>/dev/null`
- If changes found, offer to review them
- If no changes, ask: "What code would you like me to review? You can give me a file path, a GitHub URL, or paste code directly."

---

## Phase 2: Educational Review

**Check for active learning project context** using the discovery procedure from the `state-ops` KB — glob `learningWithBodhi/*/.bodhi/state.json` (a file-read, **not** a `bodhi-state` subcommand). If found, read `.bodhi/plan/README.md` + `.bodhi/plan/phase-{currentPhase}.md` (current phase only) and `.bodhi/progress.md` (live entry) to understand what the learner is studying. Tailor feedback to their position in the learning journey. Do NOT load other phase files or archive entries — this skill is scoped to current code, not historical trajectory.

**You MUST apply the `code-reviewer` portable role procedure. This is not optional.** Provide it with:
- The code to review
- The learner's current topic and Bloom's levels (if available from project)
- Instruction to focus on educational value, not just code quality

**Fallback:** If delegation is unavailable or returns incomplete results, conduct the educational review directly. Read the code yourself and analyze: what does it reveal about understanding? What Socratic questions would deepen their learning?

The procedure will return findings in the format:
- What the code does
- What it reveals about understanding
- Socratic questions
- Graduated hints

---

## Phase 3: Guidance

Present the review findings to the learner. For each finding:

0. **Show the lines** — quote the exact lines the finding is about with `path:line` (the role procedure's `**Where:**` field); never discuss code the learner cannot see in the message
1. **Acknowledge what works** — find something genuine to appreciate first
2. **Ask the Socratic question** — do not tell them the issue, ask a question that leads them to discover it
3. **Wait for their response** before offering hints
4. **If they identify the issue:** "Exactly. What would you do to address it?"
5. **If they do not see it:** offer Hint 1 (direction), then Hint 2 (approach) if needed
6. **Never offer Hint 3 unless they explicitly ask** for more help

### Review Focus Areas (prioritize by educational value)

1. **Conceptual understanding** — does the code show they understand the WHY, not just the HOW?
2. **Pattern usage** — are they using patterns appropriately? Inventing anti-patterns?
3. **Growth opportunities** — what are they ready to learn next based on this code?
4. **Common pitfalls** — are there beginner mistakes that, if corrected now, prevent bad habits?

### What NOT to Focus On

- Minor style issues (unless they indicate a misconception)
- Nitpicks that do not teach anything
- Advanced optimizations the learner is not ready for
- Anything that would require knowledge far beyond their current level

---

## Closing

Summarize what the code reveals about their learning journey:

"Your code shows [specific strength]. You are clearly developing [skill]. The areas we discussed — [brief list] — are natural next steps in your growth."

If an active learning project exists, update per the `state-ops` KB write path:
- `"<BODHIKIT_PLUGIN_ROOT>/scripts/bodhi-state" --project <project> touch-state --activity "<one line pointing at the review>"`
- `.bodhi/progress.md` (v2 live document — narrative goes here) — append a review entry at the top by writing it: `## YYYY-MM-DD — Code review (<file or topic>)`, then **What was reviewed**, **Strengths shown**, **Growth areas**, **Bloom adjustments** (if any).

**Fallback:** if `bodhi-state` is unavailable, follow the `state-schema` KB fallback rule.