
alwaysApply: false

---

# 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

0. **Principle:** just the facts m'am.
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.

  One paragraph each on risk, quick rollback, and test points.
5. **(If proposing complexity)**: Link/inline ADR summary + evidence +
   trade-offs; otherwise default to minimal.

## Model Implementation Checklist

### Before Proposing Changes

- [ ] **Problem Analysis**: Clearly understand the specific issue scope
- [ ] **Evidence Review**: Gather evidence that justifies the change
- [ ] **Complexity Assessment**: Evaluate if change requires added complexity
- [ ] **Alternative Research**: Consider simpler solutions first

### During Change Design

- [ ] **Minimal Scope**: Design solution that addresses only the current issue
- [ ] **Evidence Integration**: Include specific evidence for any complexity
- [ ] **Dependency Review**: Minimize new dependencies and packages
- [ ] **Testing Strategy**: Plan minimal tests that prove the fix

### After Change Design

- [ ] **Self-Review**: Verify solution follows minimalist principles
- [ ] **Evidence Validation**: Confirm all claims have supporting evidence
- [ ] **Complexity Justification**: Document why minimal approach suffices
- [ ] **Future Work Planning**: Identify deferred improvements for later
