@accelerationguy/accel 1.0.0

package/modules/radar/src/domains/08-performance.md

@@ -0,0 +1,247 @@
+---
+id: domain-08
+number: "08"
+name: Scalability & Performance
+owner_agents: [performance-engineer]
+---
+
+## Overview
+
+Covers algorithmic complexity, N+1 queries, caching strategy, resource usage patterns, async behavior, bottlenecks, and backpressure. Scaling failures are often design bugs, not hardware limits — an O(n^2) algorithm in a hot path or an N+1 query pattern in a list endpoint will defeat any amount of horizontal scaling.
+
+Scope: algorithmic complexity in critical paths, database query patterns, caching strategy and invalidation, connection pool management, async/blocking behavior, memory allocation patterns, batch processing efficiency, pagination, and backpressure mechanisms. Does NOT cover infrastructure capacity planning (domain 10), data model optimization (domain 02), or business logic correctness (domain 03).
+
+## Audit Questions
+
+- Are there algorithmic complexity hotspots — O(n^2) or worse operations in request-handling paths?
+- Does the system exhibit N+1 query patterns in list/collection endpoints?
+- Is there a caching strategy, and how is cache invalidation handled?
+- Are connection pools properly sized for database, HTTP clients, and message brokers?
+- Is I/O handled asynchronously where appropriate, or do synchronous blocking calls bottleneck throughput?
+- Are there memory allocation patterns that grow with request volume rather than staying bounded?
+- Is batch processing used where appropriate, or are operations performed one-at-a-time in loops?
+- Is pagination implemented for all list endpoints, and does it use efficient cursor-based or keyset pagination?
+- Is backpressure implemented — what happens when producers outpace consumers?
+- What system resources grow linearly with user count, and what grows sub-linearly?
+- Are there known performance bottlenecks, and are they instrumented for monitoring?
+- Are database queries optimized with appropriate indexes for common access patterns?
+
+## Failure Patterns
+
+### N+1 Query Problem
+
+- **Description:** A list operation issues one query to fetch a collection, then N additional queries to fetch related data for each item — turning what should be 1-2 queries into N+1 queries that scale linearly with data size.
+- **Indicators:**
+  - ORM lazy-loading of relationships inside loops
+  - Database query count that scales linearly with list size
+  - Slow list endpoints where individual item endpoints are fast
+  - Database monitoring showing thousands of nearly identical queries per request
+- **Severity Tendency:** high
+
+### Missing Pagination
+
+- **Description:** Endpoints return unbounded result sets, causing memory exhaustion and timeout failures as data grows.
+- **Indicators:**
+  - API endpoints that return all records without limit/offset or cursor
+  - Database queries without LIMIT clause in list operations
+  - Memory usage that spikes proportional to table size during API calls
+  - "SELECT *" patterns without pagination in production code
+- **Severity Tendency:** high
+
+### Unbounded Memory Growth
+
+- **Description:** Memory usage grows continuously without bound, either through genuine leaks (unreleased references) or through design that accumulates data proportional to traffic or time.
+- **Indicators:**
+  - In-memory caches without eviction policies or TTL
+  - Event listener registrations without corresponding cleanup
+  - Growing collections (maps, arrays) that are never pruned
+  - Memory profiling shows steadily increasing heap that doesn't recover after GC
+- **Severity Tendency:** high
+
+### Synchronous Bottlenecks
+
+- **Description:** I/O-bound operations (HTTP calls, file reads, database queries) are performed synchronously, blocking threads and limiting concurrency to the thread pool size.
+- **Indicators:**
+  - Synchronous HTTP calls in async-capable frameworks
+  - Blocking file I/O in request handlers
+  - Sequential database queries that could be parallelized
+  - Thread pool exhaustion under moderate load
+- **Severity Tendency:** medium
+
+### Cache Stampede
+
+- **Description:** When a popular cache entry expires, many concurrent requests simultaneously compute the same expensive result, overwhelming the backend.
+- **Indicators:**
+  - All cache entries for the same key type expire at the same time
+  - Backend load spikes correlating with cache TTL intervals
+  - No locking or probabilistic early expiration on cache refresh
+  - Database query spikes immediately after cache flush or restart
+- **Severity Tendency:** high
+
+### Missing Connection Pooling
+
+- **Description:** Database or HTTP connections are created per-request rather than pooled and reused, causing connection overhead, exhaustion of server-side connection limits, and performance degradation.
+- **Indicators:**
+  - New connection created inside each request handler
+  - Connection count at database approaches server maximum under moderate load
+  - "Too many connections" errors in logs
+  - No connection pool library in dependencies or configuration
+- **Severity Tendency:** high
+
+### Algorithmic Complexity Bombs
+
+- **Description:** O(n^2) or worse algorithms in code paths that process user-controlled input sizes, creating operations whose execution time grows dramatically with data volume.
+- **Indicators:**
+  - Nested loops iterating over the same or related collections
+  - Array `.includes()` or `.indexOf()` called inside loops (O(n) search * O(n) iteration = O(n^2))
+  - String concatenation in loops instead of builder/join patterns
+  - Sort operations inside loops, or repeated full-collection scans
+- **Severity Tendency:** high
+
+### Missing Backpressure
+
+- **Description:** Producers can generate work faster than consumers can process it, with no mechanism to slow producers down, leading to queue overflow, memory exhaustion, or dropped work.
+- **Indicators:**
+  - Unbounded in-memory queues between producer and consumer
+  - No rate limiting on API endpoints that trigger expensive background work
+  - Message queue consumers with no prefetch limit
+  - Worker processes that accept unlimited concurrent tasks
+- **Severity Tendency:** high
+
+## Best Practice Patterns
+
+### Eager Loading / DataLoader Pattern
+
+- **Replaces Failure Pattern:** N+1 Query Problem
+- **Abstract Pattern:** Batch related-data fetching into a single query per relationship type. Either eagerly load relationships when the collection is fetched, or use a DataLoader that collects individual requests and batches them into one query.
+- **Framework Mappings:**
+  - Rails: `includes(:association)` for eager loading, `preload` for separate queries, `eager_load` for JOIN-based loading
+  - Django: `select_related()` for FK joins, `prefetch_related()` for separate batched queries
+  - GraphQL: DataLoader pattern — collects individual `load(id)` calls within a tick and batches into `loadMany(ids)`
+- **Language Patterns:**
+  - SQL: `SELECT * FROM orders JOIN users ON orders.user_id = users.id WHERE orders.id IN (...)` — single query for all related data
+  - TypeScript: `dataloader` library with per-request caching and automatic batching within event loop tick
+
+### Cursor-Based Pagination
+
+- **Replaces Failure Pattern:** Missing Pagination
+- **Abstract Pattern:** Use cursor-based (keyset) pagination for stable, efficient pagination that doesn't degrade with table size. Each page returns a cursor pointing to the last item, and the next page starts from that cursor.
+- **Framework Mappings:**
+  - GraphQL Relay: Connections spec with `first`, `after`, `last`, `before` cursor arguments
+  - Django REST Framework: `CursorPagination` class using encoded cursor tokens
+  - Spring Data: `Pageable` with keyset-based `ScrollPosition` for efficient deep pagination
+- **Language Patterns:**
+  - SQL: `SELECT * FROM items WHERE id > :cursor ORDER BY id ASC LIMIT :page_size` — no OFFSET, uses index scan
+  - Any: Encode last-seen ID or sort key as opaque cursor token returned to client
+
+### Bounded Caching with Eviction
+
+- **Replaces Failure Pattern:** Cache Stampede
+- **Abstract Pattern:** Caches have explicit maximum size, TTL-based expiration, and eviction policies. Cache stampede is prevented through probabilistic early refresh, locking, or stale-while-revalidate patterns.
+- **Framework Mappings:**
+  - Redis: `SETEX` with TTL, `maxmemory-policy allkeys-lru` for automatic eviction, Redlock for distributed locking on refresh
+  - Caffeine (Java): `maximumSize()`, `expireAfterWrite()`, `refreshAfterWrite()` with async refresh to prevent stampede
+  - Node.js: `lru-cache` with `max` entries and `ttl`, `fetchMethod` for stale-while-revalidate
+- **Language Patterns:**
+  - Any: Cache-aside pattern: check cache → if miss, acquire lock → compute → store → release lock (other waiters get lock or read fresh cache)
+  - Any: Probabilistic early expiration: refresh cache entry when `remaining_ttl < random(0, base_ttl * 0.1)` to spread refresh across time
+
+### Resource Lifecycle Management
+
+- **Replaces Failure Pattern:** Unbounded Memory Growth
+- **Abstract Pattern:** Every allocated resource (cache entries, event listeners, connections, buffers) has a defined lifecycle — creation, usage, and cleanup. In-memory collections have maximum sizes or TTL-based eviction. Subscriptions and listeners are deregistered when their owners are destroyed.
+- **Framework Mappings:**
+  - Java: `try-with-resources` for AutoCloseable resources, WeakReferences for cache entries, `@PreDestroy` for cleanup
+  - .NET: `IDisposable` pattern with `using` blocks, `ConditionalWeakTable` for metadata caches
+  - React: `useEffect` cleanup functions for subscriptions, `AbortController` for fetch cancellation on unmount
+- **Language Patterns:**
+  - Go: `defer` for cleanup, `context.WithCancel()` for goroutine lifecycle management
+  - Python: Context managers (`with` statements) for resource cleanup, `weakref` for cache entries that don't prevent GC
+
+### Async-First Architecture
+
+- **Replaces Failure Pattern:** Synchronous Bottlenecks
+- **Abstract Pattern:** I/O-bound operations use async/non-blocking APIs by default. Synchronous blocking is only used for CPU-bound work on dedicated thread pools. The system's concurrency model matches its workload profile.
+- **Framework Mappings:**
+  - Spring WebFlux: Reactive streams with non-blocking I/O throughout the stack
+  - Fastify/Express: `async/await` handlers with non-blocking database drivers (pg-pool, ioredis)
+  - Go: Goroutines with channels — lightweight concurrency without callback complexity
+- **Language Patterns:**
+  - Node.js: `async/await` for all I/O, `Promise.all()` for parallel independent operations
+  - Python: `asyncio` with `aiohttp` for HTTP, `asyncpg` for database — event loop for I/O concurrency
+
+### Connection Pooling
+
+- **Replaces Failure Pattern:** Missing Connection Pooling
+- **Abstract Pattern:** Database and HTTP client connections are managed through pools with configured minimum, maximum, idle timeout, and connection lifetime. Pools are shared across request handlers and monitored for exhaustion.
+- **Framework Mappings:**
+  - HikariCP (Java): High-performance JDBC connection pool with `maximumPoolSize`, `minimumIdle`, `connectionTimeout`, `maxLifetime`
+  - pg-pool (Node.js): PostgreSQL connection pool with `max`, `idleTimeoutMillis`, `connectionTimeoutMillis`
+  - SQLAlchemy (Python): `pool_size`, `max_overflow`, `pool_recycle` configuration for database engine
+- **Language Patterns:**
+  - Any: Pool size = `(core_count * 2) + effective_spindle_count` as starting point (PostgreSQL recommendation)
+  - Any: Connection pool metrics (active, idle, waiting, timeouts) exported to monitoring
+
+### Backpressure Mechanisms
+
+- **Replaces Failure Pattern:** Missing Backpressure
+- **Abstract Pattern:** Consumers communicate capacity to producers. When consumers fall behind, producers are slowed (blocking backpressure), work is shed (load shedding), or excess is redirected (overflow routing). Queue depths are bounded and monitored.
+- **Framework Mappings:**
+  - RabbitMQ: `prefetch_count` limiting unacked messages per consumer, queue `x-max-length` with dead letter routing
+  - Kafka: Consumer group rebalancing with `max.poll.records` controlling batch size
+  - Reactive Streams (Java): `Flux.onBackpressureBuffer(maxSize)` or `onBackpressureDrop()` for explicit strategy
+- **Language Patterns:**
+  - Go: Buffered channels with select-default pattern for non-blocking sends
+  - Node.js: Streams with `highWaterMark` and `drain` event for built-in backpressure
+
+### Complexity-Aware Data Structure Selection
+
+- **Replaces Failure Pattern:** Algorithmic Complexity Bombs
+- **Abstract Pattern:** Data structures and algorithms are chosen based on the complexity requirements of the access patterns they serve. Hot paths are profiled and audited for quadratic or worse operations. Linear search in loops is replaced with hash-based lookups.
+- **Framework Mappings:**
+  - Java: `HashMap`/`HashSet` for O(1) lookups replacing `List.contains()` in loops, `StringBuilder` replacing string concatenation in loops
+  - Python: Set/dict comprehensions for membership testing replacing list iteration, `collections.defaultdict` for grouping
+  - PostgreSQL: Query plan analysis with `EXPLAIN ANALYZE` to detect sequential scans on large tables where index scans are expected
+- **Language Patterns:**
+  - JavaScript/TypeScript: Convert arrays to `Set` or `Map` before loop-based lookups: `const idSet = new Set(ids)` then `idSet.has(id)` instead of `ids.includes(id)`
+  - Any: Pre-sort + binary search or hash-based index for repeated lookups against the same collection
+
+## Red Flags
+
+- ORM calls inside loops (`.find()`, `.get()`, `.load()` per iteration)
+- API endpoints returning collections without pagination parameters
+- In-memory caches without TTL or maximum size
+- Database queries without LIMIT clause in any list operation
+- Nested loops over collections where inner collection size depends on outer
+- No connection pool configuration in database client setup
+- `SELECT *` in production queries
+- Synchronous HTTP calls in async request handlers
+- No rate limiting on public-facing API endpoints
+- Growing memory usage visible in production metrics without plateau
+
+## Tool Affinities
+
+| Tool ID | Signal Type | Relevance |
+|---------|-------------|-----------|
+| sonarqube | Cognitive complexity hotspots, code duplication in performance-critical paths, method length as proxy for algorithmic complexity | primary |
+| semgrep | Pattern detection for N+1 queries, missing pagination, synchronous calls in async contexts, unbounded loops | supporting |
+| git-history | Performance-related commit patterns (commits mentioning "slow", "timeout", "optimize") reveal historical pain points | contextual |
+
+## Standards & Frameworks
+
+- Google SRE performance guidelines — Latency budgets, load testing principles, capacity planning
+- USE Method (Brendan Gregg) — Utilization, Saturation, Errors for resource performance analysis
+- Database optimization patterns — Index design, query planning, denormalization trade-offs
+- Reactive Manifesto — Responsive, Resilient, Elastic, Message-Driven principles for scalable systems
+- Little's Law — L = λW (concurrent requests = arrival rate × average latency) for capacity modeling
+
+## Metrics
+
+| Metric | What It Measures | Healthy Range |
+|--------|-----------------|---------------|
+| Query count per request | Average database queries per API request | <10 for list endpoints, <5 for detail endpoints |
+| P95/P99 response time | Tail latency for API endpoints | P95 <500ms, P99 <2s (application-dependent) |
+| Cache hit ratio | Percentage of reads served from cache | >80% for read-heavy endpoints |
+| Connection pool utilization | Active connections as percentage of max pool size | 30-70% at normal load, <90% at peak |
+| Memory growth rate | Rate of heap growth between GC cycles | Flat or near-zero (no sustained growth) |
+| Algorithmic hotspot count | Number of O(n^2)+ operations in request-handling paths | 0 in hot paths |

package/modules/radar/src/domains/09-maintainability.md

@@ -0,0 +1,271 @@
+---
+id: domain-09
+number: "09"
+name: Maintainability & Code Health
+owner_agents: [senior-app-engineer]
+---
+
+## Overview
+
+Maintainability encompasses code smells, duplication, naming clarity, documentation accuracy, intent visibility, and technical debt management. Research indicates that maintenance activities consume 60-80% of total software lifecycle costs. This domain focuses on code-level quality factors that directly impact the ease and safety of making changes. It does NOT cover architectural patterns (domain 01), testing strategies (domain 06), or change risk analysis (domain 11).
+
+## Audit Questions
+
+- What percentage of the codebase consists of duplicated code blocks or logic?
+- Are class, function, and variable names self-documenting and aligned with domain terminology?
+- How much dead code exists that is no longer called or used by the system?
+- Do comments and documentation accurately reflect current code behavior and intent?
+- Are primitive types used directly where domain objects would improve clarity?
+- What is the average cognitive complexity of functions across the codebase?
+- Is code style consistent within and across modules?
+- Are configuration values scattered throughout the code or centralized?
+- How many functions exceed recommended length thresholds for the language?
+- Does the codebase exhibit patterns of primitive obsession or feature envy?
+- Are magic numbers and strings replaced with named constants?
+- How frequently do developers report confusion about code intent during reviews?
+
+## Failure Patterns
+
+### Excessive Duplication
+
+- **Description:** Identical or near-identical code blocks repeated across multiple locations, increasing maintenance burden and bug propagation risk. Violates the DRY principle and creates change amplification.
+- **Indicators:**
+  - Copy-pasted code blocks with minor variations in variable names
+  - Identical business logic implemented in multiple services or modules
+  - Repeated error handling patterns without abstraction
+  - Similar data transformation logic scattered across layers
+  - Multiple implementations of the same algorithm
+- **Severity Tendency:** medium
+
+### Poor Naming
+
+- **Description:** Class, function, variable, and module names that fail to communicate intent, use inconsistent terminology, or create cognitive load through abbreviations and ambiguity. Forces readers to constantly reference context.
+- **Indicators:**
+  - Generic names like "data," "manager," "handler," "process," "doStuff"
+  - Inconsistent terminology for the same concept across modules
+  - Single-letter variables outside conventional loop contexts
+  - Names that require comments to explain their purpose
+  - Abbreviations that are not universally understood
+  - Names that don't reflect the domain language
+- **Severity Tendency:** medium
+
+### Dead Code Accumulation
+
+- **Description:** Functions, classes, modules, or entire features that are no longer called or used but remain in the codebase. Creates maintenance burden, confusion about system behavior, and false positives in search results.
+- **Indicators:**
+  - Functions with no call sites in the entire codebase
+  - Commented-out code blocks spanning dozens of lines
+  - Modules imported nowhere in the dependency graph
+  - Feature flags that are permanently disabled
+  - Deprecated APIs with no migration path or timeline
+  - Build artifacts for components no longer compiled
+- **Severity Tendency:** low
+
+### Missing Intent Documentation
+
+- **Description:** Code that performs non-obvious operations without explaining why specific decisions were made. Leaves future maintainers guessing about business rules, edge cases, and architectural constraints.
+- **Indicators:**
+  - Complex algorithms with no explanation of their purpose
+  - Magic numbers without comments explaining their significance
+  - Non-obvious workarounds for third-party library issues
+  - Business logic with no reference to requirements or tickets
+  - Conditional branches with unclear business meaning
+  - Performance optimizations without justification
+- **Severity Tendency:** medium
+
+### Primitive Obsession
+
+- **Description:** Overuse of primitive data types (strings, integers, arrays) instead of small domain objects or value types. Scatters validation logic, reduces type safety, and obscures domain concepts.
+- **Indicators:**
+  - String parameters representing enumerated concepts
+  - Parallel arrays or tuples instead of structured objects
+  - Repeated validation of primitive values across the codebase
+  - Functions with multiple primitive parameters instead of domain objects
+  - Type aliases for primitives without behavior or validation
+  - Business logic operating on raw primitives instead of domain types
+- **Severity Tendency:** medium
+
+### Long Methods/Functions
+
+- **Description:** Functions or methods that exceed cognitive complexity thresholds, contain multiple levels of abstraction, or perform many unrelated operations. Reduces comprehensibility and testability.
+- **Indicators:**
+  - Functions exceeding 50 lines in most languages
+  - Multiple levels of nested conditionals or loops
+  - Functions performing I/O, business logic, and presentation in sequence
+  - More than 5 local variables tracking state
+  - Functions requiring horizontal scrolling to read
+  - Methods mixing abstraction levels without clear separation
+- **Severity Tendency:** medium
+
+### Inconsistent Code Style
+
+- **Description:** Lack of uniform formatting, naming conventions, and structural patterns across the codebase. Creates friction during reading, increases cognitive load, and signals weak quality standards.
+- **Indicators:**
+  - Mixed indentation styles (tabs vs. spaces, different widths)
+  - Inconsistent brace placement and spacing conventions
+  - Variable naming that switches between camelCase, snake_case, PascalCase
+  - Some files formatted by linters, others not
+  - Inconsistent error handling patterns (some throw, some return codes)
+  - Mixed quote styles or trailing comma conventions
+- **Severity Tendency:** low
+
+### Scattered Configuration
+
+- **Description:** Configuration values, feature flags, and environment-specific settings spread throughout the codebase rather than centralized. Makes deployment difficult and increases risk of missed configuration during environment changes.
+- **Indicators:**
+  - Hardcoded URLs or connection strings in multiple files
+  - Environment-specific logic in business code
+  - Configuration values duplicated across services
+  - No single source of truth for feature flags
+  - Magic strings representing configuration keys
+  - Configuration embedded in class constructors throughout the codebase
+- **Severity Tendency:** medium
+
+## Best Practice Patterns
+
+### Extract Common Abstractions
+
+- **Replaces Failure Pattern:** Excessive Duplication
+- **Abstract Pattern:** Identify repeated code blocks and extract them into shared functions, classes, or modules with clear single responsibilities. Use parameterization to handle variations while maintaining a single implementation.
+- **Framework Mappings:**
+  - React: Extract custom hooks for repeated stateful logic or component patterns
+  - Spring: Use service classes and utility methods for common business logic
+  - Django: Create model mixins, manager methods, or template tags for reusable patterns
+- **Language Patterns:**
+  - Python: Extract functions/classes, use decorators for cross-cutting concerns
+  - TypeScript: Create utility functions, generic types, and higher-order components
+  - Java: Use inheritance, composition, and utility classes for shared behavior
+
+### Domain-Aligned Naming
+
+- **Replaces Failure Pattern:** Poor Naming
+- **Abstract Pattern:** Use names that directly reflect domain concepts and business terminology. Names should read like natural language and require no additional context to understand their purpose.
+- **Framework Mappings:**
+  - Domain-Driven Design: Use ubiquitous language from bounded contexts
+  - Clean Architecture: Name entities, use cases, and interfaces after business concepts
+  - REST APIs: Use resource nouns and HTTP verbs that match business operations
+- **Language Patterns:**
+  - Python: Use descriptive snake_case names; avoid abbreviations unless domain-standard
+  - TypeScript: Use clear camelCase; leverage type names for additional clarity
+  - Java: Use verbose PascalCase for classes; verbs for methods reflecting actions
+
+### Aggressive Dead Code Removal
+
+- **Replaces Failure Pattern:** Dead Code Accumulation
+- **Abstract Pattern:** Continuously identify and delete unused code. Trust version control for historical reference rather than leaving commented code in place. Use feature flags for temporary disablement, not code comments.
+- **Framework Mappings:**
+  - Git: Use branches for experimental code; rely on history for recovery
+  - Feature Flag Systems: Use LaunchDarkly, Unleash for temporary feature disablement
+  - CI/CD: Add automated dead code detection to build pipelines
+- **Language Patterns:**
+  - Python: Use coverage tools to identify unused modules; remove commented blocks
+  - TypeScript: Use "unused" linting rules; remove imports with no references
+  - Java: Use IDE analysis to find unused classes; delete deprecated code after migration
+
+### Intent-Revealing Documentation
+
+- **Replaces Failure Pattern:** Missing Intent Documentation
+- **Abstract Pattern:** Document the "why" rather than the "what." Focus on business context, architectural constraints, non-obvious trade-offs, and edge cases. Use code structure and naming to make the "what" self-evident.
+- **Framework Mappings:**
+  - JSDoc/TSDoc: Document non-obvious parameters, return value meanings, side effects
+  - Javadoc: Explain design decisions, link to tickets, note performance considerations
+  - Python Docstrings: Use Google or NumPy format for structured intent documentation
+- **Language Patterns:**
+  - Python: Use module-level docstrings for context; inline comments for "why" only
+  - TypeScript: Use TSDoc for public APIs; inline comments for business rule references
+  - Java: Use Javadoc for public interfaces; comments for complex algorithms only
+
+### Value Objects and Domain Types
+
+- **Replaces Failure Pattern:** Primitive Obsession
+- **Abstract Pattern:** Replace primitive types with small, immutable domain objects that encapsulate validation, behavior, and business meaning. Use type systems to enforce domain constraints at compile time.
+- **Framework Mappings:**
+  - Domain-Driven Design: Create value objects for domain concepts like Money, EmailAddress
+  - Type Systems: Use branded types or newtypes to prevent primitive mixing
+  - ORMs: Define custom column types for domain value objects
+- **Language Patterns:**
+  - Python: Use dataclasses or attrs for value objects with validation
+  - TypeScript: Use branded types, classes, or Zod schemas for domain types
+  - Java: Use records or immutable classes with private constructors
+
+### Single-Purpose Functions
+
+- **Replaces Failure Pattern:** Long Methods/Functions
+- **Abstract Pattern:** Extract functions to perform one task at one level of abstraction. Functions should read like a table of contents, delegating details to lower-level functions. Aim for functions under 20 lines in most cases.
+- **Framework Mappings:**
+  - Clean Code: Apply Extract Method refactoring until each function has one reason to change
+  - Functional Programming: Use function composition to build complex operations from simple ones
+  - SOLID Principles: Apply Single Responsibility Principle at function level
+- **Language Patterns:**
+  - Python: Use clear function names; extract inner functions or private methods
+  - TypeScript: Use arrow functions for small operations; extract named functions for clarity
+  - Java: Use private methods for decomposition; apply Extract Method refactoring
+
+### Automated Style Enforcement
+
+- **Replaces Failure Pattern:** Inconsistent Code Style
+- **Abstract Pattern:** Use automated formatters and linters integrated into development workflow and CI/CD pipeline. Remove style decisions from code review by enforcing standards automatically.
+- **Framework Mappings:**
+  - Pre-commit Hooks: Use Husky, pre-commit to format before commit
+  - CI/CD: Fail builds on style violations; use formatters as validation steps
+  - IDE Integration: Configure auto-format on save with project-wide settings
+- **Language Patterns:**
+  - Python: Use Black for formatting, Ruff or Flake8 for linting
+  - TypeScript: Use Prettier for formatting, ESLint for code quality rules
+  - Java: Use Google Java Format or Prettier Java; Checkstyle for validation
+
+### Centralized Configuration Management
+
+- **Replaces Failure Pattern:** Scattered Configuration
+- **Abstract Pattern:** Consolidate all configuration into dedicated files or configuration management systems. Load configuration once at application startup and inject it through dependency injection or context objects.
+- **Framework Mappings:**
+  - 12-Factor App: Store config in environment variables; never in code
+  - Spring: Use application.properties/yml with profiles for environment-specific config
+  - Environment Management: Use dotenv, viper, or similar libraries for configuration loading
+- **Language Patterns:**
+  - Python: Use python-dotenv, pydantic Settings for typed configuration
+  - TypeScript: Use dotenv with Zod validation; create typed config objects
+  - Java: Use Spring @ConfigurationProperties or MicroProfile Config
+
+## Red Flags
+
+- Duplication percentage above 5% of total codebase
+- More than 10% of functions exceed language-specific complexity thresholds
+- Class or function names containing "Manager," "Utility," "Helper," "Data" without qualifiers
+- Dead code percentage above 2% of total codebase
+- Configuration values hardcoded in more than one location
+- Inconsistent indentation or formatting across files
+- Functions regularly exceeding 50 lines
+- Comments explaining what code does rather than why it exists
+- Multiple implementations of the same business logic
+- Magic numbers without named constants
+- Over 15% of codebase consists of commented-out code blocks
+
+## Tool Affinities
+
+| Tool ID | Signal Type | Relevance |
+|---------|-------------|-----------|
+| sonarqube | Code smells, duplication, cognitive complexity | primary |
+| semgrep | Anti-patterns, code smells, custom rules | supporting |
+| git-history | Code churn patterns, refactoring history | supporting |
+| gitleaks | Hardcoded secrets in configuration | contextual |
+
+## Standards & Frameworks
+
+- Clean Code (Robert Martin) — principles for readable, maintainable code
+- Refactoring (Martin Fowler) — catalog of code smell patterns and refactorings
+- Cognitive Complexity (SonarSource) — metric for measuring code understandability
+- DRY Principle (Don't Repeat Yourself) — minimizing duplication through abstraction
+- Code Complete (Steve McConnell) — comprehensive guidance on code construction quality
+- SOLID Principles — single responsibility applies to functions and modules
+
+## Metrics
+
+| Metric | What It Measures | Healthy Range |
+|--------|-----------------|---------------|
+| Duplication Percentage | Percentage of codebase that is duplicated code | < 3% |
+| Cognitive Complexity Average | Average cognitive complexity per function | < 10 |
+| Dead Code Percentage | Percentage of codebase that is unused | < 1% |
+| Code Churn Rate | Percentage of code rewritten within 3 weeks | < 15% |
+| Function Length Average | Average lines of code per function | < 25 lines |
+| Comment-to-Code Ratio | Ratio of comment lines to code lines | 10-20% |