Yeshwanthyk Architect
Settle a consequential design choice before implementation depends on it. Start from how callers use the capability, then derive types, ownership, dependencies, and failure behavior. Use the smallest design that preserves real invariants and leaves room for known change.
Ground
Read the relevant implementation and tests. Use how for current mechanics and why when history or an operational constraint can change the choice. Name the decision seam, callers, current contracts, state and external authorities, fixed constraints, and unresolved gaps. Do not treat filenames or conventions as intent.
Sketch
Write caller-facing usage before the type sketch. Show the dominant calls, inputs, outputs, and failure handling; two or three examples are useful when they expose different contracts, but use fewer for a narrow case. Derive data structures from those access patterns and parse external, storage, or framework data at the boundary.
Describe module responsibilities, dependency direction, state transitions, side effects, observability, migration, rollout, and production/test substitution points. For novel choices with multiple viable approaches, apply the exhaust-the-design-space principle before selecting a shape. Prefer a small public surface that hides real policy; consult design-red-flags.md. Use the candidate and rationale templates for a design that will be handed to others. Run arena only when competing whole-shape alternatives would materially improve the decision.
Record the selected shape, rejected alternatives, tradeoffs, risks, and open questions. Keep the rationale beside the sketch for larger changes.
When the decision seam concerns stage ownership, publication, replay, or metadata gates, consult forward implementation first. Use it within the current design decision, not as another architecture phase.
For that decision, consider Jev to classify proposed actions as implementation, validation, bookkeeping, or uncertain when bounded triage would reduce design work. First establish each action's effect and contractual obligations from the source. Follow the action-classifier contract: when enabled and transmission is approved, use the available Jev choice tool with only that evidence; otherwise continue locally. Treat the answer as advice, not proof or permission to remove a control.
Implement or hand off
An architecture-only request ends with the selected design and its rationale. If implementation is already requested, continue without adding a new approval checkpoint. If implementation reveals a mismatch, determine whether the sketch, requirement, or implementation was wrong and update the design before adding exceptions. Verify the wiring that matters to the changed contract.
Delegation is optional. When useful, follow delegation, use runner-prompt.md, and review the actual candidate artifacts; do not delegate a shared mutable write target.
Redesign signal
Return to the sketch when repeated workarounds, casts, always-present optionals, caller knowledge of internals, or multiple deviations expose the same boundary problem. Subtract dead weight and choose again with the new constraint. Leave a deliberate unresolved constraint visible when it cannot yet be removed.
Output
Lead with the target shape and why it fits. Include caller usage, types/signatures, module and ownership map, boundary contracts, production/test wiring, migration and rollout, verification points, tradeoffs, risks, rejected alternatives, and open decisions as applicable.
Completion
Architecture is complete when an executor can implement the selected shape from live contracts, ownership, dependency direction, invariants, failure behavior, migration/rollout, and proof points, with material alternatives and unknowns made explicit. Do not turn a settled mechanical choice into an architecture exercise.