autonomous-coding-toolkit 1.0.0

package/docs/lessons/0029-never-write-secrets-to-files.md

@@ -0,0 +1,61 @@
+---
+id: 29
+title: "Never write secret values into committed files"
+severity: blocker
+languages: [all]
+scope: [universal]
+category: silent-failures
+pattern:
+  type: syntactic
+  regex: "(api_key|token|password|secret)\\s*=\\s*['\"][^'\"]{8,}"
+  description: "Actual secret values hardcoded in source files"
+fix: "Reference secrets by env var name only; in tests use mock values; enforce with pre-commit hooks"
+example:
+  bad: |
+    # config.py
+    API_KEY = 'sk-1234567890abcdef'
+    DATABASE_PASSWORD = 'prodPassword123'
+
+    # Committed to repo, exposed to anyone with access
+  good: |
+    # config.py
+    import os
+    API_KEY = os.environ.get('API_KEY', '')
+    DATABASE_PASSWORD = os.environ.get('DATABASE_PASSWORD', '')
+
+    # .env (never committed, sourced by deployment)
+    API_KEY=sk-1234567890abcdef
+    DATABASE_PASSWORD=prodPassword123
+---
+
+## Observation
+
+Secrets hardcoded in source files are committed to version control, exposing them to anyone with repo access. Even after deletion, secrets remain in git history forever.
+
+## Insight
+
+Source code is assumed to be shareable (it's version-controlled, reviewed, archived). Secrets are the opposite (must be kept private, rotated, compartmentalized). Mixing them violates the principle of least privilege and creates an irreversible exposure risk.
+
+## Lesson
+
+**Never write secret values (passwords, API keys, tokens) into any file that gets committed:**
+
+1. **Configuration files**: Use environment variables with `os.environ.get()` (Python) or `process.env` (Node.js)
+2. **Tests**: Use mocks, fixtures, or test fixtures; never real credentials
+3. **.env files**: Create locally, gitignore them, source them at runtime
+4. **Pre-commit hooks**: Add linters (gitleaks, detect-secrets) to reject commits containing secrets
+
+If a secret is committed:
+
+1. Rotate it immediately (invalidate the exposed credential)
+2. Scrub it from history (git filter-branch, BFG repo cleaner)
+3. Document the incident
+
+Recommended workflow:
+
+- `config.py` reads from `os.environ`
+- `.env` (gitignored) contains local values
+- CI/deployment sets env vars via secrets manager (Vault, AWS Secrets, etc.)
+- Tests use fixtures/mocks, no real credentials
+
+Verify by inspecting the last 50 commits: `git log --all -S 'sk-' | head -50` should find zero matches.

package/docs/lessons/0030-cache-merge-not-replace.md

@@ -0,0 +1,62 @@
+---
+id: 30
+title: "Cache/registry updates must merge, never replace"
+severity: should-fix
+languages: [python, javascript, all]
+scope: [universal]
+category: integration-boundaries
+pattern:
+  type: semantic
+  description: "Cache update replaces entire cache instead of merging, losing entries from other modules"
+fix: "Use cache.update(new_entries) not cache = new_entries"
+example:
+  bad: |
+    # Module A
+    cache = {'user:1': 'Alice'}
+
+    # Module B updates cache
+    def refresh_posts():
+        posts = fetch_posts()
+        cache = {'post:1': 'Hello'}  # Replaces entire cache!
+        # user:1 lost
+
+    # Now cache only has posts, users are gone
+  good: |
+    # Shared cache object
+    cache = {}
+
+    # Module B updates cache (merge, don't replace)
+    def refresh_posts():
+        posts = fetch_posts()
+        cache.update({f'post:{p.id}': p for p in posts})
+        # All previous entries preserved
+
+    # Cache has both users and posts
+---
+
+## Observation
+
+When multiple modules access a shared cache, replacing it from one module loses entries written by others. A refresh operation in Module B that replaces the cache erases data from Module A that's still valid.
+
+## Insight
+
+Cache semantics depend on ownership. If the cache is owned by one module, that module can replace it. If it's shared, updates must be additive or selective. Replacement (assignment) assumes sole ownership; without it, you lose data from other modules.
+
+## Lesson
+
+When updating a shared cache or registry:
+
+1. **Merge, don't replace**: Use `cache.update()` (Python dict), `Object.assign()` (JavaScript), or similar. Never reassign the cache variable.
+2. **Selective update**: If you need to replace specific keys, use `cache.pop(key)` then `cache[key] = value`, or `cache.update({key: value})`.
+3. **TTL/expiry**: For caches with stale data, use timestamps or TTLs instead of wholesale replacement. Stale entries expire; fresh entries remain.
+4. **Ownership**: Document which module owns the cache. If multiple modules write to it, document the contract: "All posts keys start with `post:`, all user keys start with `user:`. Modules only touch their namespace."
+
+Example of selective update:
+
+```python
+# Only replace posts, keep other entries
+posts_dict = {f'post:{p.id}': p for p in new_posts}
+cache.update(posts_dict)  # user:1 and user:2 still there
+```
+
+Test this by simulating concurrent updates and verifying data from both modules persists.

package/docs/lessons/0031-verify-units-at-boundaries.md

@@ -0,0 +1,66 @@
+---
+id: 31
+title: "Verify units at every boundary (0-1 vs 0-100)"
+severity: should-fix
+languages: [all]
+scope: [universal]
+category: integration-boundaries
+pattern:
+  type: semantic
+  description: "Data crosses boundary with implicit unit change (proportion vs percentage)"
+fix: "Verify units at every boundary; add unit to variable names (accuracy_pct, ratio_0_1)"
+example:
+  bad: |
+    # Model outputs probability (0-1)
+    def predict(input):
+        return model.predict(input)  # Returns 0.85 (85% confidence)
+
+    # UI assumes percentage (0-100)
+    confidence = predict(data)
+    ui.show_progress_bar(confidence)  # Shows 0.85% instead of 85%!
+  good: |
+    # Clear units in names and documentation
+    def predict(input):
+        return model.predict(input)  # Returns probability_ratio_0_1
+
+    # UI explicitly converts
+    probability_ratio_0_1 = predict(data)
+    confidence_pct = probability_ratio_0_1 * 100
+    ui.show_progress_bar(confidence_pct)  # Shows 85%
+---
+
+## Observation
+
+Data flows between systems with different unit conventions: probabilities (0-1), percentages (0-100), milliseconds vs seconds, ppm vs ppb. A boundary crossing without explicit conversion silently produces wrong results with no error.
+
+## Insight
+
+Unit mismatches are silent failures because both sides are syntactically valid — a number is a number. The bug isn't a crash, it's a wrong result. A 0.85 probability rendered as 0.85% is off by two orders of magnitude but the code runs without error.
+
+## Lesson
+
+At every data boundary (API, database, service-to-service), document and verify units:
+
+1. **Variable names include units**: `accuracy_pct`, `ratio_0_1`, `duration_ms`, `temp_celsius`
+2. **API contracts specify units**: "response returns confidence as float 0-1, not percentage"
+3. **Conversion explicit**: `pct = ratio_0_1 * 100` is clear; `pct = ratio_0_1` is not
+4. **Tests verify conversion**: Test that a 0.5 probability produces a 50% display value
+
+Example contract in docs or code:
+
+```
+GET /model/predict
+Response: { "probability_ratio_0_1": 0.85 }
+The probability is returned as a ratio (0-1), NOT a percentage.
+```
+
+Add unit verification tests:
+
+```python
+result = predict(data)
+assert 0 <= result <= 1, f"Expected probability 0-1, got {result}"
+```
+
+For databases, use migration notes: "analytics.confidence column changed from integer (0-100) to float (0-1) in v2.1."
+
+Verify by running data through all boundaries and spot-checking units at each step.

package/docs/lessons/0032-module-lifecycle-subscribe-unsubscribe.md

@@ -0,0 +1,89 @@
+---
+id: 32
+title: "Module lifecycle: subscribe after init gate, unsubscribe on shutdown"
+severity: should-fix
+languages: [python, javascript]
+scope: [universal]
+category: resource-lifecycle
+pattern:
+  type: semantic
+  description: "Component subscribes to events in constructor but never unsubscribes on shutdown"
+fix: "Subscribe in initialize() after startup gate, store callback ref on self, unsubscribe in shutdown()"
+example:
+  bad: |
+    class EventListener:
+        def __init__(self):
+            self.event_bus = get_event_bus()
+            self.event_bus.subscribe('user_login', self.on_login)
+            # subscribe in __init__, no unsubscribe
+            self.callback_ref = None  # Lost reference
+
+        def on_login(self, event):
+            print(f"User {event.user} logged in")
+
+        # No shutdown method, so callback never unsubscribed
+  good: |
+    class EventListener:
+        def __init__(self):
+            self.event_bus = None
+            self.callback_ref = None
+
+        async def initialize(self):
+            self.event_bus = await get_event_bus()
+            self.callback_ref = self.on_login
+            self.event_bus.subscribe('user_login', self.callback_ref)
+
+        def on_login(self, event):
+            print(f"User {event.user} logged in")
+
+        async def shutdown(self):
+            if self.callback_ref:
+                self.event_bus.unsubscribe('user_login', self.callback_ref)
+                self.callback_ref = None
+---
+
+## Observation
+
+Components subscribe to events in constructors but rarely unsubscribe. On shutdown, stale callbacks remain registered and continue firing, creating memory leaks and ghost events.
+
+## Insight
+
+Constructors are for initialization; cleanup is for shutdown. Mixing them violates the resource lifecycle principle. A callback registered in `__init__` may outlive the component because nothing explicitly removes it.
+
+## Lesson
+
+Follow this subscription lifecycle:
+
+1. **Separate init/shutdown**: Never subscribe in `__init__`. Use an explicit `initialize()` method.
+2. **Store callback reference**: Keep a reference to the callback on `self` so you can unsubscribe later.
+3. **Unsubscribe on shutdown**: In `shutdown()`, unsubscribe and set callback to None.
+
+Pattern:
+
+```python
+class Component:
+    def __init__(self):
+        self.event_bus = None
+        self.on_event_callback = None
+
+    async def initialize(self):
+        self.event_bus = await get_event_bus()
+        self.on_event_callback = self.on_event  # Store ref
+        self.event_bus.subscribe('event_type', self.on_event_callback)
+
+    def on_event(self, event):
+        # Handle event
+
+    async def shutdown(self):
+        if self.on_event_callback:
+            self.event_bus.unsubscribe('event_type', self.on_event_callback)
+            self.on_event_callback = None
+```
+
+Test this by:
+1. Create component
+2. Verify callback is registered (count subscribers)
+3. Shutdown component
+4. Fire event, verify callback doesn't fire (or count unchanged)
+
+This pattern is critical for long-running services where components are created and destroyed repeatedly.

package/docs/lessons/0033-async-iteration-mutable-snapshot.md

@@ -0,0 +1,72 @@
+---
+id: 33
+title: "Async iteration over mutable collections needs snapshot"
+severity: blocker
+languages: [python]
+scope: [language:python]
+category: async-traps
+pattern:
+  type: syntactic
+  regex: "for .+ in self\\..+:"
+  description: "Iterating over instance attribute in async function without snapshot"
+fix: "Snapshot before iterating: for item in list(my_set):"
+example:
+  bad: |
+    class EventDispatcher:
+        def __init__(self):
+            self.subscribers = set()
+
+        async def dispatch(self, event):
+            # Iterating over mutable set in async context
+            for subscriber in self.subscribers:  # Can raise "Set changed during iteration"
+                await subscriber.handle(event)
+
+        async def unsubscribe(self, subscriber):
+            self.subscribers.discard(subscriber)
+  good: |
+    class EventDispatcher:
+        def __init__(self):
+            self.subscribers = set()
+
+        async def dispatch(self, event):
+            # Snapshot before iterating
+            subscribers_copy = list(self.subscribers)
+            for subscriber in subscribers_copy:
+                await subscriber.handle(event)
+
+        async def unsubscribe(self, subscriber):
+            self.subscribers.discard(subscriber)
+---
+
+## Observation
+
+In async contexts, iterating over a mutable collection (set, dict) that can be modified by concurrent code raises `RuntimeError: Set changed during iteration`. Synchronous iteration is safe because the event loop is blocked; async iteration is not.
+
+## Insight
+
+Async/await allows other tasks to run between iterations. If another task modifies the collection you're iterating over, Python raises an error. The instinct is to ignore this risk in single-threaded async code, but multiple tasks can run in the same thread.
+
+## Lesson
+
+When iterating over a collection in an async function:
+
+1. **Always snapshot first**: `for item in list(collection)` creates a snapshot immune to concurrent modification
+2. **Copy the right way**:
+   - Sets: `list(my_set)`
+   - Dicts: `dict(my_dict)` or `list(my_dict.items())`
+   - Lists: `my_list.copy()` or `list(my_list)`
+3. **Verify the pattern**: Grep for `for .+ in self\\.` in async functions and check for snapshots
+
+Pattern:
+
+```python
+async def broadcast(self):
+    # Snapshot before any await
+    handlers_copy = list(self.handlers)
+    for handler in handlers_copy:
+        await handler.process()
+```
+
+Test by subscribing/unsubscribing in a concurrent task while dispatching, and verify no RuntimeError is raised.
+
+This is Python-specific. JavaScript's for-of and async iteration have different semantics, but the same principle applies: if concurrent code modifies the collection, snapshot first.

package/docs/lessons/0034-caller-missing-await-silent-discard.md

@@ -0,0 +1,65 @@
+---
+id: 34
+title: "Caller-side missing await silently discards work"
+severity: blocker
+languages: [python, javascript]
+scope: [universal]
+category: async-traps
+pattern:
+  type: semantic
+  description: "Async function called without await, coroutine created but never executed"
+fix: "Always await async calls; use create_task() with done_callback for fire-and-forget"
+example:
+  bad: |
+    async def save_to_database(data):
+        await db.save(data)
+        print("Saved!")
+
+    async def main():
+        save_to_database(data)  # Missing await!
+        # Function never executed, "Saved!" never prints
+        print("Done")  # Prints immediately, before save completes
+
+    # Result: data may never be saved
+  good: |
+    async def main():
+        # Option 1: await (blocking)
+        await save_to_database(data)
+
+        # Option 2: fire-and-forget with task
+        task = asyncio.create_task(save_to_database(data))
+        task.add_done_callback(handle_save_error)
+
+        print("Done")
+---
+
+## Observation
+
+Calling an async function without `await` creates a coroutine object but doesn't execute it. The work is discarded, often silently. In Python, the event loop may warn "coroutine was never awaited"; in JavaScript, it's silent.
+
+## Insight
+
+Async functions are lazy — they return a coroutine/promise that must be awaited to execute. Missing `await` is a type error (object of wrong type is created), but Python's runtime allows it. This is a language design quirk: async functions look like regular functions but require explicit awaiting.
+
+## Lesson
+
+**Always await async calls:**
+
+1. **Default: await**: `await save_to_database(data)`
+2. **Fire-and-forget**: If you don't want to block, use `asyncio.create_task()` with error handling:
+
+```python
+task = asyncio.create_task(save_to_database(data))
+task.add_done_callback(lambda t: t.result() if t.exception() is None else None)
+```
+
+3. **Never just call**: `save_to_database(data)` is a bug
+
+Linting:
+
+- Python: Use `pylint` with `no-unused-variable` or linters that detect unawaited coroutines
+- JavaScript: Use TypeScript or ESLint with `no-floating-promises` rule
+
+Test: Verify that a fire-and-forget task completes before the program exits. Use a counter or log to verify the callback was called.
+
+This is critical in production: losing async work silently is a data loss bug.

package/docs/lessons/0035-duplicate-registration-silent-overwrite.md

@@ -0,0 +1,85 @@
+---
+id: 35
+title: "Duplicate registration IDs cause silent overwrite"
+severity: should-fix
+languages: [python, javascript, all]
+scope: [universal]
+category: silent-failures
+pattern:
+  type: semantic
+  description: "Multiple components register with the same ID, last one silently overwrites earlier ones"
+fix: "Check for existing registration before inserting; log warning or raise on duplicate"
+example:
+  bad: |
+    class HandlerRegistry:
+        def __init__(self):
+            self.handlers = {}
+
+        def register(self, handler_id, handler):
+            self.handlers[handler_id] = handler  # Silently overwrites
+
+    registry = HandlerRegistry()
+    registry.register('payment', PaymentHandler())
+    registry.register('payment', StripeHandler())  # Oops, overwrites first one
+    # Now only Stripe handler is registered, PaymentHandler is lost
+
+    registry.handle('payment', data)  # Only StripeHandler runs
+  good: |
+    class HandlerRegistry:
+        def __init__(self):
+            self.handlers = {}
+
+        def register(self, handler_id, handler):
+            if handler_id in self.handlers:
+                raise ValueError(f"Handler '{handler_id}' already registered")
+            self.handlers[handler_id] = handler
+
+    registry = HandlerRegistry()
+    registry.register('payment', PaymentHandler())
+    registry.register('payment', StripeHandler())  # Raises ValueError
+    # Bug caught immediately
+---
+
+## Observation
+
+Registries that accept duplicate IDs silently overwrite earlier registrations. A second module registering with the same ID erases the first module's handler, and there's no error.
+
+## Insight
+
+Registries are designed to prevent collisions: each ID maps to one handler. Without collision detection, the register operation becomes a silent update, and duplicate IDs are indistinguishable from intentional overwrites.
+
+## Lesson
+
+When building a registration system (event handlers, plugins, middleware):
+
+1. **Check for duplicates**: Before inserting, verify the ID isn't already registered.
+2. **Three options on duplicate**:
+   - **Reject** (strict): Raise an exception. Fails fast, prevents bugs.
+   - **Warn** (permissive): Log a warning, then overwrite. Allows dynamic reconfiguration but can mask bugs.
+   - **Append** (list-based): If multiple handlers per ID are valid, use a list instead of a dict.
+
+Pattern:
+
+```python
+def register(self, handler_id, handler):
+    if handler_id in self.handlers:
+        raise ValueError(f"Duplicate registration: '{handler_id}'")
+    self.handlers[handler_id] = handler
+```
+
+Or with warning:
+
+```python
+def register(self, handler_id, handler):
+    if handler_id in self.handlers:
+        logger.warning(f"Overwriting handler '{handler_id}'")
+    self.handlers[handler_id] = handler
+```
+
+Test by:
+1. Register handler A with ID 'foo'
+2. Register handler B with ID 'foo'
+3. Verify exception is raised OR warning is logged
+4. Verify the correct handler is in the registry afterward
+
+Choose **reject** (strict) by default unless dynamic reconfiguration is explicitly required.

package/docs/lessons/0036-websocket-dirty-disconnect.md

@@ -0,0 +1,33 @@
+---
+id: 0036
+title: "WebSocket dirty disconnects raise RuntimeError, not close"
+severity: should-fix
+languages: [python]
+scope: [language:python]
+category: resource-lifecycle
+pattern:
+  type: semantic
+  description: "WebSocket send after client disconnects without close frame raises RuntimeError instead of WebSocketDisconnect"
+fix: "Wrap all WebSocket sends in try/except RuntimeError and clean up the connection"
+example:
+  bad: |
+    async def broadcast(self, message):
+        for ws in self.connections:
+            await ws.send_json({"msg": message})
+  good: |
+    async def broadcast(self, message):
+        for ws in self.connections:
+            try:
+                await ws.send_json({"msg": message})
+            except RuntimeError:
+                self.connections.remove(ws)
+---
+
+## Observation
+WebSocket connections that are terminated by the client without a proper close frame (e.g., mobile network loss, browser tab close) raise `RuntimeError` on the next `send()` call, not `WebSocketDisconnect`. This exception type varies by websocket library implementation and client disconnection method.
+
+## Insight
+Developers expect WebSocket sends to raise `WebSocketDisconnect` on all disconnection types, so they only catch that exception. Dirty disconnects bypass the close handshake, triggering RuntimeError instead. This causes unhandled exceptions in broadcast loops.
+
+## Lesson
+Always wrap WebSocket sends in `try/except RuntimeError` in addition to connection-close handlers. Store connection state on `self`, remove failed connections immediately, and log the disconnection for visibility. Test with mobile network loss simulation, not just clean closes.

package/docs/lessons/0037-parallel-agents-worktree-corruption.md

@@ -0,0 +1,31 @@
+---
+id: 0037
+title: "Parallel agents sharing worktree corrupt staging area"
+severity: blocker
+languages: [all]
+scope: [universal]
+category: integration-boundaries
+pattern:
+  type: semantic
+  description: "Multiple agents or CI jobs commit to the same git worktree, corrupting the staging area"
+fix: "Each parallel agent gets its own git worktree; never share a worktree between concurrent processes"
+example:
+  bad: |
+    # Both agents write to same repo
+    Agent A: git add file1.py && git commit -m "feat: A"
+    Agent B: git add file2.py && git commit -m "feat: B"  # corrupts A's staging
+  good: |
+    # Each agent has isolated worktree
+    git worktree add agent-a-branch
+    git worktree add agent-b-branch
+    # Agents work in separate directories
+---
+
+## Observation
+When multiple agents or CI processes write to the same git repository directory concurrently, they interfere with each other's staging area, index locks, and commit state. This results in "fatal: cannot lock ref" errors, lost commits, or commits with wrong file combinations.
+
+## Insight
+Git's index is a single file (`.git/index`) shared across all operations in a repository. The staging area is not thread-safe by design. Concurrent writes to this file corrupt it.
+
+## Lesson
+Never share a git worktree between concurrent processes. Use `git worktree add` to create isolated working directories for each parallel agent. Each worktree has its own index and staging area. Verify worktrees are cleaned up and removed after use.

package/docs/lessons/0038-subscribe-no-stored-ref.md

@@ -0,0 +1,36 @@
+---
+id: 0038
+title: "Subscribe without stored ref = cannot unsubscribe"
+severity: should-fix
+languages: [python, javascript]
+scope: [universal]
+category: resource-lifecycle
+pattern:
+  type: syntactic
+  regex: "\.subscribe\(lambda|\.subscribe\(\s*\("
+  description: "Event subscription with anonymous lambda cannot be unsubscribed later"
+fix: "Store callback on self before subscribing; unsubscribe with stored ref in shutdown"
+example:
+  bad: |
+    def __init__(self):
+        self.emitter.subscribe(lambda event: self.on_event(event))
+
+    def shutdown(self):
+        # No way to unsubscribe -- callback ref lost
+  good: |
+    def __init__(self):
+        self._callback = lambda event: self.on_event(event)
+        self.emitter.subscribe(self._callback)
+
+    def shutdown(self):
+        self.emitter.unsubscribe(self._callback)
+---
+
+## Observation
+Event subscriptions created with inline lambdas or anonymous functions cannot be unsubscribed later because the callback reference is not stored. In shutdown or cleanup code, there's no way to reference the callback to remove it.
+
+## Insight
+The subscriber pattern returns a reference to the callback if you need to unsubscribe later. When the callback is created inline and not stored, that reference is lost immediately after subscription.
+
+## Lesson
+Always store event callbacks on `self` before subscribing. Unsubscribe using the stored reference in `shutdown()` or cleanup methods. Test that subscriptions are properly cleaned up and no callbacks fire after shutdown. This prevents memory leaks and stale event handlers.

package/docs/lessons/0039-fallback-or-default-hides-bugs.md

@@ -0,0 +1,34 @@
+---
+id: 0039
+title: "Fallback `or default()` hides initialization bugs"
+severity: should-fix
+languages: [python]
+scope: [language:python]
+category: silent-failures
+pattern:
+  type: semantic
+  description: "Expression like `self._resource or Resource()` creates new resource every access when _resource was never initialized"
+fix: "Replace with guard return + warning: if not self._resource: logger.warning('not initialized'); return"
+example:
+  bad: |
+    def get_value(self):
+        # If _resource never initialized, creates new one silently
+        return (self._resource or Resource()).value
+
+    # Bug: each call creates a new Resource if never initialized
+  good: |
+    def get_value(self):
+        if not self._resource:
+            logger.warning("Resource not initialized")
+            return None
+        return self._resource.value
+---
+
+## Observation
+Using `or` as a fallback to create a default object (`self._resource or Resource()`) masks initialization bugs. The code never fails; it silently creates a new object on every access, leading to duplicate work, lost state, and difficult-to-trace behavior.
+
+## Insight
+Fallback patterns hide the bug rather than fail fast. The developer doesn't know initialization was skipped because the code "works." State stored in the first Resource is lost on the next access, causing subtle state inconsistencies.
+
+## Lesson
+Replace fallback patterns with explicit guard checks. Log a warning if the resource is not initialized, then return early or raise an exception. This makes initialization bugs fail fast and visible. Test initialization paths explicitly to ensure resources are initialized before first use.

package/docs/lessons/0040-event-firehose-filter-first.md

@@ -0,0 +1,36 @@
+---
+id: 0040
+title: "Process all events when 5% are relevant -- filter first"
+severity: should-fix
+languages: [all]
+scope: [domain:ha-aria]
+category: performance
+pattern:
+  type: semantic
+  description: "Event handler processes every event when only a small fraction are relevant"
+fix: "Filter by domain/type/source at the top of the handler before any expensive operations"
+example:
+  bad: |
+    def on_event(self, event):
+        # Processes every event, even irrelevant ones
+        parsed = expensive_parse(event)
+        if parsed.domain != "target_domain":
+            return
+        self.handle_target(parsed)
+  good: |
+    def on_event(self, event):
+        if event.domain != "target_domain":
+            return
+        # Only expensive parse for relevant events
+        parsed = expensive_parse(event)
+        self.handle_target(parsed)
+---
+
+## Observation
+Event handlers receive high-volume event streams (e.g., Home Assistant state_changed, MQTT topic subscriptions). Filtering happens after expensive operations (parsing, decoding, database lookups) instead of before, wasting CPU on irrelevant events.
+
+## Insight
+Early filtering is a free optimization. Checking a simple field (`event.type`, `event.domain`) takes nanoseconds. Do this first, return immediately for irrelevant events, then proceed with expensive operations only for matching events.
+
+## Lesson
+Filter events at the very top of the handler using simple field checks before any expensive operations. Structure the filter to reject irrelevant events as quickly as possible. If filtering becomes complex, move it to a decorator or middleware layer. Test with high event volume (1000s/sec) to verify performance doesn't degrade.