amio/dot-agents/review-and-refine

Select the Review Mode

• Use Design mode when the primary artifact is an active design document or the user asks to improve a proposed design.
• Use Diff mode when changes have already been implemented and the primary artifact is the current working-tree or staged diff.
• When both a design and an implementation exist, treat the design as the intended contract and the diff as implementation evidence, and review them together for material inconsistencies.
• Infer the mode from the user's request and repository state when it is clear. Ask only when choosing the wrong target would materially change the scope.

Working Method

1. Establish the intended user value, agreed scope, relevant constraints, and artifact under review. In Diff mode, inspect the complete diff plus enough surrounding code, tests, and active design documentation to understand behavior and ownership; do not infer the requirement from the diff alone.
2. Ask a subagent to independently audit the artifact and produce a formal review. Give it the goal, artifact paths, relevant context, and constraints, but do not bias it with prior conclusions.
3. Require the review to report only findings that materially affect correctness, architectural soundness, implementation readiness or quality, or overall simplicity. It must explicitly search for low-value features, edge cases, configurability, compatibility paths, or speculative flexibility whose implementation introduces disproportionate architectural or operational complexity, explain that complexity, and recommend a simpler product or design boundary when appropriate.
4. Evaluate every finding as accept, partial, or reject, with a brief rationale. Ignore optional refinements, stylistic preferences, and improvements whose benefit does not justify further change. If a meaningful simplification would reduce agreed UX flexibility or feature scope, explain the trade-off and ask the user before adopting it.
5. Integrate accepted findings into the reviewed artifact. In Design mode, revise the active design. In Diff mode, correct or simplify the implementation and update high-signal tests or documentation when required. Do not apply feedback mechanically, alter established product contracts without justification, or rewrite sound work for marginal elegance.
6. Validate the refined result at the level appropriate to the mode. Check design consistency and implementation readiness in Design mode; run focused diagnostics and tests for behavior changed in Diff mode, then broader validation when justified by risk.
7. Stop when no unresolved issue materially threatens the goal, correctness, or core architecture. Do not generate additional review rounds for non-essential improvements.

Design Mode Focus

• Verify that requirements and invariants serve the agreed goal and do not silently broaden scope.
• Check component responsibilities, data ownership, dependency direction, data flow, failure handling, and implementation readiness.
• Identify low-value requirements that force additional components, state, coordination, migration paths, or public interfaces.
• Surface unresolved assumptions only when they materially affect the proposed solution.

Diff Mode Focus

• Trace the implementation back to the user goal, active design, and existing system invariants.
• Look for symptom-specific branches, downstream workarounds, duplicated safeguards, or misplaced ownership instead of root-cause fixes.
• Identify unnecessary abstractions, state, configuration, compatibility behavior, public API surface, or cross-module coordination introduced by the change.
• Check meaningful regression risks and whether tests cover the behavior that owns the requirement rather than trivial implementation details.
• Keep the review scoped to the change. Mention pre-existing issues only when they directly invalidate or materially complicate the implementation.

Decision Rules

• Review from a top-down, whole-system perspective, using low-level evidence from the artifact while focusing on the critical path rather than local detail.
• Maintain high cohesion and low coupling, and actively seek meaningful opportunities to remove layers, merge responsibilities, collapse abstractions, or eliminate unnecessary indirection.
• Judge complexity against product value. Prefer removing or narrowing low-value behavior when doing so preserves the core user value, but do not trade away agreed behavior without user approval.
• Prefer the simplest sound, implementation-ready result. Do not favor the current direction because work has begun, but do not replace a sound design or implementation for marginal gains.
• Validate core technical decisions against authoritative sources when they depend on specific APIs, framework behavior, platform constraints, or library capabilities. Flag only mismatches that materially affect the result.