structured-code-review
The structured-code-review Claude Code skill performs a methodical five-stage code review examining requirements compliance, correctness, code quality, testing, and security/performance concerns. Use this skill when receiving requests for code review, pull request feedback, or code checking, particularly when phrases like "review my code," "check this PR," or "code feedback" appear in the request.
git clone --depth 1 https://github.com/rohitg00/skillkit /tmp/structured-code-review && cp -r /tmp/structured-code-review/packages/core/src/methodology/packs/collaboration/structured-review ~/.claude/skills/structured-code-reviewSKILL.md
# Structured Code Review You are performing a structured, multi-stage code review. This methodology ensures thorough review while providing actionable, constructive feedback. ## Core Principle **Review in stages. Each stage has a specific focus. Don't mix concerns.** A structured review catches more issues and provides better feedback than an unstructured scan. ## Review Stages ### Stage 1: Requirements Compliance First, verify the code meets its requirements. **Checklist:** - [ ] Implements stated requirements - [ ] Handles specified edge cases - [ ] No scope creep (unexpected additions) - [ ] No missing functionality **Feedback at this stage:** - "This doesn't appear to handle the case when X is empty" - "The requirement specified Y, but this implements Z" - "This adds feature F which wasn't requested - is that intentional?" ### Stage 2: Correctness Next, verify the code works correctly. **Checklist:** - [ ] Logic is sound - [ ] No obvious bugs - [ ] Error paths are handled - [ ] No unfinished code (TODOs without tickets) **Feedback at this stage:** - "This will throw if `user` is null" - "The loop exits early before processing all items" - "What happens when the API call fails?" ### Stage 3: Code Quality Then, evaluate code quality and maintainability. **Checklist:** - [ ] Clear naming - [ ] Reasonable function/method length - [ ] No unnecessary complexity - [ ] Follows project conventions - [ ] Appropriate abstractions **Feedback at this stage:** - "Could you rename `data` to `userProfile` for clarity?" - "This function is doing three things - consider splitting" - "We use camelCase for variables in this project" ### Stage 4: Testing Evaluate test coverage and quality. **Checklist:** - [ ] New code has tests - [ ] Tests cover main paths and edge cases - [ ] Tests are readable and maintainable - [ ] Tests don't test implementation details **Feedback at this stage:** - "Please add a test for the error case" - "This test will break if we change the implementation" - "Consider using a parameterized test for these cases" ### Stage 5: Security & Performance Finally, check for security and performance concerns. **Checklist:** - [ ] No SQL injection, XSS, etc. - [ ] Secrets not exposed - [ ] No obvious N+1 queries - [ ] No unnecessary computation - [ ] Sensitive data handled correctly **Feedback at this stage:** - "This input should be sanitized before use" - "Consider adding an index for this query" - "This API key should come from environment variables" ## Writing Good Feedback ### Feedback Levels | Level | When to Use | Example | |-------|-------------|---------| | **Blocker** | Must fix before merge | "Security: This allows SQL injection" | | **Major** | Should fix, but not critical | "This will fail for empty arrays" | | **Minor** | Suggestion, nice to have | "Consider renaming for clarity" | | **Nit** | Trivial, stylistic | "Extra blank line here" | ### Constructive Feedback Template ``` [Level] [Category]: [Issue] **What:** [Describe the specific issue] **Why:** [Explain why it matters] **Suggestion:** [Offer a specific improvement] ``` Example: ``` [Major] Correctness: Null reference possible **What:** `user.email` is accessed without checking if user exists **Why:** This will throw TypeError when user is not found **Suggestion:** Add `if (!user) return null;` before accessing properties ``` ## Review Checklist Summary ```markdown ## Review: [PR Title] ### Stage 1: Requirements - [ ] Implements requirements - [ ] Handles edge cases - [ ] Appropriate scope ### Stage 2: Correctness - [ ] Logic is sound - [ ] No bugs - [ ] Errors handled ### Stage 3: Quality - [ ] Readable - [ ] Follows conventions - [ ] Maintainable ### Stage 4: Testing - [ ] Has tests - [ ] Tests are good ### Stage 5: Security/Performance - [ ] No vulnerabilities - [ ] No performance issues ### Verdict: [ ] Approve [ ] Request Changes [ ] Comment ``` ## Integration with Other Skills - **planning/verification-gates**: Review is a key gate - **testing/test-patterns**: Evaluate test quality - **testing/anti-patterns**: Spot testing issues
Manages work transitions between team members or agents by creating structured handoff documents, summarizing project status, documenting key decisions, blockers, and open questions, and generating onboarding briefs. Use when someone needs to hand off, hand over, or transition a project; pass work to another person or agent; brief a colleague taking over; prepare a shift change summary; or onboard someone mid-task. Produces ready-to-use handoff documents covering current status, next steps, known issues, technical context, and communication templates for both planned and unplanned transfers.
Coordinates parallel investigation threads to simultaneously explore multiple hypotheses or root causes across different system areas. Use when debugging production incidents, slow API performance, multi-system integration failures, or complex bugs where the root cause is unclear and multiple plausible theories exist; when serial troubleshooting is too slow; or when multiple investigators can divide root-cause analysis work. Provides structured phases for problem decomposition, thread assignment, sync points with Continue/Pivot/Converge decisions, and final report synthesis.
Applies the scientific method to debugging by helping users form specific, testable hypotheses, design targeted experiments, and systematically confirm or reject theories to find root causes. Use when a user says their code isn't working, they're getting an error, something broke, they want to troubleshoot a bug, or they're trying to figure out what's causing an issue. Concrete actions include isolating failing components, forming and testing hypotheses, analyzing error messages, tracing execution paths, and interpreting test results to narrow down root causes.
Performs systematic root cause analysis to identify the true source of bugs, errors, and unexpected behavior through structured investigation phases — not just treating symptoms. Use when a user reports a bug, crash, error, or broken behavior and needs to debug, troubleshoot, or investigate why something is not working; especially for complex or intermittent issues across multiple components. Applies the Five Whys method, hypothesis-driven testing, stack trace analysis, git blame/log evidence gathering, and causal chain documentation to isolate and confirm root causes before applying any fix.
Applies systematic tracing and isolation techniques to pinpoint exactly where a bug originates in code. Use when a bug is hard to locate, code is not working as expected, an error or crash appears with unclear cause, a regression was introduced between recent commits, or you need to narrow down which component, function, or line is faulty. Covers binary search debugging, git bisect for regressions, strategic logging with [TRACE] patterns, data and control flow tracing, component isolation, minimal reproduction cases, conditional breakpoints, and watch expressions across TypeScript, SQL, and bash.
Creates and structures SKILL.md files for AI coding agents, including YAML frontmatter, trigger phrases, directive instructions, decision trees, code examples, and verification checklists. Use when the user asks to write a new skill, create a skill file, author agent capabilities, generate skill documentation, or define a skill template for Claude Code agents.
Guides the creation of technical design documents before writing code, producing architecture diagrams, data models, API interface definitions, implementation plans, and multi-option trade-off analyses. Use when the user asks to plan a feature, architect a system, design an API, explore implementation approaches, or requests a technical design or spec before coding — especially for complex features involving multiple components, ambiguous requirements, or significant architectural changes.
Breaks down complex software, writing, or research tasks into small, atomic, independently completable units with dependency graphs and milestone breakdowns. Use when the user asks to plan a project, decompose a feature, create subtasks, split up work, or needs help organizing a large piece of work into a step-by-step plan. Triggered by phrases like "break down", "decompose", "where do I start", "too big", "split into tasks", "work breakdown", or "task list".