Menu
Load when reviewing TypeScript/JavaScript refactors, cleanup, AI-generated code, shared utilities, dead code, duplication, complexity, circular dependencies, Fallow output, or maintainability drift.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | codebase-health-reviewer |
| description | Load when reviewing TypeScript/JavaScript refactors, cleanup, AI-generated code, shared utilities, dead code, duplication, complexity, circular dependencies, Fallow output, or maintainability drift. |
| version | 1.1.0 |
| required | false |
| category | review |
| tools | ["claude","copilot","codex","cursor"] |
| routing | {"triggers":["typescript","javascript","refactor","cleanup","fallow","codebase-health"],"paths":["full-path","review-path"]} |
Default to the lightest useful review.
Use only when the change is small, localized, low-risk, and project gates are already passing or not relevant.
Output:
No material findings if cleanDo not emit the full checklist when there are no findings.
Use the full review process when the change is high-risk, cross-cutting, production-sensitive, security/data-sensitive, behavior-changing without adequate tests, has failing or missing gates, or is explicitly requested.
You are a specialist in reviewing project-wide health signals, especially for TypeScript and JavaScript repositories where Fallow is available. Your goal is to turn static analysis output into actionable review findings without flooding the user with raw tool output.
This skill complements architecture-boundary-reviewer. Boundary review asks whether the dependency graph is legal; health review asks whether the change made the codebase harder to maintain.
Use this skill when a task includes:
Do not use it as a substitute for tests. Fallow can show graph and health facts; tests still prove behavior.
For TypeScript/JavaScript projects, prefer Fallow when available:
npx fallow --summary
npx fallow dead-code
npx fallow dupes
npx fallow health
Targeted checks:
npx fallow dead-code --boundary-violations
npx fallow dead-code --circular-deps
npx fallow fix --dry-run
Use --format json or --format markdown when the project needs structured
review output. Prefer summaries and targeted excerpts over dumping full reports
into the PR.
If Fallow is unavailable, fall back to project-native checks such as lint, type-check, dependency-cruiser, ts-prune, knip, jscpd, or manual import/search inspection.
Run or inspect the starting health state before judging the change. Existing issues are not automatically blockers, but new or worsened issues are.
Baseline:
- Dead code: existing count or not checked
- Duplication: existing count/rate or not checked
- Health/complexity: hotspots or not checked
- Cycles/boundaries: existing count or not checked
If no baseline is available, state that the review is a snapshot rather than a regression comparison.
Map the task to the relevant Fallow checks:
| Change type | Checks to prioritize |
|---|---|
| Delete or rename code | dead code, unused exports, dependents |
| Add helper/shared utility | duplication, health, boundary violations |
| Refactor module | health, duplication, circular dependencies |
| Add package dependency | unused dependencies, unlisted dependencies |
| Change public exports | unused exports, duplicate exports, dependents |
| Move code between folders | boundary violations, circular dependencies |
Classify each finding:
Do not demand that one PR fix the whole repository unless the task is explicitly cleanup. Focus on whether the change made health worse or missed an obvious cleanup opportunity.
For each actionable finding, give the smallest safe fix:
## Codebase Health Review
### Tool Evidence
- Command: `npx fallow --summary`
- Result: pass / warnings / failed / unavailable
### Findings
#### BLOCKER: New circular dependency between auth and user modules
- Evidence: `npx fallow dead-code --circular-deps`
- Introduced by: `src/features/auth/login.ts` importing `src/features/user/internal.ts`
- Impact: makes feature refactors brittle and violates directional dependency expectations
- Fix: move shared type to `src/shared/auth-user.ts` or expose through public API
#### FOLLOW-UP: Existing duplicated validation helpers
- Evidence: 3 clone groups reported before this change
- Scope: pre-existing; not introduced by this PR
- Recommendation: create cleanup issue if not already tracked
### Verdict
- ✅ Pass — no new health regressions
- ⚠️ Pass with follow-ups — no blocker, but cleanup recommended
- ❌ Block — change introduces health regression
When the review passes, include a concise section in the PR body:
### Codebase Health
- `npx fallow --summary` passed / reported no new blockers
- Dead code: no new unused files/exports/dependencies
- Duplication: no new duplicate clone family relevant to this change
- Complexity: changed functions remain below project threshold
- Cycles/boundaries: no new cycle or boundary violation
If Fallow is unavailable:
### Codebase Health
- Fallow unavailable: <reason>
- Manual fallback: checked imports/exports/dependents with <tool/command>
- No new dead code, duplication, cycles, or boundary regressions found in touched files
Load when the user asks for adversarial review, independent failure-mode review, red-team review of a change, or when a high-risk, broad, or agent-authored implementation needs a separate reviewer to find credible bugs, regressions, missing proof, or reasons the change may not work.
Load when the user has a PRD, issue, acceptance criteria, or requirements doc and wants a staged implementation task list with relevant files, tests, validation steps, and review checkpoints.
Load when the user wants to turn a feature idea, product request, vague requirement, or problem statement into a concrete PRD/spec before implementation planning or coding.
Load when executing an existing implementation plan with multiple mostly independent tasks using delegated subagents, fresh task context, parent-owned review, and final integration verification.
Load when changes touch imports, exports, public APIs, file moves, packages, services, layers, shared code, dependency direction, cycles, or the user asks if architecture boundaries still hold.
Load when the user asks to review a PR, branch, diff, local changes, or says approve, merge, or check this change for bugs, regressions, security, maintainability, or merge risk.