# Branch Code Review

> Review changes on the current branch versus main for design, maintainability, and correctness. Use when a general code review is requested. Use when this capability is needed.

- Skill: `tomevault-io/branch-code-review` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/branch-code-review`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/branch-code-review/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/branch-code-review

---

# Branch Code Review (General)

## Purpose
Perform a general code review on the current branch compared to the base branch (`main` by default), focusing on architecture, maintainability, and correctness.

## Scope
- If `$ARGUMENTS` is provided, treat it as a scope (paths, diff range, or PR number).
- If no arguments are provided, review `base...HEAD` where `base` is detected (`origin/main` → `origin/master` fallback).

## Workflow
1. **Determine diff target**
   - Detect base branch:
     - `git symbolic-ref refs/remotes/origin/HEAD` → extract `main` or `master`.
     - If not available, try `origin/main`, then `origin/master`.
2. **Enumerate change surface**
   - `git diff --name-status base...HEAD`
   - `git log --oneline base...HEAD`
   - Read the diff before diving into code.
3. **Architecture pass**
   - Evaluate loose coupling, high cohesion, extensibility, and DRY.
   - Check module boundaries and whether responsibilities are clearly separated.
4. **Maintainability pass**
   - Keep files under ~500 lines unless necessary.
   - Names are descriptive; public names are concise; internal names can be verbose.
   - Comments explain *why* for non-obvious logic; remove redundant comments.
   - Documentation is updated for behavior, usage, or interface changes.
5. **Correctness and safety**
   - Validate logic, edge cases, and error handling.
   - Look for regressions, config mismatches, or hidden coupling.
6. **Tests**
   - Ensure tests exist and are meaningful for the change surface.
   - Prefer tests that would fail on broken behavior.

## Best-Practice Signals (from authoritative guidance)
- Review design and interactions first; validate overall intent. (Google Eng Practices)
- Read every changed line in logical sequence; expand context if needed. (Google + Microsoft)
- Focus on correctness, readability/maintainability, and test quality. (Microsoft)
- Use structured checklists to avoid missing issues. (Atlassian)

## Repo-Specific Context
This repo is evolving toward extensible planning/content management. Favor:
- Clear interfaces for future content types beyond plans.
- Minimal cross-package coupling.
- Extensible, composable APIs (avoid one-off branching).
- Config/format stability to support long-lived plans and migrations.

## Output Format
Follow the repo review style:
- Findings first, ordered by severity.
- Include file references and concrete evidence.
- If no issues, say so explicitly and list residual risks or testing gaps.

Use this structure:
```
## Findings
- 🔴 Critical: ...
- 🟠 High: ...
- 🟡 Medium: ...
- 🟢 Low: ...

## Questions / Assumptions
- ...

## Tests
- Suggested: ...
```

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/paulbreuler) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-12 -->