architecting-solutions

Start by clarifying the problem statement, success criteria, and constraints, then analyze existing codebase patterns with grep and file searches. Propose minimal, medium, and comprehensive options with trade-offs, get user approval, and write the final design as a PRD in the docs directory.

List every piece of state being migrated, find all consumers with grep for imports and hook usages, and define a migration strategy per item. Include rollback plans, backward compatibility notes, and before/after code examples so another agent can implement it directly.

Use this skill for architecture and technical design requests like "design solution" or "technical design" that do not mention PRD-specific planning. For dedicated PRD product planning work, the frontmatter directs you to the prd-planner skill instead.

Common root causes include independent hook instances that do not share state, empty callback implementations, and polling timing gaps. Trace the complete call chain from trigger to effect with file paths and line numbers, and draw a timeline to expose when each poll or revalidation fires.

Always check whether an existing mechanism already solves most of the problem before proposing new patterns. Present the absolute minimal change first, and only recommend comprehensive refactoring when the current architecture is fundamentally broken or the user explicitly requests it.