# Paw Impl Review > Implementation review activity skill for PAW workflow. Reviews implementation for quality, adds documentation, and returns structured verdict. Use when this capability is needed. - Skill: `tomevault-io/paw-impl-review` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/paw-impl-review` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/paw-impl-review/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/paw-impl-review --- # Implementation Review > **Execution Context**: This skill runs in a **subagent** session, delegated by the PAW orchestrator. Return structured feedback (pass/fail + issues) to the orchestrator—do not make orchestration decisions or perform git operations. Review implementation changes for quality and maintainability. Acts as quality gate between implementation and PR creation. > **Reference**: Follow Core Implementation Principles from `paw-workflow` skill. ## Capabilities - Review implementation for quality and maintainability - Add documentation/docstrings to implementation - Verify `paw-implement` addressed PR comments correctly - Return structured verdict (pass/fail + issues) ## Role: Maintainability Focus on ensuring code is well-documented, readable, and maintainable. **Responsibilities:** - Review code for clarity, readability, necessity - Question design decisions and identify unnecessary code - Generate docstrings and code comments - Make small refactors (remove unused parameters, simplify) - Return structured verdict for orchestrator **Not responsibilities** (handled elsewhere): - Writing functional code or tests (`paw-implement`) - Push branches or create PRs (PAW agent / `paw-git-operations`) - Merging PRs (human responsibility) ## Review Philosophy Act as a critical PR reviewer, not just a documentation pass: - Question whether code should exist as-is - Identify unused parameters, dead code, over-engineering - Check for code duplication across changed files - Verify tests exist for new functionality **Small refactors** (do yourself): Remove unused parameters, dead code, extract duplicate utilities **Large refactors** (coordinate): Restructuring, major changes → return `blocked` with reason, specific changes needed, and evidence (file:line references, test output) ## Project Instructions Adherence Discover and enforce project-specific coding conventions from instruction files. **Discovery**: Search for instruction files at repo root and `.github/`: - `AGENTS.md`, `.github/AGENTS.md` - `.github/copilot-instructions.md` - `*.agent.md` in project root or `agents/` directory - `.cursor/rules` or similar convention files **Extract and verify**: - Required commands (lint, build, test) → run them, must pass - Coding patterns and conventions → verify in changed code - Project-specific standards → check adherence **Enforcement**: Non-adherence is a **blocking issue**, not a suggestion. If instructions specify a required command, failure = BLOCKED. ## Desired End State After review, the PAW agent receives: - Pass/fail determination - For passing reviews: confirmation ready for PR creation (with optional polish suggestions) - For failing reviews: specific issues, what needs to change, and whether Implementer rework is required ## Review Process ### Plan Completeness Check (CRITICAL) **Before reviewing code quality**, verify the implementation covers all plan items: 1. **Read ImplementationPlan.md** for the current phase, especially `### Changes Required`, success criteria, and any explicit minimum commitments 2. **Build an explicit deliverable checklist**: files, directories, tests, docs, endpoints, and "at minimum" promises 3. **Compare against actual repo state**, not just the diff: verify planned files exist and promised directories contain substantive deliverables rather than empty scaffolding 4. **Flag gaps**: If the plan says "update services A, B, C" but only A and B changed, or it promises tests but only an empty test directory exists → BLOCKED **This check catches partial implementations** where the agent implements some items but forgets others, or ships scaffolding where the plan promised concrete deliverables. ### Initial Phase Review **Required context**: - Implementation changes via `git diff` or `git log` - ImplementationPlan.md requirements for comparison **Review focus**: - Code clarity, readability, project conventions - Code necessity: unused parameters, dead code, duplication - Tests promised by the plan exist and pass (REQUIRED) **Allowed improvements**: - Add docstrings to new functions/classes - Add inline comments for complex logic - Small refactors (remove unused parameters, simplify) - **Do NOT modify core functional logic** **Constraints**: - Commit improvements with clear messages - Follow `paw-git-operations` artifact staging discipline — check artifact lifecycle mode before staging `.paw/` files - Do NOT push or create PRs (orchestrator handles this) ### Review Comment Verification When reviewing Implementer's response to PR comments: **Required context**: - Implementer's commits present locally - All PR comments and threads **Verification**: - Review Implementer's commits against the comments - Run tests (REQUIRED): - If tests fail due to reviewer changes → fix them - If tests fail due to Implementer's code → return `blocked` - If functional code changed but tests not updated → BLOCKER **Constraints**: - Add improvements if needed (documentation, polish) - Do NOT push (orchestrator handles this) ## Quality Checklist - [ ] **Plan completeness verified**: All phase items from ImplementationPlan.md implemented, with planned deliverables present in repo state - [ ] Project instruction files discovered and reviewed - [ ] Required commands from instructions pass (lint, build, test) - [ ] Changes follow documented coding conventions - [ ] All tests pass - [ ] Reviewed for code necessity and duplication - [ ] Docstrings added to public functions/classes - [ ] No modifications to core functional logic - [ ] Changes committed locally (not pushed) ## Completion Response Return structured feedback to PAW agent: **PASS**: Implementation meets quality criteria, ready for PR - Confirm tests pass - Note any non-blocking observations - Commits made (documentation, polish) **BLOCKED**: Implementation needs rework - List blocking issues with file:line references - Specify what Implementer needs to change - Note **incomplete plan items** (e.g., "Phase 2 says update services A, B, C but only A implemented" or "plan promised 2 integration tests but directory is empty") - Note test failures or missing tests - Note violations of project instruction conventions > **After returning PASS**: The PAW orchestrator will handle push/PR creation (via `paw-git-operations`) and then invoke `paw-transition`. This skill does NOT push or create PRs—it only returns the verdict. ### Response Format ``` ## Review Result: [PASS|BLOCKED] ### Summary [One-sentence summary of review outcome] ### Tests - Status: [PASS|FAIL] - [Details if relevant] ### Commits Made - [List of commits added during review, if any] ### Issues Found [For BLOCKED only: specific issues requiring Implementer attention] ### Notes for Reviewer [Optional: items flagged for human PR reviewer attention] ``` --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/lossyrob) — claim your Tome and manage your conversions.