mpy-review

MicroPython Review Assistant Skill

Purpose

This skill provides AI-assisted code review for MicroPython using historical review patterns from the lead maintainer. It searches a database of ~19.5K categorized review comments to find relevant examples and generate review context.

Note: When the mpy-reviewer MCP server is available (registered in .claude/settings.json), prefer using MCP tools directly (review_diff, search_reviews, etc.) instead of the CLI. The MCP server keeps the embedding model warm across calls, eliminating 2-3s cold start per query. This skill remains as a fallback for sessions outside the project scope.

IMPORTANT: The review_diff MCP tool accepts diffs of any size. Do NOT fall back to CLI because a diff seems "too large". Pass the full diff text directly as the diff_text parameter regardless of length. The tool internally splits multi-file diffs into per-file chunks for embedding, so large diffs are handled efficiently.

MCP file-based output: The MCP review_diff and review_pr tools return a compact orchestration prompt (~5-8K) instead of raw data. Review examples are written to individual temp files under /tmp/mpy-review-*/. The prompt includes a summary table with file paths, sizes, severities, and domains. To use the examples:

• Read small files (<2KB) directly with the Read tool
• For large files (>2KB), consider spawning subagents to process them in parallel
• The diff is NOT echoed back — you already have it in context from when you generated it

When to Use This Skill

Invoke this skill when the user:

• Wants to review code changes (branches, commits, diffs, PRs)
• Asks for maintainer-style feedback on their code
• Wants to find examples of specific review patterns
• Needs review context for MicroPython code
• Mentions reviewing, feedback, or code quality for MicroPython

Important: Users cannot invoke skills directly. They must ask you to use the skill:

• User: "Can you review my current branch?"
• User: "Can you /mpy-review the current branch?"

When the user asks for review help, invoke this skill proactively.

Requirements

This skill requires codanna for semantic code search and codebase analysis.

Automatic setup: A SessionStart hook automatically installs codanna via cargo on first use.

Manual installation:

cargo install codanna --all-features

If codanna is not installed, the tool will fail with a prominent error message directing the user to install it.

Tool Location

The underlying CLI tool is located at:

uv run --project ${CLAUDE_PLUGIN_ROOT} mpy-reviewer

Always use this full path when invoking the tool. Do not rely on PATH.

Understanding User Intent

Parse natural language requests and map to appropriate tool commands:

Review Current Changes

User says: "review my current changes", "review this branch", "review what I've done"

What to do:

1. Generate diff: git diff main (or appropriate base branch)
2. Pipe to tool: git diff main | uv run --project ${CLAUDE_PLUGIN_ROOT} mpy-reviewer review --stdin --codebase --output prompt
3. Present the review prompt to help the user

Example:

git diff main | uv run --project ${CLAUDE_PLUGIN_ROOT} mpy-reviewer review --stdin --codebase --output prompt

Review Specific Commit

User says: "review commit abc123", "check commit abc123"

What to do:

1. Get commit diff: git show abc123
2. Pipe to tool: git show abc123 | uv run --project ${CLAUDE_PLUGIN_ROOT} mpy-reviewer review --stdin --output prompt

Example:

git show ca65d543 | uv run --project ${CLAUDE_PLUGIN_ROOT} mpy-reviewer review --stdin --codebase --output prompt

Review Uncommitted Changes

User says: "review my uncommitted changes", "review staged changes"

What to do:

# All uncommitted changes (staged + unstaged)
git diff HEAD | uv run --project ${CLAUDE_PLUGIN_ROOT} mpy-reviewer review --stdin --output prompt

# Only staged changes
git diff --cached | uv run --project ${CLAUDE_PLUGIN_ROOT} mpy-reviewer review --stdin --output prompt

Review GitHub PR

User says: "review PR 12345", "check pull request 12345"

What to do:

uv run --project ${CLAUDE_PLUGIN_ROOT} mpy-reviewer review --pr 12345 --codebase --output prompt

Review Specific Files

User says: "review my changes to py/gc.c", "review changes in extmod/"

What to do:

git diff main -- py/gc.c | uv run --project ${CLAUDE_PLUGIN_ROOT} mpy-reviewer review --stdin --output prompt

git diff main -- extmod/ | uv run --project ${CLAUDE_PLUGIN_ROOT} mpy-reviewer review --stdin --codebase --output prompt

Find Review Examples

User says: "find examples of memory allocation reviews", "show me feedback on error handling"

What to do:

uv run --project ${CLAUDE_PLUGIN_ROOT} mpy-reviewer search "memory allocation" --domain memory -k 10

uv run --project ${CLAUDE_PLUGIN_ROOT} mpy-reviewer search "error handling" --domain correctness -k 10

Get Quick Context (No Full Prompt)

User says: "show me similar reviews", "what has been said about this before"

What to do: Use --output context instead of --output prompt to get just the examples without full prompt structure:

git diff main | uv run --project ${CLAUDE_PLUGIN_ROOT} mpy-reviewer review --stdin --output context

Tool Commands Reference

Review Command

uv run --project ${CLAUDE_PLUGIN_ROOT} mpy-reviewer review [OPTIONS]

Input Options (choose one):

• --diff FILE - Review a diff file
• --pr NUMBER - Review a GitHub PR (uses gh CLI)
• --stdin - Read diff from stdin (recommended for git integration)

Quality Options:

• --codebase - Include MicroPython codebase context (definitions, patterns) [RECOMMENDED]
• --rerank - Use cross-encoder re-ranking for better relevance (slower, 5-10s on CPU)
• -k N - Number of review examples (default: 8)

Output Options:

• --output context - Just the review examples (default, quick to read)
• --output prompt - Full prompt ready for AI review (recommended for comprehensive review)
• --output json - Structured JSON output

Search Command

uv run --project ${CLAUDE_PLUGIN_ROOT} mpy-reviewer search "query" [OPTIONS]

Options:

• -k N - Number of results (default: 10)
• --domain DOMAIN - Filter by domain (see categories below)
• --severity SEVERITY - Filter by severity (blocking, suggestion, nitpick)
• --component COMPONENT - Filter by component (py_core, extmod, port_specific, etc.)
• --style-only - Only show comments that exemplify the maintainer's style
• --json - JSON output

Stats Command

uv run --project ${CLAUDE_PLUGIN_ROOT} mpy-reviewer stats

Shows index status and record count. Use this to verify the system is working.

Categories for Filtering

Domains (use with --domain)

• correctness - Logic bugs, edge cases, error handling
• code_style - Formatting, naming conventions
• api_design - Public interfaces, function design
• memory - Memory management, leaks, allocation
• performance - Speed, efficiency optimizations
• portability - Cross-platform compatibility
• documentation - Comments, docs, clarity
• testing - Test coverage, quality
• security - Security vulnerabilities
• architecture - Design patterns, structure
• build_system - Makefiles, build configuration
• error_handling - Error paths, recovery

Severities (use with --severity)

• blocking - Must fix before merge
• suggestion - Recommended improvement
• nitpick - Minor style/preference

Components (use with --component)

• py_core - Core Python runtime (py/)
• extmod - Extended modules (extmod/)
• port_specific - Port implementations (ports/)
• drivers - Hardware drivers
• tools - Build/dev tools
• tests - Test suite
• docs - Documentation
• build_system - Build configuration

Output Interpretation

Context Output (--output context)

Returns formatted markdown with:

• Review examples with diff context
• Review comments
• Domain and severity tags

Present this directly to the user to show relevant past reviews.

Prompt Output (--output prompt)

Returns a complete prompt containing:

• Review style guide
• 5-10 relevant review examples with code context
• The code to review
• Task instructions for AI review

How to use: After generating this prompt, you should:

1. Present it to the user, OR
2. Use it internally to generate a maintainer-style review yourself

Note: When using the MCP server instead of CLI, the review_diff/review_pr tools return an orchestration prompt with temp file paths rather than inlining all examples. Read the referenced files to access the full review examples.

JSON Output (--output json)

Returns structured data. Parse and present relevant fields to user.

Two-Step Verification Workflow

After generating findings, use the verify_findings MCP tool to cross-check each finding against the actual codebase before presenting results. This reduces false positives caused by pattern-matching without context.

Structured Finding Format

Findings must be formatted as a JSON array:

[
  {
    "file": "extmod/asyncio/stream.py",
    "line": 42,
    "severity": "blocking",
    "description": "POLLHUP not handled in ioctl bitmask",
    "diff_hunk": "the relevant diff hunk text"
  }
]

verify_findings Tool

verify_findings(findings, diff_text, pr_number=None, repo="micropython/micropython")

• findings: JSON array of structured findings (format above)
• diff_text: the full unified diff being reviewed
• pr_number: optional PR number
• repo: repository slug

Returns a markdown orchestration prompt with a summary table and paths to per-finding verdict files under /tmp/mpy-verify-*/.

Verdict Types

• confirmed: finding is valid; keep as-is (or with adjusted severity)
• partially_valid: finding has merit but needs adjustment; update severity/description
• false_positive: finding is wrong; drop it from the review
• inconclusive: verification could not determine validity; use your judgment

Verification Workflow

1. Generate diff (git diff, git show, etc.)
2. Call review_diff to get examples and style context
3. Read examples and analyze the diff
4. Assemble findings as a JSON array
5. Call verify_findings(findings, diff_text) to cross-check
6. Read verdict files for evidence
7. Drop false positives, adjust partially valid findings
8. Present verified findings as the final review

Workflow Examples

Example 1: User Wants General Review

User: "Can you review my current changes?"

Your response:

1. Run: git diff main | uv run --project ${CLAUDE_PLUGIN_ROOT} mpy-reviewer review --stdin --codebase --output prompt
2. Read the generated prompt
3. Use the prompt to provide maintainer-style review feedback to the user

Example 2: User Wants Quick Examples

User: "What has been said about similar code before?"

Your response:

1. Run: git diff main | uv run --project ${CLAUDE_PLUGIN_ROOT} mpy-reviewer review --stdin --output context
2. Present the review examples to the user directly
3. Summarize common themes

Example 3: User Asks About Specific Pattern

User: "Find me examples of feedback on GPIO configuration"

Your response:

1. Run: uv run --project ${CLAUDE_PLUGIN_ROOT} mpy-reviewer search "GPIO configuration" --component port_specific -k 15
2. Present the search results
3. Summarize key patterns

Example 4: User Mentions Specific Commit

User: "Review commit ca65d543"

Your response:

1. Run: git show ca65d543 | uv run --project ${CLAUDE_PLUGIN_ROOT} mpy-reviewer review --stdin --codebase --output prompt
2. Use the prompt to provide review feedback
3. Highlight key issues found from similar past reviews

Example 5: User Asks to Review Specific File

User: "Can you review my changes to py/gc.c?"

Your response:

1. Run: git diff main -- py/gc.c | uv run --project ${CLAUDE_PLUGIN_ROOT} mpy-reviewer review --stdin --codebase --output prompt
2. Provide targeted review focusing on that file
3. Reference relevant review patterns for GC code

Decision Guide: When to Use Which Options

Use --codebase

When: User wants comprehensive review, mentions API usage, function calls, or needs context Why: Includes MicroPython codebase definitions and patterns Cost: +2-3 seconds

Use --rerank

When: User emphasizes quality/accuracy, or initial results seem off-topic Why: Better relevance via cross-encoder scoring Cost: +5-10 seconds on CPU

Use --output prompt

When: User wants detailed review, mentions "thorough", or you'll provide review feedback Why: Gives you complete context to generate maintainer-style review Cost: Longer output to process

Use --output context

When: User asks for examples, "what has been said", or wants quick reference Why: Just the examples, faster to read Cost: Minimal

Use search instead of review

When: User asks about patterns/topics without providing specific code to review Example: "What do reviewers think about error handling?" Why: Semantic search, not diff-based retrieval

Handling Errors

"Index not found"

The vector index hasn't been built. Inform user:

The review database index needs to be built first. Run:
cd ${CLAUDE_PLUGIN_ROOT}
uv run python scripts/build_index_resume.py

"Command not found"

Verify uv and the project are accessible:

uv run --project ${CLAUDE_PLUGIN_ROOT} mpy-reviewer stats

Git errors (no repository, invalid ref, etc.)

Handle appropriately - ask user to clarify or check their git state.

Performance Expectations

• First query: 2-3 seconds (model loading)
• Subsequent queries: 0.5-1 second (dense search only)
• With --rerank: +5-10 seconds on CPU
• With --codebase: +2-3 seconds

Inform user if a long operation is running.

Data Scope

The database contains:

• ~19.5K categorized review comments
• Source: micropython/micropython and micropython/micropython-lib repositories
• Timeframe: 2013-2026
• Coverage: All PR review comments, issue comments, and review verdicts

Natural Language Understanding

Be flexible with user requests. Map to appropriate commands:

User Intent	Tool Command
"review this"	git diff | ... review --stdin
"review commit X"	git show X | ... review --stdin
"review PR 123"	... review --pr 123
"find GPIO reviews"	... search "GPIO" --component port_specific
"show me memory issues"	... search "memory" --domain memory --severity blocking
"examples of his style"	... search "..." --style-only

Always interpret user intent conversationally, then invoke the appropriate tool command.

Important Notes

1. Always use full path: uv run --project ${CLAUDE_PLUGIN_ROOT} mpy-reviewer
2. Prefer stdin for git integration: Use git diff \| ... --stdin over temp files
3. Default to quality: Use --codebase --output prompt unless user wants quick results
4. Be conversational: Don't just relay CLI output, interpret and present meaningfully
5. Handle context: If reviewing specific commits/branches, mention what's being reviewed
6. Cite examples: When referencing review patterns, show the actual comments from search results

Verification

To test the skill is working:

uv run --project ${CLAUDE_PLUGIN_ROOT} mpy-reviewer stats

Should show:

• Index exists: True
• Number of records: ~19.5K