sanity-check

# Challenge Complexity Systematic pushback against over-engineering → justified simplicity. <when_to_use> - Planning features or architecture - Choosing frameworks, libraries, patterns - Evaluating proposed solutions - Detecting premature optimization or abstraction - Build vs buy decisions NOT for: trivial tasks, clear requirements with validated complexity, regulatory/compliance-mandated approaches </when_to_use> <stages> Load the `maintain-tasks` skill when applying framework to non-trivial proposals: | Stage | Trigger | activeForm | | ----------- | -------------------------- | -------------------------------- | | Identify | Complexity smell detected | "Identifying complexity smell" | | Alternative | Generating simpler options | "Proposing simpler alternatives" | | Question | Probing constraints | "Questioning constraints" | | Document | Recording decision | "Documenting decision" | Task format: ```text - Identify { complexity type } smell - Propose alternatives to { specific approach } - Question { constraint/requirement } - Document { decision/rationale } ``` Workflow: - Start: Create Identify `in_progress` when smell detected - Transition: Mark current `completed`, add next `in_progress` - Skip to Document if complexity validated immediately - Optional stages: skip Alternative if obvious, skip Question if constraints clear </stages> <escalation> Adjust tone based on severity: ◇ **Alternative** (Minor complexity): > "Interesting approach. Help me understand why X over the more common Y?" ◆ **Caution** (Moderate risk): > "This pattern often leads to { specific problems }. Are we solving for something I'm not seeing?" ◈ **Hazard** (High risk): > "This violates { principle } and will likely cause { specific issues }. I strongly recommend { alternative }. If we must proceed, we need to document the reasoning." </escalation> <triggers> Common complexity smells to watch for: **Build vs Buy**: Custom solution when proven libraries exist - Custom auth system → Auth0, Clerk, BetterAuth - Custom validation → Zod, Valibot, ArkType - Custom state management → Zustand, Jotai, Nanostores - Custom form handling → React Hook Form, Formik **Indirect Solutions**: Solving problem A by first solving problems B, C, D - Compiling TS→JS then using JS → Use TS directly in build tool - Reading file, transforming, writing back → Use stream processing - Storing in DB to pass between functions → Pass data directly **Premature Abstraction**: Layers "for flexibility" without concrete future requirements - Plugin systems for 1 use case - Factories for single implementations - Dependency injection for stateless functions - Generic repositories for 1 data source **Performance Theater**: Optimizing without measurements or clear bottlenecks - Caching before measuring load - Debouncing without user complaints - Worker threads for CPU-light tasks - Memoization of cheap calculations **Security Shortcuts**: Disabling security features instead of configuring properly - `CORS: *` → Configure specific origins - `any` types for external data → Runtime validation with Zod - Disabling SSL verification → Fix certificate chain - Storing secrets in code → Environment variables + vault **Framework Overkill**: Heavy frameworks for simple tasks - React for static content → HTML + CSS - Redux for local UI state → useState - GraphQL for simple CRUD → REST - Microservices for small apps → Monolith first **Custom Infrastructure**: Building platform features that cloud providers offer - Custom logging → CloudWatch, Datadog - Custom metrics → Prometheus, Grafana - Custom secrets → AWS Secrets Manager, Vault - Custom CI/CD → GitHub Actions, CircleCI </triggers> <red_flags> Watch for these justifications — reframe with specific questions: "We might need it later" → "What specific requirement do we have now?" "It's more flexible" → "What flexibility do we need that the simple approach doesn't provide?" "It's best practice" → "Best practice for what context? Does that context match ours?" "It's faster" → "Have you measured? What's the performance requirement?" "Everyone does it this way" → "For problems of this scale? Do they have our constraints?" "It's more enterprise-ready" → "What enterprise requirement are we meeting?" "I read about it on Hacker News" → "Does their problem match ours?" </red_flags> <patterns> Guide toward simpler alternatives with concrete examples: **Feature Flags over Plugin Architecture** ```typescript // Complex interface Plugin { transform(data: Data): Data; } const plugins = loadPlugins(); let result = data; for (const plugin of plugins) { result = plugin.transform(result); } // Simple const features = getFeatureFlags(); let result = data; if (features.transformA) { result = transformA(result); } if (features.transformB) { result = transformB(result); } ``` **Direct over Generic** ```typescript // Complex (premature abstraction) interface DataStore<T> { get(id: string): Promise<T>; } class PostgresStore<T> implements DataStore<T> { /* ... */ } const users = new PostgresStore<User>({ /* config */ }); // Simple (direct, refactor later if needed) async function getUser(id: string): Promise<User> { return await db.query("SELECT * FROM users WHERE id = $1", [id]); } ``` **Standard Library over Framework** ```typescript // Complex import _ from "lodash"; const unique = _.uniq(array); const mapped = _.map(array, fn); // Simple const unique = [...new Set(array)]; const mapped = array.map(fn); ``` **Composition over Configuration** ```typescript // Complex const pipeline = new Pipeline({ steps: [ { type: 'validate', rules: [...] }, { type: 'transform', fn: 'normalize' }, { type: 'save', destination: 'db' } ] }) // Simple const result = pipe( data, validate, normalize, save ) ``` </patterns> <justified> Complexity is appropriate when: 1. **Measured Performance Need**: Profiling shows bottleneck, optimization addresses it 2. **Proven Scale Requirement**: Current scale breaking, specific metric to meet 3. **Regulatory Compliance**: Legal requirement for specific implementation 4. **Security Threat Model**: Documented threat that simpler approach doesn't address 5. **Integration Contract**: External system requires specific approach 6. **Team Expertise**: Team has deep expertise in complex pattern but not simple one Even then: - Document why in ADR - Add TODO to revisit when constraints change - Isolate complexity to smallest possible scope - Provide escape hatches </justified> <workflow> Apply this protocol systematically: ### 1. IDENTIFY → Recognize complexity smell Scan proposal for common triggers: - Build vs Buy - Indirect Solutions - Premature Abstraction - Performance Theater - Security Shortcuts - Framework Overkill - Custom Infrastructure ### 2. ALTERNATIVE → Propose simpler solutions Always provide **concrete, specific alternatives** with examples: ❌ Vague: "Maybe use something simpler?" ✅ Specific: "Use Zod for validation instead of building a custom validation engine. Here's how..." Include: - Exact library/pattern name - Code snippet showing simpler approach - Why it's sufficient for actual requirements ### 3. QUESTION → Investigate constraints Ask probing questions to uncover hidden requirements: - "What specific requirement makes the simpler approach insufficient?" - "What will break in 6 months if we use the standard pattern?" - "What performance/scale problem are we solving?" - "What security threat model requires this complexity?" - "What team capability gap makes the standard approach unsuitable?" ### 4. DOCUMENT → Record decisions If complexity chosen after validation: - Document specific requirement that justifies it - Add ADR (Architecture Decision Record) explaining trade-offs - Include TODO for revisiting when requirements change - Add comments explaining non-obvious complexity </workflow> <rules> ALWAYS: - Apply pushback protocol to non-trivial proposals - Provide concrete alternatives with code examples - Ask specific questions about constraints - Match escalation level to severity (◇/◆/◈) - Document justified complexity decisions NEVER: - Accept "might need it later" without concrete timeline - Allow security shortcuts without threat model - Skip questioning performance claims without measurements - Proceed with indirection without clear justification - Accept complexity without documenting why </rules> <references> - [decision-framework.md](references/decision-framework.md) — full decision checklist - [redux-overkill.md](examples/redux-overkill.md) — challenging Redux for simple form - [custom-auth.md](examples/custom-auth.md) — challenging custom auth build </references>