review-complexity
Skill4 starsChanged 3 months agoMITView on GitHub
Detect accidental complexity in code changes — unnecessary code that doesn't serve the domain problem. Use when reviewing a branch or pull request for over-engineering, defensive null checks, redundant exception handling, and similar smells.
In this repository19 other files it gives its agents.
- AGENTS.mdAGENTS.md
- adapter-contract-testingSkill
- azure-devops-prSkill
- bugszero-root-causeSkill
- legacy-3pSkill
- port-refactoringSkill
- quality-gateSkill
- review-ai-writingSkill
- review-allSkill
- review-architectureSkill
- review-driftSkill
- review-impactSkill
- review-prSkill
- review-securitySkill
- review-slopSkill
- review-testingSkill
- scope-challengeSkill
- teams-local-messagesSkill
- write-testsSkill
The file
Files
Accidental Complexity Review Skill
Specialized code review focused on accidental complexity — unnecessary code that doesn't serve the domain problem.
Reference
See docs/accidental-complexity-guide.md for
the full smell catalogue with examples, detection heuristics, and the linter rules that
measure each smell, and docs/code-design-rules.md for
the shape a suggestion should point at — a missing value object or a missing
behaviour-bearing type is behind more of these smells than any other single cause.
Protocol: docs/review-protocol.md — arguments, ref resolution, exhaustiveness, severity levels, report shape. Read it first.
Its § 4 Be exhaustive is mandatory; the lens steps it refers to are steps 2–3 (Apply the complexity lens, Challenge each finding) below.
Process
- Resolve refs and gather the diff — per
review-protocol.md. Apply the complexity lens — for each changed file, hunt for:
Critical (design holes):
- Null/None checks inside domain logic
- Emptiness guards on collections before an operation that should already be a safe no-op on empty — no reliable search exists for these, so reason about every conditional whose subject is a collection (see the guide, 1.4)
- Optional arguments that are never actually null
- Defensive programming hiding broken contracts
Major (structural complexity):
- Multi-layer exception handling (adapter + service + caller all catching)
- Boolean flag parameters that split behaviour
- Always-null optional arguments
- Emptiness guards around already-safe collection operations
- Middle-man classes that just delegate
- God objects / classes doing too much — linters and CodeScene for the screen, then the
method × attribute matrix (guide §10) for what is inside;
scripts/class_cohesion.pycomputes it for Python - Long functions — the longest function the protocol's § 2 listed, against
code-design-rules.mdrule 4 - A primitive with logic tied to it that crosses a port or a router naked
(
code-design-rules.mdrule 1). Primitive includeslist/set/dict. Major because wrapping is one of the first refactoring moves: once the primitive has spread through every signature, the type costs a migration instead of a constructor
Minor (code smells):
- Long parameter lists (>4 params)
- Speculative generality (YAGNI violations)
- Unnecessary class/state (could be a function)
- A primitive nobody computes on, or a data clump inside one module
- Nested conditionals (arrow anti-pattern)
The primitive step is not optional. For every new or changed dataclass, port signature and router or handler parameter in the diff, list each
str,int,float,bool,datetimeand each collection of them, and write next to it what logic is tied to it (a format, a comparison, a parse, a default, a lookup key) and what type it stands in for. A list with nothing next to any line is the finding "none"; a missing list is a missing step. Tools give a screen — CodeScene's primitive-obsession percentage,ruff PLR2004for magic values — but both under-count; the list is the check.- Challenge each finding:
- Can this be removed entirely?
- Can complexity be pushed elsewhere (up the stack, into an adapter)?
- Is there a simpler design that eliminates the need?
- Confirm § 4 of the protocol is satisfied, then generate report →
reviews/complexity-review-issues.md
Severity Model
| Severity | Indicators |
| Critical | Null checks in domain logic, emptiness guards before operations already safe on empty, optional params never used as null, exception handling masking design flaws |
| Major | Multi-layer try/catch, boolean flags splitting behaviour, unnecessary delegation, feature envy, a primitive with logic on it crossing a port or a router |
| Minor | Long param lists, speculative generality, unnecessary state, a primitive nobody computes on |
Output Format
# Accidental Complexity Review: {branch-name}
## Critical Issues
### 1. Title
**Location:** path/to/file:123
**Smell:** name of the pattern
**Why it matters:** brief explanation of the hidden cost
**Suggestion:** concrete refactor to eliminate the complexity
## Major Issues
...
## Minor Issues
...
## Summary
- X Critical, Y Major, Z Minor issues
- Overall complexity health assessmentExample Usage
review-complexity # Current branch vs main
review-complexity feat/foo # Specific branch
review-complexity feat/foo dev # Different base
review-complexity 3574 # PR/MR by numberDoes it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

