Skill: ivangdavila/review-code (version 1.0.0)

--- name: Review Code slug: review-code version: 1.0.0 homepage: https://clawic.com/skills/review-code description: Review code with risk-first analysis, reproducible evidence, and patch-ready guidance for correctness, security, performance, and maintainability. changelog: Initial release with risk-first review workflow, severity-confidence scoring, and fix-ready output templates. metadata: {"clawdbot":{"emoji":"🔎","requires":{"bins":[]},"os":["darwin","linux","win32"]}} --- ## Setup On first use, read `setup.md` for integration guidance and local memory initialization. ## When to Use User asks for a code review, PR review, merge-readiness check, or bug-risk audit before shipping. Agent delivers a risk-ranked review with explicit evidence, impact, confidence, and concrete fix direction. ## Architecture Memory lives in `~/review-code/`. See `memory-template.md` for structure and starter templates. ```text ~/review-code/ ├── memory.md # Review preferences, stack context, and recent constraints ├── findings/ # Optional per-review finding logs ├── baselines/ # Team conventions and accepted risk baselines └── sessions/ # Session summaries for ongoing audits ``` ## Quick Reference | Topic | File | |-------|------| | Setup and integration behavior | `setup.md` | | Memory schema and templates | `memory-template.md` | | End-to-end review execution flow | `review-workflow.md` | | Severity and confidence calibration | `severity-and-confidence.md` | | Language and architecture risk checks | `language-risk-checklists.md` | | Test impact requirements by change type | `test-impact-playbook.md` | | Comment and report templates | `comment-templates.md` | | Patch strategy for actionable fixes | `patch-strategy.md` | ## Data Storage Local notes stay in `~/review-code/`. Before creating or changing local files, present the planned write and ask for user confirmation. ## Core Rules ### 1. Define the Review Contract First Confirm target scope before reviewing: branch, files, risk tolerance, and release context. If scope is unclear, state assumptions explicitly and keep findings tied to those assumptions. ### 2. Start With Risk Mapping, Then Deep Dive Run a fast pass to locate high-risk zones first: auth, money, data integrity, concurrency, and migration paths. Only then perform line-level analysis with `review-workflow.md` so major failures are surfaced early. ### 3. Every Finding Must Be Evidence-Backed Do not report vague concerns. Each finding must include: trigger location, concrete failure mode, user or business impact, and minimal reproduction clue. If evidence is weak, mark low confidence or downgrade to a question. ### 4. Separate Blocking vs Advisory With Severity + Confidence Use `severity-and-confidence.md` for consistent triage. Blocking findings must be reproducible or highly probable with strong impact. Advisory feedback must remain concise and never hide blockers. ### 5. Always Pair Findings With a Fix Path For each blocking issue, provide a minimally disruptive fix strategy. Use `patch-strategy.md` to propose rollback-safe edits, guard tests, and verification steps. ### 6. Tie Review Quality to Test Impact Map each change to required tests using `test-impact-playbook.md`. If tests are missing, list the exact scenarios that must be added and why they prevent regressions. ### 7. Optimize for Signal, Not Volume Prioritize high-impact defects over style noise. If no blockers are found, state that explicitly and list residual risks, test gaps, and monitoring advice. ## Common Traps - Reporting opinions as facts -> review credibility drops and teams ignore real blockers. - Mixing blocker and nit feedback without labels -> delayed merges and mis-prioritized fixes. - Calling something “probably fine” without tests -> silent regressions in production. - Suggesting large rewrites for local defects -> good fixes are postponed indefinitely. - Ignoring release context (hotfix vs refactor) -> wrong trade-offs for urgency. - Missing migration and backward-compatibility checks -> runtime failures after deploy. ## External Endpoints This skill makes NO external network requests. | Endpoint | Data Sent | Purpose | |----------|-----------|---------| | None | None | N/A | No other data is sent externally. ## Security & Privacy **Data that leaves your machine:** - Nothing by default. This is an instruction-only review skill unless the user explicitly exports artifacts. **Data stored locally:** - Review preferences, project constraints, and optional findings approved by the user. - Stored in `~/review-code/`. **This skill does NOT:** - auto-approve code or merge pull requests. - make undeclared network calls. - store credentials, tokens, or sensitive payloads. - modify its own core instructions or auxiliary files. ## Trust This is an instruction-only code review skill. No credentials are required and no third-party services are contacted by default. ## Related Skills Install with `clawhub install <slug>` if user confirms: - `code` - implementation workflow that complements review findings. - `git` - safer branch, diff, and commit handling during remediation. - `typescript` - stricter typing and runtime safety review for TS-heavy codebases. - `ci-cd` - release-gate checks and deployment safeguards after fixes. - `devops` - production risk assessment and rollback planning. ## Feedback - If useful: `clawhub star review-code` - Stay updated: `clawhub sync`

path: comment-templates.md
content: # Review Comment Templates

Use these templates for clear, actionable communication.

## Blocking Finding Template

`[P1][High] <file:line> - <issue title>`

- **What fails:**
- **Impact:**
- **Why this is likely:**
- **Minimal fix:**
- **How to verify:**

## Advisory Finding Template

`[P2][Medium] <file:line> - <improvement title>`

- **Current risk:**
- **Suggested improvement:**
- **Expected payoff:**

## Low-Confidence Question Template

`[Question][Low] <file:line> - <hypothesis>`

- Observed signal:
- Missing context:
- Clarification requested:

## No-Findings Summary Template

`No blocking defects found in reviewed scope.`

- Residual risks:
- Testing gaps:
- Suggested monitoring after release:

## Merge Recommendation Template

- **Recommend merge:** yes/no
- **Blocking count:**
- **Advisory count:**
- **Conditions before merge:**

## Tone Guardrails

- critique code, never author
- avoid sarcasm or absolute language
- keep each finding concise and evidence-based


path: language-risk-checklists.md
content: # Language and Architecture Risk Checklists

Use only relevant sections for the current stack.

## Cross-Stack Core Checks

- input validation at trust boundaries
- null or optional handling on every data hop
- error propagation without silent swallowing
- idempotency of retries and background jobs
- backward compatibility for APIs and data contracts

## JavaScript and TypeScript

- unsafe `any` paths masking runtime errors
- missing runtime guards on external payloads
- async race conditions in shared mutable state
- unhandled promise rejections and partial failures
- bundling regressions from heavy dependencies

## Python

- mutable default arguments and hidden state leaks
- broad exception catches hiding root causes
- timezone-naive datetime operations
- ORM queries causing N+1 behavior
- serialization mismatches across boundaries

## Java, Kotlin, C#, Go

- transactional boundaries and rollback consistency
- thread safety and shared state contention
- panic or exception propagation to API layer
- resource lifecycle leaks (connections, streams)
- timeout and cancellation handling in I/O calls

## Data and Migration Paths

- destructive migrations without rollback plan
- implicit schema assumptions in old clients
- default values changing business meaning
- indexes missing for new query paths
- dual-write drift during transition windows

## Final Architecture Sanity Check

Before closing review, confirm:
- ownership boundaries are respected
- dependency direction did not regress
- observability exists for changed critical paths


path: memory-template.md
content: # Memory Template - Review Code

Create `~/review-code/memory.md` with this structure:

```markdown
# Review Code Memory

## Status
status: ongoing
version: 1.0.0
last: YYYY-MM-DD
integration: pending | complete | paused | never_ask

## Review Defaults
severity_threshold:
confidence_floor:
delivery_mode: quick | standard | deep

## Project Context
primary_stack:
critical_paths:
release_risk_profile:

## Known Constraints
test_limits:
environment_limits:
non_goals:

## Recent Patterns
- recurring defect class
- risky module
- fix strategy that worked

## Notes
- facts explicitly confirmed by user
- assumptions to revalidate in next review

---
*Updated: YYYY-MM-DD*
```

## Status Values

| Value | Meaning | Behavior |
|-------|---------|----------|
| `ongoing` | Active review support | Keep adapting findings style and risk focus |
| `complete` | Stable review baseline reached | Use lightweight updates |
| `paused` | User paused this skill | Keep context read-only until resumed |
| `never_ask` | User wants no setup prompts | Do not ask setup questions unless requested |

## Optional File Templates

Create `~/review-code/findings/YYYY-MM-DD.md`:

```markdown
# Findings - YYYY-MM-DD

## Scope
- branch:
- files reviewed:
- release context:

## Blocking Findings
- [P0/P1] file:line - issue - impact - fix summary

## Advisory Findings
- [P2/P3] file:line - issue - improvement

## Residual Risks
- remaining risk and monitoring note
```

## Key Principles

- Save only user-approved context.
- Keep logs short, factual, and reproducible.
- Update `last` whenever defaults or constraints change.


path: patch-strategy.md
content: # Patch Strategy for Review Findings

Use this when proposing concrete fixes after a finding.

## Principles

- prefer minimal diffs over large rewrites
- protect behavior with tests before refactoring
- include rollback-safe steps for risky changes
- keep patch scope aligned with the identified defect

## Fix Planning Sequence

1. Reproduce the failure or risk condition.
2. Add or update test that captures the issue.
3. Apply minimal code change to pass the test.
4. Re-run nearby tests and static checks.
5. Document any follow-up refactor separately.

## High-Risk Change Guardrails

For auth, billing, migration, or data integrity fixes:
- require explicit rollback path
- require monitoring signal after deploy
- avoid bundled unrelated cleanups

## Suggested Output Format

- `Patch goal:` one sentence
- `Files touched:` list
- `Test added/updated:` exact scenario
- `Risk after patch:` low/medium/high with reason
- `Rollback note:` one concrete step

## Example Short Plan

- Patch goal: prevent stale cache writes during concurrent updates.
- Files touched: cache service write path and retry helper.
- Test added: concurrent writer test with conflict retries.
- Risk after patch: medium due to deployment ordering.
- Rollback note: disable retry path via feature flag.


path: review-workflow.md
content: # Review Workflow - Risk First

Use this flow to deliver faster and more defensible reviews.

## Phase 1: Scope and Risk Framing

1. Confirm review target and boundaries.
2. Identify high-risk surfaces first:
   - auth and authorization
   - money and billing logic
   - data mutation paths
   - concurrency or async coordination
   - schema or migration changes
3. Capture assumptions that affect verdict quality.

Output:
- clear scope line
- risk map with top 3 surfaces

## Phase 2: Evidence Pass

For each risk surface, inspect diffs and local context.
Every finding must include:
- exact location
- failure mode
- impact severity
- confidence level
- minimal remediation path

Reject vague statements such as “this might break.”
Replace with reproducible conditions.

## Phase 3: Test and Verification Pass

Map findings to test requirements:
- existing tests that already protect behavior
- missing tests required for merge safety
- runtime checks needed post-deploy

If tests cannot run, say why and list a concrete fallback verification plan.

## Phase 4: Delivery Pass

Structure final output in this order:
1. blocking findings by priority
2. advisory findings
3. residual risks and test gaps
4. short merge recommendation

Keep nits minimal unless user asked for style pass.

## Fast Path for Hotfixes

When urgency is high:
- focus only on P0/P1 risks
- require rollback path for risky edits
- defer non-critical refactors

Goal: safe release under time pressure, not perfect code.


path: setup.md
content: # Setup - Review Code

Read this silently when `~/review-code/` is missing or empty.
Start naturally and solve the current user request first.

## Your Attitude

Be precise, calm, and risk-focused.
Sound like an engineer helping ship safer code under real constraints.
Prefer concrete evidence over strong opinions.

## Priority Order

### 1. First: Integration
Within the first exchanges, clarify activation expectations:
- should this review mode activate whenever the user asks for PR checks, merge readiness, or bug-risk scans
- should feedback be strict by default or balanced for velocity
- any contexts where this should never activate

Confirm integration behavior in plain language and continue.

### 2. Then: Understand Review Context
Collect only what changes the review quality:
- runtime and language stack
- release urgency and blast radius
- ownership boundaries and constraints
- existing quality gates already in place

Avoid long discovery if the user needs a quick high-risk scan.

### 3. Finally: Personalize Reporting Depth
Adjust output depth to user preference:
- quick mode: blockers only with short fix path
- standard mode: blockers plus key advisories and test gaps
- deep mode: architecture risks, long-tail edge cases, and rollout checks

Do not force deep audits when the user asks for fast triage.

## What You Are Saving Internally

Store only data that improves later reviews:
- preferred severity threshold and tone
- recurring project risk hotspots
- accepted trade-offs and non-goals
- known test infrastructure constraints

Avoid storing secrets, credentials, or private code.

## Guardrails

- Never invent evidence for a finding.
- Never label as blocker without explaining impact.
- Never flood the user with low-value nits when major risks exist.
- Never imply certainty when confidence is low.


path: severity-and-confidence.md
content: # Severity and Confidence Guide

Use this matrix to keep triage consistent across reviews.

## Priority Levels

| Priority | Meaning | Merge Impact |
|----------|---------|--------------|
| P0 | Security breach, data loss, or outage risk | Block merge |
| P1 | High-probability functional defect | Block merge |
| P2 | Maintainability or medium-term reliability risk | Advisory |
| P3 | Style or low-impact improvement | Advisory |

## Confidence Levels

| Confidence | Use When | Reviewer Behavior |
|------------|----------|-------------------|
| High | Reproducible or directly provable from code | State as finding |
| Medium | Strong signal but partial context missing | State with assumptions |
| Low | Suspicion without sufficient evidence | Ask as targeted question |

## Escalation Rules

- P0/P1 with high confidence -> explicit blocker.
- P0/P1 with medium confidence -> blocker plus required verification steps.
- P2/P3 with low confidence -> convert to question, not mandate.

## Finding Format

Use one line summary first:
`[P1][High] file:line - short issue title`

Then include:
- What fails
- Why it matters
- Minimal fix path
- Validation step

## Anti-Noise Rules

- Never up-rank a finding to force action.
- Never bury blockers inside long advisory lists.
- Never call something “critical” without user-impact explanation.

## Tie-Breaker

If uncertain between two severities:
- choose lower severity
- raise confidence notes
- request the missing evidence needed to upgrade


path: test-impact-playbook.md
content: # Test Impact Playbook

Map code changes to required test evidence.

## Change Type to Test Requirements

| Change Type | Minimum Test Evidence |
|-------------|-----------------------|
| Pure logic function | unit tests for happy path and edge cases |
| API handler | contract test plus failure-path coverage |
| Data mutation flow | integration test with rollback or retry behavior |
| Async job worker | retry, timeout, and idempotency checks |
| UI state logic | interaction tests for loading, error, and success states |
| Security-sensitive path | negative tests for auth or input bypass |

## Gap Classification

- missing-critical: blocker because defect risk is high
- missing-important: advisory but required before next release
- missing-optional: useful hardening for future cycles

## Required Review Output

When tests are missing, include:
1. exact scenario that needs a test
2. expected behavior
3. failure behavior prevented by the test
4. priority (P0 to P3)

## If Tests Cannot Run

State the blocker explicitly:
- why execution was impossible
- what evidence was still inspected
- what must be run before release

## Lightweight Templates

Blocking gap:
`[P1][High] Missing test for <scenario>. Without it, <failure mode> can ship undetected.`

Advisory gap:
`[P2][Medium] Add coverage for <scenario> to reduce regression risk in future refactors.`


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)