Structured Code Analysis Skill

Description

This skill provides a structured methodology for analyzing codebases. It guides investigation through phases — overview, deep-dive, cross-cutting concerns, and recommendations — with findings tracked and organized throughout.

Instructions

When the user asks you to analyze code or a codebase, follow this structured process:

Phase 1: Project Overview

Gather high-level information:

Copy
# Project structure
find . -type f -name '*.ts' -o -name '*.tsx' -o -name '*.js' | head -50

# Dependencies
cat package.json | jq '.dependencies, .devDependencies'

# Entry points
cat package.json | jq '.main, .scripts'

# Configuration files
ls -la tsconfig.json .eslintrc* .prettierrc* jest.config* webpack.config*

Output:

Copy
## Project Overview

| Aspect | Details |
|--------|---------|
| Language | TypeScript 5.3 |
| Framework | Express.js |
| Test Framework | Jest + Supertest |
| Build Tool | tsc |
| Total Files | 127 (.ts/.tsx) |
| Lines of Code | ~8,400 |
| Dependencies | 23 direct, 8 dev |

Phase 2: Architecture Analysis

Map the system structure:

Copy
## Architecture Map

### Layer Diagram

Routes → Controllers → Services → Repositories → Database ↓ External APIs

### Module Dependencies
- auth/ depends on: users/, config/
- users/ depends on: database/
- payments/ depends on: users/, external/stripe
- notifications/ depends on: users/, external/sendgrid

### Circular Dependencies: NONE FOUND

Phase 3: Deep-Dive Analysis

Focus on specific areas based on findings:

Copy
## Deep-Dive: Error Handling

### Pattern Analysis
- 12/15 route handlers have try/catch blocks
- 3 handlers have unhandled promise rejections
- Global error handler exists in middleware/errorHandler.ts
- Custom error classes: AppError, ValidationError, NotFoundError

### Issues Found
1. **src/routes/payments.ts:45** — No error handling for Stripe API call
2. **src/services/auth.ts:23** — Catches error but swallows it silently
3. **src/controllers/users.ts:67** — Returns raw error message to client (info leak)

Phase 4: Cross-Cutting Concerns

Check areas that span the entire codebase:

Copy
## Cross-Cutting Analysis

| Concern | Status | Notes |
|---------|--------|-------|
| Error handling | Partial | 3 gaps found |
| Logging | Good | Structured logging with pino |
| Authentication | Good | JWT with refresh tokens |
| Input validation | Weak | Only 6/15 routes validate |
| Testing | Moderate | 62% coverage, no e2e |
| Security | Review needed | No rate limiting, CORS too permissive |
| Performance | Unknown | No metrics or profiling |

Phase 5: Recommendations

Prioritized action items:

Copy
## Recommendations

### Priority 1 (Critical)
- [ ] Add error handling to payment routes (data loss risk)
- [ ] Fix error message exposure in user controller (security)
- [ ] Add rate limiting to auth endpoints (security)

### Priority 2 (Important)
- [ ] Add input validation to remaining 9 routes
- [ ] Tighten CORS configuration
- [ ] Add e2e tests for critical flows

### Priority 3 (Nice to Have)
- [ ] Add performance monitoring (APM)
- [ ] Increase unit test coverage to 80%
- [ ] Add OpenAPI documentation

Rules

• Follow the 5-phase process in order — do not skip to recommendations
• Track all findings with file paths and line numbers
• Quantify findings where possible ("3 out of 15 routes" not "some routes")
• Distinguish between facts ("no rate limiting") and opinions ("architecture could be simpler")
• Prioritize recommendations by risk/impact, not by ease of fix
• If the codebase is large (>500 files), focus phases 2-3 on the areas most relevant to the user's question
• Present findings progressively — overview first, details on request
• Do not suggest rewrites unless the user specifically asks for refactoring advice

Examples

User: Analyze this codebase for security issues Action: Full 5-phase analysis with Phase 3 focused on security: auth, input validation, data exposure, dependencies

User: I just joined this team, help me understand the codebase Action: Emphasis on Phase 1-2 (overview and architecture), lighter Phase 3-5

User: Is this code ready for production? Action: Full analysis with emphasis on Phase 4 (cross-cutting concerns) and Phase 5 (prioritized blockers)