Design

Develop the idea far enough that implementation can proceed confidently. Preserve exploration and design pressure without turning every request into a ceremony.

Start with context

Inspect the smallest useful set of materials:

• Applicable AGENTS.md
• The current implementation path
• Nearby tests, schemas, or product documents
• Existing patterns that constrain the decision

Do not scan the whole repository unless the decision is truly cross-cutting.

Classify reference material

A product description, tutorial, screenshot, example implementation, log, or design document may be:

• Inspiration: adopt only the qualities or behavior the user selected.
• Evidence: use it to test a claim about current or desired behavior.
• Normative: treat it as binding only when the user or repository makes it part of the accepted contract.

Route by the requested outcome, not the artifact format. A screenshot does not automatically require design exploration, and a long tutorial does not automatically become the project specification. Explicit written instructions and corrections override inferred visual or tutorial details. Ask about the source's role only when the distinction materially changes the result and cannot be inferred safely.

Reconstruct the problem

State, in compact form:

• Desired user or system outcome
• Current behavior
• Hard constraints and non-goals
• Proposed mechanism and the assumptions behind it
• Decisions already made by the user
• Material unknowns

Treat the user's existing direction as real input. Do not reopen settled choices simply to manufacture alternatives.

A proposed mechanism is not automatically a settled decision. Unless the user explicitly makes it a requirement, preserve the outcome and constraints while independently evaluating whether that mechanism is the best supported route. Do not agree into avoidable complexity, and do not replace the proposal merely because another design is more familiar.

When the user asks to build, adapt, or borrow a named behavior, preserve that direction and explore only the decisions still needed to implement it. Do not turn an implementation request into an open-ended product workshop.

Check the capability boundary

Before designing a new integration, transport, fallback, or abstraction, verify the assumption that makes it necessary:

• What exact current capability or policy blocks the outcome?
• Is that limitation directly observed, or inherited from one mode, old version, or earlier attempt?
• Does the repository, installed runtime, local help, or authoritative platform documentation already expose a direct supported route?
• How many owners, transports, profiles, persistent states, and trust boundaries does each viable route add?

Use readily available world knowledge to generate alternatives, then verify drift-prone technical facts when the result could change the architecture. Prefer the supported route that removes a boundary while preserving the complete outcome. When a small smoke test can settle the decision cheaply, run it before building the bridge.

Explore the decision surface

Identify the few decisions that change implementation or product behavior. Common examples:

• State ownership
• Persistence and migration
• API or component boundaries
• Error and empty states
• Compatibility
• Rollout and reversibility
• Security or privacy boundaries

For each real decision:

1. Explain the tension.
2. Offer one recommended direction.
3. Include at most two alternatives when they are genuinely viable.
4. State the trade-off in concrete terms.

Do not provide three cosmetic variants merely to satisfy a format.

Work the decision frontier

Use dependency ordering when decisions remain unsettled. Track only material decisions for the current outcome, their prerequisites, and facts that could invalidate them. Keep settled owner choices separate from provisional mechanisms and reversible choices delegated to the agent.

First investigate facts available from the repository, installed runtime, tools, and relevant authoritative documentation. Present only decisions whose prerequisites are settled, with a recommendation grounded in that evidence. Ask dependent questions after the upstream choice is resolved; continue independent work while another branch lacks evidence. Delegation is optional and requires its own value justification.

After each answer or material new fact, revisit only the affected descendants. In a continuing task, update the existing decision or plan record rather than reopening the whole interview. Stop when the current approach and acceptance criteria can be chosen without silently guessing a material owner decision. Unrelated future branches may remain deferred.

For authorized best-effort work, make reversible assumptions and proceed. An explicit request for design only remains design only; discovering a good solution does not grant implementation authority.

Questions

Ask a question only when the answer:

• Changes externally visible behavior,
• Controls an irreversible or destructive choice,
• Selects between materially different architectures, or
• Cannot be inferred safely from the repository and prior discussion.

When useful, ask one focused question at a time during an interactive design conversation. When the user asked for a best-effort design or implementation, make explicit assumptions and continue.

Produce a usable design

Scale the output.

For a local feature, a compact design may include:

• Behavior
• State/data flow
• Main implementation touchpoints
• Edge cases
• Verification

For a cross-cutting change, include:

• Goals and non-goals
• Proposed architecture
• Interfaces and ownership
• Data lifecycle or migration
• Failure handling
• Compatibility and rollout
• Testing strategy
• Open decisions

Use diagrams only when relationships are hard to express in prose.

Stress-test the recommendation

Before finishing, check:

• What existing behavior could regress?
• What happens with stale, partial, duplicate, or missing data?
• What is the simplest path that still supports the real use case?
• Did the chosen mechanism survive comparison with the platform's direct supported paths?
• Is the design creating infrastructure for an imagined future?
• Can the decision be reversed later?
• What evidence will show the implementation works?

Revise once. Do not create an endless self-review loop.

Design documents

Write a persistent design document only when one of these applies:

• The user requests it.
• Multiple sessions or people will rely on it.
• The change alters architecture, public contracts, or stored data.
• The decision record will remain useful after implementation.

Otherwise keep the design inline.

Exit behavior

• If the user asked only for design exploration, stop with the recommendation and open decisions.
• If the user asked to implement, continue to a concise plan or direct implementation according to task size.
• Do not require a separate approval checkpoint when the recommended direction is already supported by the user's request and repository evidence.

Avoid

• A mandatory interview before touching the problem
• Repeating the user's prompt as a long specification
• Reopening settled choices
• Designing every hypothetical future extension
• Treating a small UI adjustment as architecture
• Writing a design document solely to prove design work occurred