| name | pragmatism |
| description | Guides durable engineering judgment for software design, implementation, refactoring, debugging, and review. Use when deciding scope, choosing between designs, simplifying code, evaluating trade-offs, or judging how much change a problem deserves. |
Pragmatism
Pragmatism is disciplined judgment under real constraints. Build what solves the problem, fits the system, and can be maintained by the next person.
Start With Reality
Understand the actual problem before changing code.
Read the surrounding system until the change has a natural home.
Prefer evidence from code, behavior, tests, logs, and users over guesses.
Separate the reported symptom from the underlying cause.
Solve the shared cause when the same flaw can surface through multiple paths.
Do not satisfy the wording of a request while leaving the real problem intact.
Respect The Existing System
Treat the codebase as the record of decisions already paid for.
Follow established conventions unless they block the change or cause harm.
Reuse local patterns, helpers, and boundaries before introducing new ones.
Improve the current design before replacing it.
Make the new code look inevitable in its surroundings.
Avoid novelty that future maintainers must decode before they can work.
Prefer The Smallest Complete Change
Make the smallest change that fully solves the problem.
Small does not mean partial. Preserve behavior, invariants, and coherence.
Delete code when deletion is the clearer fix.
Avoid speculative features, unused options, and flexibility with no present caller.
Do not build the second implementation before the second need exists.
Stop when the problem is solved and the remaining work is only imagined.
Keep Complexity Honest
Every abstraction must earn its cost.
Add a layer only when it removes real duplication, clarifies ownership, or protects a boundary that already matters.
Prefer direct code over indirection that only renames the same idea.
Prefer boring structures that reveal intent quickly.
Do not hide simple behavior behind architecture.
Let complexity live only where the domain requires it.
Own What You Add
Treat every dependency, flag, setting, public surface, and extension point as future maintenance.
Add a dependency only when it clearly beats what the platform, standard library, or codebase already provides.
Prefer fewer moving parts when the behavior is stable and local.
Prefer explicit ownership when the behavior crosses boundaries or affects data, security, money, or trust.
Leave fewer things to configure unless variation is already real.
Preserve The Hard Parts
Never simplify away correctness, security, data integrity, accessibility, observability, or recovery from failure.
Validate at trust boundaries.
Handle errors where ignoring them would lose data, corrupt state, or mislead users.
Keep edge cases that the domain actually needs.
Choose the simple robust option over the simple fragile one.
Refactor With Purpose
Refactor when it makes the requested change safer, removes proven duplication, or clarifies a boundary.
Do not refactor to express taste.
Keep unrelated cleanup separate unless it is required to finish safely.
Prefer incremental improvement over dramatic rewrites.
Leave the system easier to change along the path it is already taking.
Explain Trade-Offs
Name the cost of the chosen solution.
Name what was deliberately not built.
Name the condition that would justify revisiting the decision.
Prefer a clear limitation over hidden ambition.
Make future work visible without making it today's work.
Finish With Evidence
Verify the behavior at the smallest useful level.
Match verification effort to risk.
Use existing checks when they already cover the change.
Add focused checks when the change introduces logic, fixes a bug, or protects a contract.
Do not let verification become a second place to speculate.
Default Posture
Read first.
Find the cause.
Change less.
Reuse more.
Name trade-offs.
Protect the hard parts.
Leave maintainable code.
