| name | grug-review |
| description | Review code with grug-brain anti-complexity philosophy. Use when reviewing PRs, diffs, or code changes to identify unnecessary complexity. |
| argument-hint | [--epic <EPIC_ID>] |
Grug Code Review
Review code changes through the grug-brain lens. Complexity is the enemy.
Planning Context
Before running the checklist, follow ~/.claude/skills/shared/planning-context.md to resolve an epic (via --epic <EPIC_ID> flag, branch name parse, or fallback) and produce a planning-context block. Surface the block at the top of your output — reviewers and the user see the same intent signal the code authors worked against.
If the loader falls back to "No linked planning context available — reviewing against general code-quality heuristics only.", print that line and proceed with the checklist normally.
When planning context exists, treat explicit design decisions as intentional: complexity the plan chose is not automatically "slop." Flag it only if the complexity exceeds what the decision justifies.
Review Checklist
For each change, ask:
- Complexity check: Does this add complexity? Is it truly necessary?
- Abstraction smell: Is there premature abstraction? Are patterns forced before they emerge?
- Cut points: If refactoring, are the cut points natural or artificial?
- Locality: Is related code kept together or scattered across files?
- Cleverness alert: Is there clever code that should be dumb code?
- YAGNI: Is anything here that is not needed right now?
- Chesterton's Fence: If removing code, do we understand why it existed?
Output Format
Structure your review as:
Complexity Concerns
- List issues where complexity demon has crept in
- Explain why simpler alternative exists
Suggested Simplifications
- Concrete suggestions to reduce complexity
- Show before/after when helpful
Acceptable Complexity
- Acknowledge when complexity is genuinely necessary
- Note tradeoffs that justify the approach
Review Principles
- Three similar lines of code > premature abstraction
- Explicit readable code > compact clever code
- Working code today > perfect code someday
- Integration tests > unit test theater
- Measure before optimizing
Example Feedback
### Complexity Concerns
**Premature abstraction in `DataHandler`**: This abstract base class has only one implementation. Grug say: delete the ABC, keep the concrete class. Abstract when second implementation actually needed.
**Over-engineered error handling**: The retry decorator with exponential backoff handles errors that cannot happen in this context. Grug say: remove decorator, add simple try/except only if error is possible.
### Suggested Simplifications
The `validate_and_transform_and_persist` method does three things. But grug note: these three things always happen together, in this order, nowhere else. Splitting into three methods adds indirection without benefit. Keep as one method, maybe rename to `save_validated`.
### Acceptable Complexity
The caching layer adds complexity but profiler shows 40% latency reduction. Complexity justified by measurement. Grug approve.
