mize/docs/general-agent-guide.md

Require clarification and plan approval before making architectural code changes

Before making any code changes which could be considered to influence the architekture of the application, you must follow this two-step process:

Step 1: Ask Clarifying Questions

• Always ask at least one clarifying question about the user's request
• Understand the full scope and context of what they're asking for
• Clarify any ambiguous requirements or edge cases
• Ask about preferred approaches if multiple solutions exist
• Confirm the expected behavior and user experience
• Ask the clarifying questions by numbering them, so the user can number their replies.

Step 2: Present Implementation Plan

• After receiving clarification, present a detailed implementation plan
• Break down the work into specific, actionable steps
• Identify which files will be created, modified, or deleted
• Explain the technical approach and any architectural decisions
• Highlight any potential risks, trade-offs, or dependencies
• Estimate the complexity and scope of changes
• Wait for explicit user approval before proceeding with any code changes

What are considered architectural changes

Architectural (clarify → plan → wait for approval), for example:

• New parts, or new cross-part method / opt surfaces
• Wiring one part into another (e.g. UI shell calling auth.client.login, soft-notify via has_part)
• Changes to core loading / has_part / part-system semantics
• Splitting or merging capabilities across part boundaries

Not architectural (implement directly when the intent is clear), for example:

• Layout / CSS / copy tweaks in an existing screen
• Adding another display line or button that only uses existing local state or already-exposed methods
• Bugfixes that don’t change the part API (e.g. document::Style re-render warnings)

Approval Requirements

• User must explicitly approve the plan with words like "yes", "approved", "proceed", "go ahead", or similar
• If the user suggests modifications to the plan, incorporate them and seek re-approval
• Do not assume silence or ambiguous responses mean approval

Exceptions

• This process may be skipped only for trivial changes like fixing obvious typos or formatting
• When in doubt, always follow the full process rather than assuming an exception applies

Example Workflow

1. User: "Add a login form to the app"
2. Assistant: "I'd like to clarify a few things about the login form: [questions]"
3. User: [provides answers]
4. Assistant: "Based on your requirements, here's my implementation plan: [detailed plan]. Does this approach look good to you?"
5. User: "Yes, that looks good"
6. Assistant: [writes plan to file].
7. Assistant: [proceeds with implementation].