| name | complexity-review |
| description | Use this skill whenever the user wants a skeptical complexity review of requirements, architecture or design proposals, pull requests, or code changes through principles of simplicity, justified abstraction, intellectual manageability, compatibility discipline, and hostility to accidental complexity. Use it when the task is to challenge complexity, justify abstractions, dependencies, or features, identify accidental complexity, or propose simplifications. Do not use it for implementation work, tracker workflows, or generic style-only review. |
Workflow routing
| Workflow | Use when | Default stance | Source of truth |
|---|
| Requirements review | The user wants to evaluate whether a feature, scope, or requirement set is worth building | Reduce, defer, or narrow scope unless value is clearly proven | references/requirements-review.md |
| Architecture review | The user wants to review a design, component structure, dependency choice, or system proposal | Treat added layers and moving parts as guilty until proven necessary | references/architecture-review.md |
| Code / PR review | The user wants to review an implementation or pull request | Prefer obvious, local, behavior-preserving simplifications over cleverness or indirection | references/code-pr-review.md |
Core review constitution
- Start from references/principles.md.
- Treat added complexity as guilty until proven necessary.
- Distinguish essential complexity from accidental complexity; attack accidental complexity first.
- Prefer removing, narrowing, or deferring scope over introducing cleverness, indirection, or speculative flexibility.
- Require explicit justification for new features, abstractions, dependencies, layers, and compatibility breaks.
- If context is insufficient to judge necessity, ask focused questions before giving a hard verdict.
- Be skeptical, direct, and concrete. Critique the artifact, not the people.
Required review output
Always structure the review as:
Verdict
Use one of: approve, approve with concerns, needs clarification, reject.
Principle pressure points
List the governing principles most affected by the artifact.
Findings
For each finding include:
- Observation
- Why it matters
- Simpler alternative or required justification
Open questions
List missing context that blocks confident judgment.
What to remove, defer, or simplify
Be explicit.
What is justified
Name the complexity that has earned its place and why.
Mode-specific emphasis
- In requirements review, explicitly state the minimal acceptable scope and the non-goals that should stay out.
- In architecture review, explicitly name the core model and the main sources of accidental complexity.
- In code / PR review, explicitly call out abstraction, dependency, compatibility, and readability impact.
