simplicity-review

Review code, diffs, and repos for avoidable complexity and over-engineering.

Updated Apr 6, 2026
One-click install
npx skills add https://github.com/toderian/project_template --skill simplicity-review-toderian
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: simplicity-review
Source: https://github.com/toderian/project_template/tree/main/plugins/agents-core/skills/simplicity-review
Command: npx skills add https://github.com/toderian/project_template --skill simplicity-review-toderian

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Codebases accumulate speculative abstractions, hand-rolled standard library behavior, unnecessary dependencies, and wrappers around native platform features. This Skill provides a structured review workflow that identifies what can be deleted, replaced with stdlib or native features, or deferred until a real requirement exists. ## Core Features & Use Cases - Four Review Modes: Run a prebuild check before implementing, review a diff for bloat, audit an entire repo for simplification candidates, or collect a debt ledger of deliberate simplifications marked with simplicity: comments. - Minimal-Correct-Change Ladder: A seven-step decision ladder that prioritizes reusing local code, standard library, native platform features, and existing dependencies before writing new code. - Tagged Findings: Findings are labeled with actionable tags (delete, stdlib, native, yagni, shrink, reuse) and ranked by expected cut and risk. - Use Case: Before adding a new utility library to a project, run a prebuild review to check whether the standard library or an already-installed dependency solves the requirement, avoiding a new dependency entirely. ## Quick Start Ask the assistant to run a simplicity review on the current diff and list anything that can be deleted or replaced with standard library or native platform features.

Frequently Asked Questions about simplicity-review

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I review a pull request for over-engineering?

Use the diff-review mode to inspect only the changed lines and flag new abstractions, dependencies, wrappers, or helpers that outsize the requirement. Findings are tagged and ranked by expected value, starting with the largest safe deletion.

How to find code that can be replaced with standard library functions?

Run a repo audit, which scans dependency manifests, shared utilities, and source directories for hand-rolled behavior the language or runtime already provides. Each finding names the standard API that replaces the custom code.

What is the difference between simplicity review and code correctness review?

Simplicity review targets over-engineering only: dead code, speculative abstractions, and avoidable dependencies. It explicitly excludes security review, spec compliance, accessibility, performance profiling, and regression testing, which belong in separate review passes.

When should I not simplify code?

Do not remove trust-boundary validation, authorization checks, data-loss prevention, accessibility basics, required observability, or user-requested behavior. Simplification must preserve behavior, edge-case correctness, readability, and the repo's established patterns.

How do I track deliberate technical shortcuts in code?

Add a `simplicity:` comment with a known ceiling and a revisit trigger, such as `simplicity: global lock is enough for one worker; revisit when workers run concurrently`. The debt-ledger mode collects these markers and flags any missing revisit triggers.