Anti-Pattern Index

Purpose: Cross-reference index of anti-patterns documented throughout the codebase. Links to source documents without duplicating content.

Last Scan: 2026-01-21 Documents Scanned: 10 patterns, 8 ADRs, 4 MUX design docs

Quick Reference by Category

Category Count Key Sources
Grammar/Consciousness 12 grammar-transformation-guide, consciousness-philosophy, ownership-metaphors
Testing 4 pattern-045, pattern-049
Architecture 11 ADR-006, ADR-010, ADR-039, ADR-040, ADR-043, ADR-051
Process/Methodology 10 pattern-046, pattern-047, systematic-excellence, omnibus-logs
Integration 5 pattern-035, pattern-054

Total Indexed: 42 anti-patterns

Grammar & Consciousness Anti-Patterns

Anti-patterns related to the MUX grammar (“Entities experience Moments in Places”) and preserving consciousness in responses.

ID Anti-Pattern Source Recommended Pattern
G-01 Query language in responses grammar-transformation-guide.md#anti-pattern-1-query-language-in-responses Pattern-052
G-02 Timestamps without context grammar-transformation-guide.md#anti-pattern-2-timestamps-without-context Pattern-053
G-03 IDs instead of names grammar-transformation-guide.md#anti-pattern-3-ids-instead-of-names EntityProtocol
G-04 Config strings as Places grammar-transformation-guide.md#anti-pattern-4-config-strings-as-places PlaceProtocol
G-05 Mechanical error messages grammar-transformation-guide.md#anti-pattern-5-mechanical-error-messages Pattern-054
G-06 Status codes instead of states grammar-transformation-guide.md#anti-pattern-6-status-codes-instead-of-states MomentProtocol
G-07 Raw data dumps grammar-transformation-guide.md#anti-pattern-7-raw-data-dumps Pattern-052
G-08 Treating NATIVE as cache ownership-metaphors.md#part-3 Mind/Senses/Understanding model
G-09 Losing place context ownership-metaphors.md#part-4 Pattern-051
G-10 Hiding uncertainty ownership-metaphors.md#part-5 Pattern-054
G-11 Third-person system language consciousness-philosophy.md#pillar-1 First-person presence
G-12 Alert/warning spam tone consciousness-philosophy.md#part-5 Supportive reframing

Testing Anti-Patterns

Anti-patterns related to testing strategy and verification.

ID Anti-Pattern Source Recommended Pattern
T-01 Mocked dependencies hiding integration issues pattern-045 Integration testing requirements
T-02 Schema/model drift not caught by tests pattern-045 Schema validation on startup
T-03 Type mismatches only enforced at DB level pattern-045 Dataclass field validators
T-04 Skipping audit “just this once” pattern-049 Audit cascade discipline

Architecture Anti-Patterns

Anti-patterns related to system architecture, configuration, and design decisions.

ID Anti-Pattern Source Recommended Pattern
A-01 Dual repository implementations ADR-005 Single repository per entity
A-02 get_session() anti-pattern ADR-006 Async session factory
A-03 Direct environment access in domain layers ADR-010 Configuration service injection
A-04 Mixed configuration patterns in same service ADR-010 Consistent access patterns
A-05 Database stored procedures for app logic ADR-043 Application layer logic
A-06 Shared database across environments ADR-040 Local database per environment
A-07 LLM-for-Everything - Using LLM for deterministic operations ADR-039 Canonical handlers for simple queries
A-08 Keyword-Only Matching - Pure keyword matching without LLM capability ADR-039 Hybrid approach
A-09 Shared Dev Database - Multiple environments sharing one database ADR-040 Local database per environment
A-10 Thread-Local Injection - Implicit context via thread locals ADR-051 Explicit parameter passing
A-11 Verification Theater - Process without actual verification ADR-028 Evidence-based verification pyramid

Process/Methodology Anti-Patterns

Anti-patterns related to development workflow and agent behavior.

ID Anti-Pattern Source Recommended Pattern
P-01 75% complete then abandoned pattern-046 Beads completion discipline
P-02 Rationalizing incomplete work as “optional” pattern-046 Explicit PM approval for deferrals
P-03 Proceeding with uncertainty (completion bias) pattern-047 Time Lord Alert escape hatch
P-04 Silent escalation avoidance pattern-047 Explicit uncertainty signals
P-05 “Good Enough” Trap - Shipping code that “works” without considering maintainability systematic-excellence.md Define “done” to include excellence
P-06 “Refactor Later” Lie - Promising cleanup that never happens systematic-excellence.md Refactor as you go
P-07 “Deadline” Pressure - Sacrificing quality for speed systematic-excellence.md Negotiate scope, not quality
P-08 80% Completion Trap - Declaring done without evidence the-completion-discipline-draft.md Completion matrix with evidence
P-09 “Should Have Known” Syndrome - Reactive discovery of obvious requirements 2025-10-29-omnibus-log.md Comprehensive upfront audit
P-10 Escalation Timing Failure - Debugging too long before seeking help 2025-11-16-omnibus-log.md Escalate after first untested commit

Integration Anti-Patterns

Anti-patterns related to external service integration.

ID Anti-Pattern Source Recommended Pattern
I-01 Silent failures / swallowed exceptions pattern-054 Honest failure with suggestion
I-02 Generic error messages (“Something went wrong”) pattern-054 Specific diagnosis + remediation
I-03 Forgetting initialize() - Using adapter without async initialization pattern-035 Lazy init pattern
I-04 Non-Idempotent Init - Initialize that breaks on repeat calls pattern-035 Make initialize() idempotent
I-05 Sync Init for Async Ops - Synchronous initialization for async operations pattern-035 Async initialization

Reverse Index: Pattern → Anti-Patterns Addressed

Pattern/Document Anti-Patterns Addressed
Pattern-045 T-01, T-02, T-03
Pattern-046 P-01, P-02
Pattern-047 P-03, P-04
Pattern-049 T-04
Pattern-051 G-09
Pattern-052 G-01, G-07
Pattern-053 G-02
Pattern-054 G-05, G-10, I-01, I-02
ADR-005 A-01
ADR-006 A-02
ADR-010 A-03, A-04
ADR-040 A-06
ADR-043 A-05
consciousness-philosophy.md G-11, G-12
ownership-metaphors.md G-08, G-09, G-10
grammar-transformation-guide.md G-01 through G-07
pattern-035 I-03, I-04, I-05
ADR-028 A-11
ADR-039 A-07, A-08
ADR-051 A-10
systematic-excellence.md P-05, P-06, P-07
the-completion-discipline-draft.md P-08
2025-10-29-omnibus-log.md P-09
2025-11-16-omnibus-log.md P-10

Scan Methodology

Documents Scanned (Pilot)

Patterns (10):

ADRs (8):

MUX Design Docs (4):

Keywords Searched

Phase 2: Emergent Anti-Pattern Detection (Completed)

Experiment Executed: 2026-01-21

5 Detection Strategies Used:

  1. Negative language clustering - “should not”, “avoid”, “never” proximity scoring (50% precision)
  2. Contrast pattern detection - “instead of X, do Y” structures (38% precision)
  3. Code comment mining - WARNING, CAUTION, HACK, XXX markers (50% precision)
  4. ADR rejected alternatives - ❌ options in decision docs (28% precision, highest volume)
  5. Session log lessons learned - “lesson learned”, “should have”, “root cause” (60% precision, best)

Results:

Automation Recommendations:

See dev/active/anti-pattern-phase2-experiment-results.md for full analysis.

Update Protocol

Triggers:

  1. Weekly documentation audit (FLY-AUDIT) - quick refresh
  2. Pattern sweep (6-week cadence) - comprehensive scan
  3. After major documentation sprints

Process:

  1. Run keyword scan against target directories
  2. Compare to existing index
  3. Add new anti-patterns with stable IDs (never renumber)
  4. Update “Last Scan” date
  5. Mark superseded patterns if any

Next Pattern Sweep: Feb 3, 2026 (per staggered-audit-calendar-2026.md)

Coverage Gap Analysis

Current Coverage: 9 of 58 patterns (15.5%)

Patterns WITH Coverage

035, 045, 046, 047, 049, 051, 052, 053, 054

Priority Gaps (Next Sweep Focus)

Priority Category Patterns Est. Anti-Patterns
P1 Core Architecture 001-008, 014-015, 017, 034 10-15
P2 Data & Query 013, 016, 023, 025, 026 5-8
P3 AI & Intelligence 012, 019-020, 022, 028-029, 055-058 8-12

Target: 50% coverage (29 patterns) by end of Q1 2026

See dev/active/anti-pattern-coverage-gap-analysis.md for full breakdown.

Index created: 2026-01-21 Last updated: 2026-01-21 (added coverage gap analysis) Maintainer: Documentation Management Agent