complexity-analysis

Unnecessary complexity in architecture emerges from premature abstraction, over-engineering for hypothetical scale, and misaligned design patterns. This Skill detects complexity smells—layering without need, generalization before validation, framework choices that exceed requirements—and surfaces simpler alternatives with trade-off documentation so you build only what solves the immediate problem.

Challenge proposed solutions during feature planning, architecture decisions, and framework selection. Over-engineering commonly occurs when teams abstract prematurely, add patterns in advance of real constraints, or choose tools for future scale rather than current need. This Skill applies a phase-driven workflow to surface real requirements, evaluate cost and reversibility, and document why simpler paths were rejected.

Necessary complexity solves a validated problem with documented trade-offs; technical debt accumulates from premature abstraction and deferred decisions. This Skill distinguishes between them by requiring evidence of real need, assessing reversibility, and guiding risk-aware decisions so complexity added today is justified and documented, not hidden cost.

Build versus buy decisions often fail when teams over-engineer custom solutions or over-commit to heavy frameworks. This Skill provides a decision framework that weighs cost, scale, and reversibility to reveal when buying or building a minimal version outweighs a complex custom approach, with documented reasoning for each choice.

Yes. Premature abstraction is a primary trigger for unnecessary complexity. This Skill implements checks that validate abstraction against real requirements, question generalization before patterns are proven, and document why abstraction was deferred or accepted, preventing patterns and layers from accumulating without justification.

Complexity analysis produces documented outcomes: a record of alternatives considered, trade-offs evaluated, decisions justified, and escalation guidance if risk remains unresolved. This documentation anchors future decisions, clarifies why simplicity was chosen, and creates a shared reference for why the current design exists.