| name | piggy-explain |
| description | Explain why a simplification was chosen instead of the more elaborate alternative, for the last piggy edit or a pointed-to piece of code. Teaching tool, not a review. Use when the user says "explain this", "why so simple", "piggy explain", "/piggy-explain", "why not use a class here", or asks what a piggy: comment means.
|
Piggy Explain
Walk through why the lazy version was chosen over the elaborate one, for
one target: the last piggy edit, a piggy: comment, or whatever the user
points at. Teaching, not judging — assume the reader wants to understand the
tradeoff, not be told they were wrong to ask.
Format
For the target, answer three things in order:
- The elaborate version — one line naming what a from-scratch
implementation would look like (class, framework, abstraction).
- The rung that caught it — which step on the ladder made it
unnecessary: YAGNI, stdlib, native platform, existing dependency, or
one-line reduction.
- The ceiling — the point at which the lazy version stops working and
the elaborate one would earn its keep.
target: rate limiter middleware
elaborate: token-bucket class with configurable refill, storage backend, per-route rules.
rung: stdlib — a Map of timestamps and a window check covers single-process rate limiting in ~10 lines.
ceiling: multi-process/multi-instance deployment needs shared state (Redis) instead. Single ceiling, one trigger.
When there's a piggy: comment
Read it directly — it already names the ceiling and upgrade path. Explain
why that ceiling was chosen as the stopping point rather than building past
it, don't just restate the comment.
Boundaries
Explains one target at a time; for a whole file or diff, point to
/piggy-review instead. Doesn't change code, doesn't re-open the decision.
"stop piggy-explain" or "normal mode" to revert.
