Engineering Philosophy

Principles

• Architecture — Class responsibilities defined in the project's architecture map (often docs/architecture.md).
• KISS — Simple solutions over complex ones.
• YAGNI — Build only what's needed now. Less code is better.
• Minimal Scope - Narrowest visibility that works: keep methods and attributes private (_name in Python) unless something outside the class needs them; don't export what only one module uses. Widen only when a real consumer appears.
• Write Less - If you can avoid writing the code or the comment, don't. A comment earns its place only when it says what the code cannot: a why, an invariant, a magic-number derivation, never a restatement. Default every comment to one line. Multi-line is allowed ONLY for a byte-layout, a derivation, or a non-obvious why that needs the room. This covers every comment, source, config, and CI YAML alike; before committing, re-read each comment you added and cut it to one line or delete it.
• One-Line Diagnostics - Error messages and comments fit on one line within the line-length limit; keep exception texts short enough that the whole raise statement is a single line.
• DRY — Single source of truth. Never copy-paste. Reuse spans the repo: prefer an existing sibling idiom over a second variant.
• OOP — Follow OOP approach and best practices.
• SOLID — Enforce Single Responsibility; keep the others in mind when possible.
• No Magic — Make everything explicit. No hidden behaviour or implicit transformations.
• No Number Without Measurement — Performance figures in docs (gas, latency, throughput, proof sizes) MUST come from a real measurement: a test run, a profile, a fixture, or an upstream spec citation. Author-quoted "approximately X" without a source is a future-self trap; either remove the number or measure it first. Same for scaling claims ("supports 10k concurrent users"): unmeasured is hope, not fact.
• Small Steps — Minimal changes, commit often.
• Stay In Scope - Change only what the task requires. Don't fix, reformat, or rename unrelated code you happen to read, even when it looks wrong: note it and leave it. Off-task diffs are harder to review and revert; genuine cleanups earn their own PR.
• Specs Lead, Code Follows - The spec, plan, and interface contracts are the source of truth; code conforms to them, not the reverse. When your code contradicts the spec (shape doesn't fit, an Open/TBD item blocks you, a requirement looks wrong), stop and surface it for a human instead of rewriting the spec to match. Retro-fitting the spec destroys the audit trail and closes coordination points left open on purpose.
• Use Libraries — Prefer established libraries (ORMs, validators, parsers) over reimplementing features. Check the ecosystem before writing custom code.
• Backwards Compatibility — Don't keep code for backwards-compatibility purposes.
• CI — Automate all possible quality checks.
• Investigate, Don't Mask — When a check fails or unexpected behaviour occurs, investigate the root cause instead of adding defensive code to mask the symptom.
• Fail Fast — Detect and surface errors immediately at the point of failure. Use assertions, strict validation, and early returns.
• Be Brief — Imperative output. No preamble, no recap, no restating the task back. Compress response prose, never operational checklists: keep every named rule, severity word, sub-check, and category from the active skill verbatim — cut the explanation around them, not the rule itself. Applies to chat replies, commit messages, PR bodies, review findings, and any other text the agent emits.

Application

These principles are judgement weights, not rules. When two principles conflict, this skill defers to the workflow skill driving the task:

• During designing-architecture: KISS, YAGNI, Use Libraries, and No Magic dominate. Reject premature abstractions and speculative configurability.
• During reviewing-changes: SOLID, DRY, Investigate-Don't-Mask, Fail Fast, and Stay In Scope dominate. Flag defensive try/except that hides root causes; flag duplication; flag oversized classes; flag edits to files outside the change's stated scope.
• During running-tdd-cycles: Small Steps, Stay In Scope, and Fail Fast dominate. One requirement per red-green-refactor; one logical change per commit; touch only the files that requirement needs.

When a user proposes a change that violates one of these principles, name the principle and explain the consequence — don't just refuse.