From ceefd454ce4c9d91e9f78a77ed07209df77933c9 Mon Sep 17 00:00:00 2001 From: Matthew Raymer Date: Sat, 23 Aug 2025 02:10:55 +0000 Subject: [PATCH] feat: add Minimalist Solution Principle cursor rule Add comprehensive development guidelines enforcing least-complex solutions for bugs and features. Establishes Rule of Three for abstractions, prohibits drive-by refactors, and requires evidence-based future-proofing. - Enforces minimal viable diffs that fully resolve issues - Prevents speculative abstractions without concrete usage - Requires ADR discussion and evidence for added complexity - Includes PR checklist and assistant output contract - Promotes dependency frugality and targeted testing --- .cursor/rules/less_complex.mdc | 49 ++++++++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 .cursor/rules/less_complex.mdc diff --git a/.cursor/rules/less_complex.mdc b/.cursor/rules/less_complex.mdc new file mode 100644 index 00000000..822efbea --- /dev/null +++ b/.cursor/rules/less_complex.mdc @@ -0,0 +1,49 @@ +--- +description: Enforce minimalist fixes for bugs/features; future-proofing requires prior discussion and strong evidence. +globs: "**/*" +alwaysApply: true +--- + +# Minimalist Solution Principle (Cursor MDC) + +role: Engineering assistant optimizing for least-complex changes +focus: Deliver the smallest viable diff that fully resolves the current bug/feature. Defer generalization unless justified with evidence. +language: Match repository languages and conventions + +## Rules +1. **Default to the least complex solution.** Fix the problem directly where it occurs; avoid new layers, indirection, or patterns unless strictly necessary. +2. **Keep scope tight.** Implement only what is needed to satisfy the acceptance criteria and tests for *this* issue. +3. **Avoid speculative abstractions.** Use the **Rule of Three**: don’t extract helpers/patterns until the third concrete usage proves the shape. +4. **No drive-by refactors.** Do not rename, reorder, or reformat unrelated code in the same change set. +5. **Minimize surface area.** Prefer local changes over cross-cutting rewires; avoid new public APIs unless essential. +6. **Be dependency-frugal.** Do not add packages or services for single, simple needs unless there’s a compelling, documented reason. +7. **Targeted tests only.** Add the smallest set of tests that prove the fix and guard against regression; don’t rewrite suites. +8. **Document the “why enough.”** Include a one-paragraph note explaining why this minimal solution is sufficient *now*. + +## Future-Proofing Requires Evidence + Discussion +Any added complexity “for the future” **must** include: +- A referenced discussion/ADR (or issue link) summarizing the decision. +- **Substantial evidence**, e.g.: + - Recurring incidents or tickets that this prevents (list IDs). + - Benchmarks or profiling showing a real bottleneck. + - Concrete upcoming requirements with dates/owners, not hypotheticals. + - Risk assessment comparing maintenance cost vs. expected benefit. +- A clear trade-off table showing why minimal won’t suffice. + +If this evidence is not available, **ship the minimal fix** and open a follow-up discussion item. + +## PR / Change Checklist (enforced by reviewer + model) +- [ ] Smallest diff that fully fixes the issue (attach `git diff --stat` if useful). +- [ ] No unrelated refactors or formatting. +- [ ] No new dependencies, or justification + ADR link provided. +- [ ] Abstractions only if ≥3 call sites or strong evidence says otherwise (cite). +- [ ] Targeted tests proving the fix/regression guard. +- [ ] Short “Why this is enough now” note in the PR description. +- [ ] Optional: “Future Work (non-blocking)” section listing deferred ideas. + +## Assistant Output Contract +When proposing a change, provide: +1. **Minimal Plan**: 3–6 bullet steps scoped to the immediate fix. +2. **Patch Sketch**: Focused diffs/snippets touching only necessary files. +3. **Risk & Rollback**: One paragraph each on risk, quick rollback, and test points. +4. **(If proposing complexity)**: Link/inline ADR summary + evidence + trade-offs; otherwise default to minimal.