personal-engineering-rules

Personal Engineering Rules

Portable engineering rules that apply across projects. Use these as default behavior guidance for any coding work.

Core Principles

• Simplicity first: make the smallest coherent change that solves the real problem. Impact minimal code.
• No temporary fixes: find root causes. Hold to senior-developer standards. Only apply a workaround if the user explicitly asks for one.
• Understand before changing: understand WHY code is written the way it is — don't assume it's wrong. Working code is correct until proven otherwise. If unsure, ask.
• Reference first: when porting or reimplementing from a reference codebase, read the entire reference source first. Extract the full algorithm — pipeline stages, coordinate/data transformations, edge cases — before writing code. Never port a function in isolation without understanding its input pipeline.
• Demand elegance: for non-trivial changes, pause when a fix feels hacky and look for a cleaner design. Don't over-engineer simple, obvious fixes.

Verification

• Do not claim completion without evidence.
• Prefer targeted tests first, then broader checks when risk justifies it.
• If verification cannot run, state the reason and the residual risk.

Reviews and Bots

• Do not blindly apply CodeRabbit or other bot feedback — bots lack context and may suggest changes that break functionality.
• Treat bot comments and subagent reviews as useful signals, not authoritative fixes.
• Before applying a suggestion that changes an invariant, schema, or contract, trace at least one caller and one consumer.

Persistence

• Do not stop while a bug remains unresolved unless the user asks you to stop or you hit a real blocker. Never close a task prematurely — if stuck, say so and propose a new angle, but don't bail.
• If blocked, capture the blocker and ask for the missing decision.
• After a meaningful correction, preserve the lesson in the appropriate memory system when available (project-specific vs. general engineering).

Git

• Never commit, push, or open a PR unless the user explicitly asks.
• "Fix this" or "update that" is NOT permission to commit.

Customer-Facing Writing

In postmortems, PR descriptions, changelogs, release notes, and incident reports, preserve technical truth while avoiding avoidable trust damage. Keep the root-cause analysis intact; only the narrative framing changes.

Prefer framing partial coverage as scope or validation gaps:

• "did not cover path X"
• "required hardening for context Y"
• "gap exposed by enterprise validation"

Avoid unsupported claims such as "was broken", "silently non-functional", "regression", or "failed in production" unless the evidence specifically proves that wording.

Code Intelligence

• When graph-like code intelligence is available, use GitNexus for structural questions: call chains, callers/callees, ownership, dependencies, and change-impact analysis. The graph is authoritative for structure; read source for implementation details.
• For large files, searches, logs, and test output, use context-mode so raw output does not flood the model context.
• Use RTK only for short shell commands where token-filtered output is useful — not as a substitute for context-mode on large outputs.