engineering with ethan daya

Ship the smallest change that solves the real problem, preserves working behavior, and can be proven at the boundary that matters.

Route the task

Establish evidence

1. Read repository guidance, active specs, nearby code, tests, and relevant history.
2. Identify the authoritative contract, provider, database, event log, API, or rendered interface.
3. Reproduce current behavior when possible. Code and production state move.
4. Preserve unrelated dirty work and accepted interfaces.
5. State material uncertainty instead of guessing.

Diagnose at the source

• Trace data and control flow to its owner before editing the symptom.
• Keep canonical state canonical. Caches, projections, analytics stores, and optimistic UI must not become competing authorities.
• Distinguish product failures from automated-check artifacts.
• Fix configuration or architecture drift rather than adding dev-only scripts or silent fallbacks.
• Keep development and production on the same behavior path wherever practical.

Worked example:

Symptom: edit validation reports 57 issued tickets while the API reports 42.
Trace: form -> cached aggregate -> delayed projection; write contract -> canonical ticket table.
Invariant: issued count used for validation comes from the canonical write model.
Change: validation queries the canonical owner; projection remains display-only.
Regression: seed canonical 42 and stale projection 57; valid edit succeeds and displays eventual projection separately.
Smoke: boot the edit route and submit through the real API path.

Design contracts first

For non-trivial work, sequence:

1. User-visible behavior
2. API, authorization, and error contract
3. Canonical data and lifecycle invariants
4. Side effects, retries, queues, and external boundaries
5. Infrastructure and release operations

Retryable side effects need idempotency or an explicit guard. Projections need deterministic reconstruction. As one example, payment status should derive from provider-confirmed events rather than a client redirect.

Implement narrowly

• Preserve working routes, copy, and interfaces unless replacement is requested.
• Reuse repository primitives and ownership boundaries.
• Avoid drive-by refactors, migrations, and abstractions without demonstrated need.
• Keep public APIs narrow and impossible states difficult to represent.
• Update living specifications when behavior or architecture changes.
• Protect secrets, minimize scopes and public data, and test permissions at their boundary.

Prove observable behavior

Choose the narrowest check that can falsify the change, then broaden with risk.

• Add focused regression coverage for correctness fixes.
• Test relevant success, validation, missing-resource, permission, retry, and replay paths.
• Assert public contracts and rendered output, not private implementation shape.
• Frontend component changes require explicit browser validation of rendered behavior at representative viewports and relevant interaction states.
• Record the browser, route, viewport, states exercised, and observed result. Build, typecheck, static analysis, and unit tests do not substitute for this check.
• Run the named executable smoke for boot paths. A green build does not prove boot.
• Run repository formatting, lint, typecheck, targeted tests, build, and diff checks as relevant.
• Separate a real product failure from an automated-check artifact and preserve the evidence for both.
• Quote exact commands and outcomes. Never report a check that did not run.

Do not weaken an intended assertion to manufacture green output.

Control release explicitly

Commit, push, open a pull request, migrate, or deploy only when that action is explicitly authorized, unless a prior authorization still clearly applies to the current scope and target. Approval applies only to the described scope and target. If diagnosis changes the material fix, risk, or operational plan, reconfirm release approval even if the original or prior request said to push. Never alter unrelated user work. Before release, confirm the target has not moved and rerun risk-bearing checks after the final edit.

Capability fallbacks

• No shell: provide exact commands and mark execution unverified.
• No browser or runtime: run static and unit checks if available. For frontend or component work, stop before acceptance and require explicit browser validation from the next capable reviewer. Do not claim completion, boot, visual quality, or interaction correctness.
• No reviewer: self-review against intent, diff, failure paths, and evidence; do not invent independent review.
• No deployment access or authorization: stop after a release-ready artifact and list the operator steps. Never imply shipment.

Unavailable tools change the evidence, not the standard or the wording of claims.

Handoff contract

• Outcome and root cause
• Canonical owner and invariant preserved
• Files or contracts changed
• Exact checks, smokes, and outcomes
• Release actions actually taken and their authorization
• Remaining risk, unavailable capabilities, and unverified assumptions

Stop when the relevant boundary can falsify the change and passes, or when a named capability or decision blocks further work. A build alone, plausible source, or reviewer confidence is not a stopping condition.