pm7y-codebase-review

What this skill does

# Codebase Review Skill

Reviews codebases for consistency, patterns, and adherence to software engineering principles. Produces analysis findings that are passed to `pm7y-ralph-planner` for TASKS.md generation.

---

## Overview

This skill performs comprehensive codebase analysis focusing on:

- **Style & pattern consistency** - Implicit and explicit conventions
- **Language idioms** - Following best practices for each language
- **Principle adherence** - KISS, DRY, POLA, YAGNI
- **Complexity reduction** - Identifying unnecessary complexity
- **Duplication detection** - Finding repeated code patterns

**Output:** Analysis findings passed to `pm7y-ralph-planner`, which generates a `TASKS.md` file with validation requirements and learnings tracking for autonomous execution via `pm7y-ralph-loop`.

**When to use:**

- Periodic codebase health checks with automated fixes
- Before major refactoring efforts
- Autonomous code quality improvement sessions
- After rapid feature development to address technical debt

---

## Review Depth Options

The review supports different depth levels via command arguments:

| Depth | Scope | Use When |
|-------|-------|----------|
| `--quick` | Sample key files, high-level patterns | Quick health check |
| `--standard` | Representative files from each area | Regular reviews (default) |
| `--comprehensive` | Full codebase scan, detailed analysis | Before major refactoring |

---

## Review Process

### Step 1: Study Documentation

Before analyzing code, read and understand:

1. **README.md** - Project overview, architecture decisions
2. **CLAUDE.md** - Codebase conventions (if exists)
3. **CONTRIBUTING.md** - Contribution guidelines
4. **Architecture docs** - Any docs in `/docs` or similar
5. **.editorconfig** - Formatting preferences
6. **Linter configs** - ESLint, Prettier, StyleCop, .pylintrc, .rubocop.yml, etc.

Use these to understand the project's stated conventions before comparing to actual code.

### Step 2: Detect Languages and Frameworks

Scan the codebase to identify all languages and frameworks present. Look for:

| Language/Framework | Indicators |
|-------------------|------------|
| **JavaScript/TypeScript** | `package.json`, `.js`, `.ts`, `.jsx`, `.tsx` files |
| **React** | React in package.json dependencies, JSX/TSX files, hooks |
| **Node.js** | `package.json` with node dependencies, no browser frameworks |
| **C#/.NET** | `.sln`, `.csproj`, `.cs` files, `Program.cs` |
| **Python** | `requirements.txt`, `pyproject.toml`, `setup.py`, `.py` files |
| **Go** | `go.mod`, `go.sum`, `.go` files |
| **Rust** | `Cargo.toml`, `Cargo.lock`, `.rs` files |
| **Java** | `pom.xml`, `build.gradle`, `.java` files |
| **Ruby** | `Gemfile`, `.rb` files, `Rakefile` |
| **PHP** | `composer.json`, `.php` files |
| **Kotlin** | `build.gradle.kts`, `.kt` files |
| **Swift** | `Package.swift`, `.swift` files, `.xcodeproj` |

**Record detected languages** for use in task grouping and analysis focus.

### Step 3: Analyze Code by Language

For each detected language, apply language-specific analysis. Use Context7 to look up current best practices for the detected languages/frameworks.

---

#### React/TypeScript Analysis

*Apply when React/TypeScript detected.*

**Component Patterns:**
- Functional vs class components (prefer functional)
- Hook usage patterns (custom hooks, composition)
- State management approach (local, context, external)
- Component file structure (co-location, barrel exports)

**TypeScript Idioms:**
- Type inference vs explicit types
- Interface vs type aliases
- Utility types usage
- Strict mode adherence

**Style Consistency:**
- Naming conventions (PascalCase components, camelCase functions)
- Import ordering and grouping
- Export patterns (default vs named)
- File naming conventions

**React Best Practices:**
- Prop drilling vs composition
- useEffect dependencies and cleanup
- Memoization (useMemo, useCallback, React.memo)
- Error boundaries
- Accessibility patterns

---

#### C#/.NET Analysis

*Apply when C#/.NET detected.*

**Architecture Patterns:**
- Layer separation (Controllers, Services, Repositories)
- Dependency injection usage
- Interface abstractions
- CQRS or traditional patterns

**C# Idioms:**
- Nullable reference types
- Async/await patterns
- LINQ usage (query vs method syntax)
- Record types vs classes
- Pattern matching

**Style Consistency:**
- Naming conventions (PascalCase, _camelCase for fields)
- File organization (one class per file)
- Namespace structure
- XML documentation

**.NET Best Practices:**
- Exception handling patterns
- Configuration management
- Logging patterns
- Validation approaches

---

#### Other Languages (Dynamic Analysis)

*Apply when languages other than React/TypeScript or C#/.NET are detected.*

For languages not covered above, use Context7 to look up current best practices:

1. **Identify the language** - Use the detection table from Step 2
2. **Query Context7** - Look up idioms, style guides, and best practices for that language
3. **Apply universal checks** - See "Generic Analysis" below
4. **Focus on consistency** - Even without deep language knowledge, inconsistencies are identifiable

**Common analysis patterns for any language:**
- Code organization and module structure
- Naming convention consistency
- Error/exception handling patterns
- Testing patterns and coverage
- Dependency management
- Documentation quality

---

#### Generic Analysis (Any Language)

*Always apply these checks regardless of language.*

**Universal Patterns:**
- Consistent naming within the codebase
- File/directory organization patterns
- Comment quality and accuracy
- Test organization and coverage
- Configuration management
- Environment handling
- Logging patterns
- Error handling consistency

### Step 4: Apply Engineering Principles

Evaluate code against each principle:

**KISS (Keep It Simple, Stupid):**
- Overly complex solutions for simple problems
- Unnecessary abstraction layers
- Convoluted control flow
- Over-engineered patterns

**DRY (Don't Repeat Yourself):**
- Duplicated code blocks
- Similar functions that could be generalized
- Repeated configuration
- Copy-pasted logic with minor variations

**POLA (Principle of Least Astonishment):**
- Surprising function behaviors
- Misleading names
- Unexpected side effects
- Non-obvious API designs

**YAGNI (You Aren't Gonna Need It):**
- Unused code or features
- Premature abstractions
- Over-configurable systems
- Speculative generality

See [principles-reference.md](principles-reference.md) for detailed examples.

### Step 5: Use Context7 for Documentation

When evaluating idioms or best practices, use Context7 MCP tools to look up:

- Current React patterns and hooks documentation
- C# language feature documentation
- .NET framework best practices
- Package-specific usage patterns

This ensures recommendations align with current (not outdated) best practices.

### Step 6: Pass Findings to pm7y-ralph-planner

After completing the analysis, invoke the `pm7y-ralph-planner` agent using the Task tool. Pass your findings as structured input so the planner can generate a proper TASKS.md with validation requirements and learnings tracking.

**Invoke pm7y-ralph-planner with this prompt:**

```
Generate a TASKS.md for codebase review remediation.

## Goal
Fix code quality issues identified during codebase review.

## Project Context
- **Technologies:** [Languages, frameworks, build tools detected]
- **Build command:** [detected build command]
- **Test command:** [detected test command]
- **Review scope:** [quick/standard/comprehensive]

## Key Conventions (from documentation)
- [Convention 1]
- [Convention 2]

## Findings

### High Priority (Critical issues affecting correctness or maintainability)

- **[PRINCIPLE]**: [Brief description]
  - Files: `file1.ext:line`, `file2.ext:line`
  - Action: [Specific action to take]
  - Verify: [How to verify the fix]

[Repeat for each high priority finding]

### Medium Priority (Con