Revise Effect onboarding documentation

[vcarl]

Problem

Current Effect docs (EFFECT.md, EFFECT_REFERENCE.md) are comprehensive but not optimized for onboarding:

• Cover patterns not used in this codebase (Streams, Sinks, Schedules, Config)
• No "reading Effect code" primer
• Outdated syntax (Context.GenericTag, Layer.make)
• No connection to actual codebase files
• Decision trees are abstract, not actionable

Proposed Structure

EFFECT.md → Onboarding Guide

1. Reading Effect Code - mental model, what yield* does, pipe() pattern
2. Patterns We Use - with file references to actual code
3. Writing New Code - checklist with file refs, templates
4. Anti-Patterns - moved from reference doc
5. Model Files - escalationResolver.ts, service.ts, Database.ts

EFFECT_REFERENCE.md → Trimmed Quick Reference

• Keep: Error handling, concurrency, services, observability
• Fix: Update to Context.Tag class pattern, proper withConcurrency syntax
• Add: Discord SDK helpers reference, database patterns

EFFECT_ADVANCED.md → Future Patterns (NEW)

Move unused-but-potentially-useful patterns here:

• Stream/Sink processing
• Schedule combinators
• Config module
• Schema/Struct validation
• Queue, Ref/TRef, fiber supervision

Patterns Actually Used (from codebase survey)

Pattern	Occurrences	Primary Files
Effect.gen + yield*	94+	All command handlers
Effect.tryPromise	158+	discordSdk.ts
Effect.all + withConcurrency	10+	escalationResolver.ts
Data.TaggedError	11 types	errors.ts
Effect.withSpan	90+	All handlers
Context.Tag + Layer	12+	service.ts, Database.ts

Not used: Streams, Sinks, Schedules, Config, Schema, Queue, Ref

Verification

After rewriting:

• New developer can understand escalationResolver.ts after reading EFFECT.md
• All code examples compile and match codebase patterns
• No references to unused Effect features in main docs
• Every pattern has a file reference

Related

• Issue Effect migration: async/await files remaining #266 - Effect migration status
• Notes file: notes/2026-01-29_1_effect-migration-status.md