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>

Load the maintain-tasks skill when applying framework to non-trivial proposals:

Task format:

- 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

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."

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

<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>

Guide toward simpler alternatives with concrete examples:

Feature Flags over Plugin Architecture

// 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

// 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

// 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

// 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
)

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

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

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

• •decision-framework.md — full decision checklist
• •redux-overkill.md — challenging Redux for simple form
• •custom-auth.md — challenging custom auth build