Less-Is-More-Skill AGENTS.md

Less Is More

Leave the system easier to inspect, explain, change, and trust.

Prefer, in order: no edit, deletion, consolidation, replacement, then a narrow addition. This is a decision order, not a checklist to perform or narrate. Correctness, explicit product requirements, user data, and useful product character outrank line count. Simplicity is measured in mechanisms, not lines: competing owners, sources of truth, states, branches, fallbacks, abstractions, dependencies, and things that must change together. Smallest means fewest mechanisms at the right depth, never the smallest diff — a bandaid at the wrong layer is a large change disguised as a small one, and a larger edit that deletes a mechanism is often the smaller change.

This skill is a loop, not a preamble: re-apply the decision order at each new sub-task, and re-read "Finish subtractively, then stop" immediately before reviewing the final diff.

Establish the real problem

Know which kind of work the request is — audit, bug fix, feature, simplification — and do not call new product behavior simplification. If the request is materially ambiguous, contradictory, destructive, or likely to affect user data, ask one precise question; otherwise state the narrowest safe assumption and proceed.

1. Start from real state. Read the applicable repository instructions, current files, configuration, dependencies, tests, generated sources, and working tree. Protect unrelated user changes. Do not reason from memory when the current system can be inspected — and that includes data: print an artifact's actual shape (top-level keys, one row) before parsing or mutating it.
2. Name the invariant and owner. State what must be true, which component enforces it, what state and side effects it owns, and what success and failure mean. If the invariant or owner is unclear, keep investigating.
3. Verify what can drift. Confirm framework behavior, platform rules, external APIs, dependencies, and other time-sensitive facts against current primary sources. Say unknown when evidence is unavailable.
4. Trace end to end. Follow inputs, state, persistence, concurrency, cancellation, lifecycle, side effects, callers, and downstream consumers. Work from the ownership boundary, not only the reported symptom or diff window.
5. Audit the shape before writing. Look for duplicate state, competing owners, second sources of truth, obsolete branches, abandoned migrations, unsupported compatibility, unacceptable fallbacks, unused configuration, hand-edited generated output, and abstractions that guard no real boundary. Before deleting apparently dead code, check reachable callers, supported clients, persisted data, migrations, and deployment paths.
6. Choose the smallest coherent operation. Consider no edit, deletion, consolidation, and direct replacement before addition. Reuse the project's existing owner, idiom, helper, or platform primitive before creating another. For non-trivial work, be able to say briefly why the choice beats the strongest realistic alternative; do not produce a ritual options table.
7. Verify the real outcome. Use focused regression tests where behavior changed. A new regression test is evidence only after it has been shown able to fail — run it against the unfixed behavior, or break the fix once — and its fixture must provably reach the code under test; prefer exact assertions, since a negative assertion ("does not contain") passes vacuously when the setup silently produces nothing. Remove tests that pin behavior the change deliberately made obsolete, naming the requirement that obsoleted them; never delete a test merely because it fails. Match verification to the claim: an internal event is not proof of audible playback, visible rendering, durable persistence, delivered data, or completed teardown. Use real integration, lifecycle, device, or human checks when software tests cannot establish the result.