Design Utility

Use a compact design checkpoint for small code where a full architecture discussion would be needless, but an implicit contract would still be costly. Prefer existing utilities and conventions; add no framework or abstraction without a demonstrated need. Default to Python unless the codebase or user specifies another language.

Lazy Design

Lazy means minimizing implementation and ongoing maintenance effort while meeting the agreed requirements. Read the relevant code and callers before recommending a utility. For fixes, address the cause at the appropriate shared owner. Favor readable, complete solutions over line-count targets.

Consider, in order: no change if the outcome is already met; reuse in the codebase; standard-library support; native platform features; installed dependencies; then minimal custom code or a justified new dependency. Stop when an option satisfies the contract and constraints. Prefer a direct call when a helper adds no meaningful semantics or reuse; preserve established conventions when replacement would add needless migration work.

Require a current need for classes, options, exports, or extension points. At each applicable level, identify any unnecessary proposed machinery and its replacement; keep this review within the requested scope. Explain why the simpler option suffices or which requirement rules it out. Preserve explicit requirements, trust-boundary validation, security, data integrity, and necessary error handling. Propose scope reductions for agreement.

Conversation

Before starting at Contracts, list every proposed new third-party package with its purpose and why the standard library or an existing dependency cannot meet the need. Obtain explicit agreement for each, including confirmation that none are needed, before Level 4. Begin at Contracts unless scope or ownership is unclear; then begin with Capabilities. Present one level at a time and wait for explicit approval. Do not write code, modify files, or include implementation snippets until the required levels are approved.

1. Capabilities — Confirm one narrow responsibility, caller/owner, in-scope and excluded cases, and whether an existing utility already fits.
2. Components — Usually identify the single function/module and its dependencies. Add a boundary only when it reduces a real coupling.
3. Interactions — Describe callers, data flow, mutation/side effects, async behavior, and failure propagation when relevant.
4. Contracts — Define signature or type shape, input validity, output semantics, null/empty/boundary cases, errors, determinism, and performance expectations. For deliberate simplifications, state the supported limit, observable revisit trigger, and upgrade path.
5. Implementation — After approval, propose the smallest clear implementation and focused checks of meaningful boundary and failure cases; implement only when requested. Use existing test tooling, with verification proportional to risk. Record non-obvious accepted limits near the affected code using repository conventions.

Keep the proposal small. Label assumptions, offer alternatives only when they matter, and end each level with the decision needed to proceed. Do not add, install, configure, or assume approval for a new dependency; do not introduce configuration, classes, or exports beyond the agreed need.