mindforge-cc 10.0.3 → 11.0.0

package/.mindforge/skills/multi-tenancy-patterns/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: multi-tenancy-patterns
+version: 1.0.0
+min_mindforge_version: 0.3.0
+status: stable
+triggers: multi-tenancy, tenant isolation, shared database tenancy, row-level security, tenant context, data isolation, tenant provisioning, tenant migration, tenant routing, schema per tenant, tenant-aware query, tenant onboarding
+---
+
+# Skill — Multi-Tenancy Patterns
+
+## When this skill activates
+Any task involving multi-tenant architecture, tenant isolation, shared database
+strategies, tenant context propagation, or tenant provisioning workflows.
+
+## Mandatory actions when this skill is active
+
+### Before designing multi-tenancy
+1. Assess isolation requirements (regulatory, security, performance).
+2. Determine tenant scale (10 tenants vs 10,000 tenants).
+3. Choose isolation level based on business requirements, not engineering convenience.
+
+### Isolation levels
+
+**Shared Database + Row-Level Security (RLS):**
+- Single database, single schema, tenant_id column on every table.
+- Cheapest to operate, easiest to deploy.
+- Least isolated — bugs can leak data between tenants.
+- Best for: SaaS with many small tenants, cost-sensitive.
+- Risk: a missing WHERE clause exposes all tenant data.
+
+**Schema per tenant:**
+- Single database, separate schema per tenant.
+- Moderate isolation and moderate cost.
+- Migrations must run per-schema (automation required).
+- Best for: moderate tenant count (< 1000), need logical separation.
+
+**Database per tenant:**
+- Completely separate database per tenant.
+- Maximum isolation, maximum cost.
+- Independent scaling, independent backup/restore.
+- Best for: enterprise customers, regulatory requirements, high-value tenants.
+
+### RLS implementation (PostgreSQL)
+
+```sql
+-- Enable RLS on the table
+ALTER TABLE orders ENABLE ROW LEVEL SECURITY;
+
+-- Create policy that filters by tenant
+CREATE POLICY tenant_isolation ON orders
+  USING (tenant_id = current_setting('app.current_tenant')::uuid);
+
+-- Force RLS even for table owner
+ALTER TABLE orders FORCE ROW LEVEL SECURITY;
+
+-- Set tenant context at connection level
+SET app.current_tenant = 'tenant-uuid-here';
+```
+
+**Critical rules:**
+- RLS policies must be impossible to bypass from application code.
+- NEVER use a superuser connection that bypasses RLS in application code.
+- Test RLS with a dedicated "tenant leak" test suite.
+- Add a CHECK constraint: `tenant_id IS NOT NULL` on every tenant-scoped table.
+
+### Tenant context propagation
+
+**Middleware pattern:**
+```
+Request → Extract tenant → Validate → Set context → Handler → Response
+```
+
+**Extraction sources (priority order):**
+1. JWT claim (most secure — server-signed).
+2. Subdomain: `tenant1.app.com` → tenant_id lookup.
+3. Path prefix: `app.com/tenant1/...` → extract from URL.
+4. Header: `X-Tenant-ID` (for service-to-service only).
+
+**Propagation through the stack:**
+- HTTP layer: middleware sets tenant in request context.
+- Service layer: receives tenant from context, passes to repositories.
+- Data layer: sets session variable before executing queries.
+- Background jobs: serialize tenant_id in job payload, restore before processing.
+
+### Tenant routing
+
+**Subdomain routing:**
+- `tenant1.app.com`, `tenant2.app.com`
+- Requires wildcard DNS and TLS certificate.
+- Clean separation, easy to identify tenant.
+- Custom domains: CNAME tenant1.com → tenant1.app.com.
+
+**Path-based routing:**
+- `app.com/tenant1/dashboard`, `app.com/tenant2/dashboard`
+- Simpler DNS/TLS setup.
+- Requires path prefix stripping in routing layer.
+
+**Header-based routing (internal only):**
+- `X-Tenant-ID: tenant-uuid`
+- For service-to-service communication within the platform.
+- Never expose to end users (spoofing risk).
+
+### Tenant provisioning
+
+**Onboarding workflow:**
+1. Create tenant record (name, plan, config).
+2. Provision resources (schema/database if applicable).
+3. Run seed data (default roles, settings, sample data).
+4. Configure DNS/routing (subdomain or custom domain).
+5. Send welcome notification.
+
+**Automation requirements:**
+- Provisioning must be fully automated (no manual steps).
+- Must complete in < 30 seconds for shared DB, < 5 minutes for isolated DB.
+- Rollback on failure — no half-provisioned tenants.
+
+### Tenant-aware migrations
+
+**Shared DB (RLS):**
+- Standard migrations — all tenants share the schema.
+- Add tenant_id to new tables, backfill existing tables.
+
+**Schema per tenant:**
+- Migration runner must iterate all tenant schemas.
+- Parallel execution for speed, with error handling per-tenant.
+- Failed migrations must not block other tenants.
+
+**Database per tenant:**
+- Migration runner connects to each tenant DB.
+- Version tracking per-tenant (some may be ahead/behind during rollout).
+- Canary strategy: migrate one tenant first, verify, then batch.
+
+### Testing multi-tenancy
+
+- **Isolation tests:** Create 2+ tenants, write data as tenant A, verify tenant B cannot see it.
+- **Context tests:** Verify tenant context survives async operations (background jobs, event handlers).
+- **Edge cases:** What happens with no tenant context? (Must fail closed, not open.)
+- **Performance:** Verify RLS does not degrade query performance significantly (check EXPLAIN).
+- **All environments** must have multiple tenants configured (including development).
+
+## Self-check before task completion
+- [ ] Did I follow the mandatory actions for this skill?
+- [ ] Did I apply the patterns appropriate to the context?
+- [ ] Did I verify the implementation meets the criteria above?
+- [ ] Did I document decisions and trade-offs made?

package/.mindforge/skills/multi-turn-conversation-design/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: multi-turn-conversation-design
+version: 1.0.0
+min_mindforge_version: 10.0.4
+status: stable
+triggers: multi-turn conversation, conversation state, context carryover, clarification strategy, conversation repair, intent disambiguation, dialogue management, turn-taking, conversation memory, slot filling, conversation flow, dialogue state tracking
+---
+
+# Skill — Multi-Turn Conversation Design (Dialogue State Management)
+
+## When this skill activates
+When designing conversational interfaces, building dialogue systems, implementing
+multi-step user interactions, or troubleshooting conversation flow issues. Use for
+chatbots, voice assistants, multi-step forms, or any interface where information
+is gathered across multiple exchanges.
+
+Core principle: **Continuity over repetition** — a well-designed conversation feels
+like talking to someone with a good memory. Never re-ask what was already provided.
+Never lose context between turns. Never make the user repeat themselves.
+
+## Mandatory actions when this skill is active
+
+### Dialogue State Tracking
+
+1. **State schema (track at every turn):**
+   ```json
+   {
+     "conversation_id": "uuid",
+     "turn_number": 5,
+     "current_intent": "book_flight",
+     "confidence": 0.92,
+     "slots": {
+       "origin": {"value": "SFO", "confirmed": true, "source": "turn_2"},
+       "destination": {"value": "JFK", "confirmed": true, "source": "turn_3"},
+       "date": {"value": null, "confirmed": false, "source": null},
+       "passengers": {"value": 1, "confirmed": false, "source": "assumed_default"}
+     },
+     "pending_clarifications": ["date"],
+     "conversation_history": ["summary of prior turns"],
+     "user_preferences": {"prefers_direct_flights": true}
+   }
+   ```
+
+   Rules:
+   - State is updated after EVERY turn (never stale)
+   - Each slot tracks: value, whether confirmed by user, and which turn provided it
+   - Assumed values are marked as unconfirmed (verify before critical actions)
+   - History is summarized (not raw) to stay within context limits
+
+### Context Carryover
+
+2. **Explicit reference to prior context:**
+   ```
+   Good (references prior turn):
+   "You mentioned you're flying from SFO. What date works for you?"
+
+   Bad (no reference, feels disconnected):
+   "What date would you like to fly?"
+
+   Good (acknowledges what's known):
+   "I have SFO to JFK for 1 passenger. I just need your travel date."
+
+   Bad (re-asks known information):
+   "Where are you flying from?"
+   ```
+
+   Rules:
+   - Start responses by acknowledging what you already know
+   - Reference specific prior statements: "Earlier you said X..."
+   - Summarize collected information periodically (every 3-4 turns)
+   - If context window is exhausted: summarize and explicitly note what's carried forward
+   - Never assume context persists implicitly — make carryover visible
+
+### Clarification Strategy
+
+3. **When to clarify (confidence-based):**
+   ```
+   Confidence >= 0.9: Proceed without clarification
+   Confidence 0.7-0.9: Proceed but confirm ("I'll book SFO to JFK — is that right?")
+   Confidence 0.5-0.7: Ask targeted question with options
+   Confidence < 0.5: Ask open-ended clarification
+
+   Clarification types (from most to least specific):
+   1. Binary confirmation: "Did you mean San Francisco?"
+   2. Multiple choice: "Did you mean SFO, SJC, or OAK?"
+   3. Constrained question: "Which airport in the Bay Area?"
+   4. Open question: "Where are you flying from?" (last resort)
+   ```
+
+   Rules:
+   - Always prefer more specific clarification formats (binary > choice > open)
+   - Limit choices to 3-5 options maximum
+   - Never ask two clarification questions in one turn (one at a time)
+   - If user answers a different question than asked: accept the new info, don't force the original question
+   - After 2 failed clarification attempts on same slot: offer to skip or use default
+
+### Conversation Repair
+
+4. **Detecting and recovering from misunderstanding:**
+   ```
+   Misunderstanding signals:
+   - User contradicts a prior agent response
+   - User repeats their question with different phrasing
+   - User says "no", "that's not what I meant", "wrong"
+   - User provides information that conflicts with current state
+
+   Repair protocol:
+   1. Acknowledge the misunderstanding explicitly
+      "I misunderstood — let me correct that."
+   2. State what you incorrectly assumed
+      "I thought you meant [X], but you're saying [Y]."
+   3. Update state with correct information
+   4. Confirm the correction
+      "Got it — [Y], not [X]. Is that right?"
+   5. Continue from the corrected state
+   ```
+
+   Rules:
+   - Never argue with the user about what they meant
+   - Repair immediately (don't wait for the user to notice the error)
+   - After repair: replay any downstream logic that depended on the wrong value
+   - Track repair frequency (high repair rate = poor understanding, needs model improvement)
+
+### Slot Filling
+
+5. **Multi-turn information gathering:**
+   ```
+   Slot filling strategy:
+   1. Identify all required slots for the current intent
+   2. Check which are already filled (from prior turns or user profile)
+   3. Ask for unfilled slots in natural priority order (most important first)
+   4. One slot per turn (don't overwhelm)
+   5. Allow user to provide multiple slots in one message (parse and fill all)
+   6. Confirm all slots before executing action
+
+   Example flow:
+   Turn 1: User: "I want to book a flight"
+           → Intent: book_flight, all slots empty
+   Turn 2: Agent: "Where are you flying from?"
+           → User: "SFO to JFK next Tuesday"
+           → Fill: origin=SFO, destination=JFK, date=next_tuesday
+   Turn 3: Agent: "SFO to JFK next Tuesday for 1 passenger. Shall I search?"
+           → Confirm all slots, offer to proceed
+   ```
+
+   Rules:
+   - Never re-ask a filled slot (check state first)
+   - If user provides extra info: accept and fill (don't say "I didn't ask that yet")
+   - Required slots must be confirmed before executing actions
+   - Optional slots get defaults (stated explicitly: "I'll assume 1 passenger unless you say otherwise")
+
+### Intent Disambiguation
+
+6. **Handling ambiguous or multi-intent messages:**
+   ```
+   Single intent (clear):
+   "Book me a flight to NYC" → book_flight
+
+   Ambiguous intent (clarify):
+   "I need to go to NYC" → travel? meeting? moving? → "Are you looking to book a flight?"
+
+   Multi-intent (handle sequentially):
+   "Book a flight and a hotel" → [book_flight, book_hotel]
+   → "Let's start with the flight. Where are you flying from?"
+   → Complete flight, then: "Now let's find you a hotel."
+   ```
+
+   Rules:
+   - Handle one intent at a time (queue others, don't drop them)
+   - When disambiguating: offer the most likely interpretation first
+   - Track which intents are pending (never lose a queued intent)
+   - If intents are independent: handle in order mentioned
+   - If intents are dependent: handle the dependency first
+
+### Conversation Flow Design
+
+7. **Turn structure:**
+   ```
+   Every agent turn should contain:
+   1. Acknowledgment: what you understood from the user's message
+   2. Progress indicator: what's done, what remains
+   3. Next action: what you need from the user OR what you're doing next
+
+   Pattern:
+   "[Acknowledge]. [Progress]. [Next step]."
+   "Got it, SFO to JFK. I just need your travel date. When are you flying?"
+   ```
+
+   Rules:
+   - Keep agent turns concise (2-3 sentences for information gathering)
+   - Never end a turn without a clear next step (question, confirmation, or action)
+   - Use progressive disclosure (don't dump all information at once)
+   - Match formality to user's tone (mirror their communication style)
+
+## Self-check before task completion
+
+Before marking a task done when this skill was active:
+
+- [ ] Is dialogue state tracked and updated every turn (intent, slots, confidence)?
+- [ ] Does every agent response reference prior context (no disconnected turns)?
+- [ ] Is clarification strategy confidence-based (specific at high confidence, open at low)?
+- [ ] Is there a repair protocol for misunderstandings (acknowledge, correct, confirm)?
+- [ ] Does slot filling never re-ask already-provided information?
+- [ ] Are multi-intent messages handled sequentially (queued, not dropped)?
+- [ ] Does every agent turn have: acknowledgment, progress, next step?
+- [ ] Are assumed/default values explicitly stated and marked unconfirmed?

package/.mindforge/skills/multimodal-ai/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: multimodal-ai
+version: 1.0.0
+min_mindforge_version: 10.5.0
+status: stable
+triggers: multimodal AI system, vision language model, image generation integration, audio AI processing, multi-input AI pipeline, multimodal embedding, visual question answering, image understanding AI, multimodal fusion, cross-modal retrieval, visual AI agent, multimodal prompt design
+compose:
+  - agent-orchestration-patterns
+---
+
+# Multimodal AI Systems
+
+## When this skill activates
+
+This skill activates when building AI systems that process multiple input modalities (vision + language, audio + text, image generation from text), implementing vision-language models, designing multimodal embeddings, or creating cross-modal retrieval systems. It applies to any system where AI must understand or generate content across different sensory modalities.
+
+## Mandatory actions when this skill is active
+
+### Before writing any code
+
+1. **Map modality requirements** — Identify all input/output modalities (text, image, audio, video). Determine which modalities are primary (must-have) vs. augmentative (enhances quality but optional). Define the fusion strategy: early fusion (combine raw inputs), late fusion (combine model outputs), or hybrid.
+2. **Select appropriate models** — Choose vision-language models based on task: GPT-4V/Claude for reasoning + vision, CLIP for embeddings, DALL-E/Stable Diffusion for generation, Whisper for audio. Validate that models support your required resolution, context length, and throughput.
+3. **Design preprocessing pipelines** — Each modality requires specific preprocessing: images need resizing/normalization/format conversion, audio needs resampling/segmentation, video needs frame extraction. Define preprocessing specs upfront to avoid format mismatches.
+4. **Establish quality metrics** — Define success criteria per modality: image classification accuracy, caption BLEU score, audio transcription WER, cross-modal retrieval Recall@K. Multimodal systems fail silently when one modality degrades.
+
+### During implementation
+
+- **Normalize modality inputs** — Convert all modalities to consistent formats before fusion. Use standard libraries: PIL/OpenCV for images, librosa/soundfile for audio, ffmpeg for video. Validate dimensions and data types at pipeline entry points.
+- **Handle modality-specific errors gracefully** — Image decoding failures, audio corruption, and video format issues should not crash the pipeline. Implement per-modality error handling with clear logging and fallback strategies (skip corrupted input, use placeholder, or retry with degraded quality).
+- **Implement attention mechanisms for fusion** — When combining modalities, use attention weights to let the model learn which modality is most informative for each input. Cross-attention between image patches and text tokens is the gold standard for VLMs.
+- **Batch processing by modality** — Group inputs by modality for efficient GPU utilization. Processing a mixed batch of images and text is slower than processing homogeneous batches sequentially.
+- **Design multimodal prompts carefully** — Vision-language models require structured prompts: "Image: [image] Question: {query} Answer:". Test prompt templates with diverse inputs to avoid format brittleness. Place modality markers consistently.
+- **Cache embeddings aggressively** — Multimodal embeddings are expensive to compute. Cache image embeddings, audio embeddings, and text embeddings separately with content-based keys (hash of preprocessed input). Invalidate caches only when model or preprocessing changes.
+
+### After implementation
+
+- **Validate cross-modal alignment** — Test that similar concepts across modalities produce similar embeddings (dog image + "dog" text should be close in embedding space). Use cosine similarity thresholds and spot-check with diverse examples.
+- **Measure modality-specific performance** — Isolate performance per modality. A system may excel at text understanding but fail at vision. Track accuracy, latency, and cost per modality separately.
+- **Test edge cases per modality** — Images: unusual aspect ratios, corrupted files, black images, high-resolution inputs. Audio: silence, noise, overlapping speech. Text: empty strings, non-ASCII characters, extremely long inputs.
+- **Monitor modality imbalance** — If one modality dominates the training data or inference distribution, the model may ignore other modalities. Track input distribution and validate that minority modalities still contribute to predictions.
+
+## Self-check before task completion
+
+- [ ] All input modalities are preprocessed to consistent formats with validation
+- [ ] Modality fusion strategy (early/late/hybrid) is explicitly implemented and tested
+- [ ] Per-modality error handling prevents pipeline crashes from corrupted inputs
+- [ ] Multimodal prompts are structured consistently and tested with diverse examples
+- [ ] Cross-modal retrieval accuracy meets target thresholds (Recall@K ≥ target)
+- [ ] Embeddings are cached with content-based keys to reduce compute cost
+- [ ] Performance is measured and validated separately for each modality
+- [ ] Edge cases (corrupted files, unusual formats, empty inputs) are handled gracefully

package/.mindforge/skills/mutation-testing/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: mutation-testing
+version: 1.0.0
+min_mindforge_version: 10.0.8
+status: stable
+triggers: mutation testing, stryker, mutmut, mutation score, surviving mutant, killed mutant, mutation operator, test strength, weak test detection, mutation coverage, test effectiveness, kill ratio
+compose: testing-standards
+---
+
+# Mutation Testing
+
+## When this skill activates
+
+This skill activates when evaluating test suite effectiveness, identifying weak tests, configuring mutation testing tools, or analyzing mutation testing results. It applies whenever the question is "are my tests actually catching bugs?" rather than "do my tests pass?"
+
+## Mandatory actions when this skill is active
+
+### Before
+
+1. Verify the project has a passing test suite (mutation testing requires green tests as baseline).
+2. Identify the language and select the appropriate tool (Stryker for JS/TS, mutmut for Python, PIT for Java).
+3. Determine scope: full codebase or targeted (changed files only for CI, full for periodic audits).
+4. Check that test execution time is reasonable (mutation testing multiplies runtime by mutant count).
+5. Establish the target kill ratio (minimum 80%, aim for 90%+ on critical paths).
+
+### During
+
+**Core Concept:**
+- Mutation testing modifies your source code (introduces bugs) and checks if tests fail.
+- If a test fails after mutation: the mutant is **killed** (good — tests caught the bug).
+- If all tests pass after mutation: the mutant **survived** (bad — tests missed the bug).
+- Surviving mutants reveal exactly where test coverage is superficial.
+
+**Mutation Operators:**
+- **Arithmetic**: Replace `+` with `-`, `*` with `/`.
+- **Conditional**: Replace `>` with `>=`, `==` with `!=`, flip `&&` to `||`.
+- **Boundary**: Change `i < 10` to `i <= 10` (off-by-one detection).
+- **Return value**: Replace `return x` with `return 0`, `return null`, `return !x`.
+- **Removal**: Delete function calls, remove assignments, skip statements.
+- **String**: Replace string literals with empty string or different value.
+
+**Metrics and Interpretation:**
+- **Mutation score** = (killed mutants / total mutants) * 100%.
+- **Killed**: Test suite detected the mutation (test failed). This is the goal.
+- **Survived**: No test caught the mutation. Investigate WHY.
+- **Timeout**: Mutation caused infinite loop. Counted as killed (behavior changed).
+- **No coverage**: No test executes the mutated line. Add tests for this code.
+- **Equivalent mutant**: Mutation produces identical behavior (e.g., `x * 1`). Ignore these.
+
+**Investigating Surviving Mutants:**
+1. Look at the mutated line and the operator applied.
+2. Ask: "What assertion would fail if this mutation were a real bug?"
+3. If no assertion exists: write a test that specifically validates that behavior.
+4. If assertion exists but passes: the assertion is too weak (not checking the right value).
+5. Common causes: missing boundary tests, testing only happy path, asserting on wrong property.
+
+**Tool Configuration:**
+
+*Stryker (JavaScript/TypeScript):*
+- Configure `mutate` array to target source files (exclude test files, configs).
+- Use `--incremental` for CI (only mutate changed files).
+- Set thresholds: `{ high: 90, low: 80, break: 75 }`.
+
+*mutmut (Python):*
+- Run `mutmut run` for full analysis, `mutmut results` for summary.
+- Use `--paths-to-mutate` to scope to specific modules.
+- Inspect survivors with `mutmut show <id>`.
+
+*PIT (Java):*
+- Configure via Maven/Gradle plugin with target classes and test classes.
+- Use `STRONGER` mutator group for comprehensive coverage.
+- Set `mutationThreshold` in build to fail below target.
+
+**Performance Optimization:**
+- In CI: only mutate files changed in the PR (incremental mode).
+- Use parallel execution (Stryker supports `--concurrency`).
+- Exclude generated code, DTOs, and trivial getters/setters.
+- Run full mutation analysis on a schedule (nightly/weekly), not every commit.
+
+### After
+
+1. Kill ratio meets the configured threshold (80%+ minimum).
+2. All surviving mutants in critical code paths have been investigated.
+3. New tests written to kill meaningful surviving mutants.
+4. Equivalent mutants documented and excluded from score calculation.
+5. CI is configured to run incremental mutation testing on PRs.
+
+## Self-check before task completion
+
+- [ ] Mutation testing tool is configured correctly for the project language.
+- [ ] Scope is appropriate (not wasting time on generated/trivial code).
+- [ ] Kill ratio meets the minimum threshold for the module's criticality.
+- [ ] Surviving mutants have been triaged: fix (write test) or dismiss (equivalent mutant).
+- [ ] New tests added actually kill the previously surviving mutants (verified by re-run).
+- [ ] CI integration uses incremental mode to keep pipeline fast.
+- [ ] Results are documented for team visibility (report or dashboard).
+- [ ] Performance impact is acceptable (total mutation test time within budget).

package/.mindforge/skills/notification-system-design/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: notification-system-design
+version: 1.0.0
+min_mindforge_version: 10.0.4
+status: stable
+triggers: notification system, multi-channel notification, frequency capping, preference management, notification delivery, push notification architecture, notification template, notification queue, do not disturb, notification deduplication, channel routing, notification personalization
+---
+
+# Skill — Notification System Design (Multi-Channel Delivery Architecture)
+
+## When this skill activates
+When designing notification delivery systems, implementing multi-channel messaging,
+building preference management, or architecting notification infrastructure. Use for
+any system that needs to send timely, relevant messages to users across push, email,
+SMS, in-app, or other channels.
+
+Core principle: **Respect over reach** — every notification should earn its delivery
+by being timely, relevant, and respectful of user preferences and attention.
+
+## Mandatory actions when this skill is active
+
+### Channel Selection (Urgency Matrix)
+
+1. **Route notifications by urgency and type:**
+   ```
+   | Urgency    | Channels                    | Examples                          |
+   |------------|-----------------------------|-----------------------------------|
+   | Critical   | Push + Email + SMS          | Security alert, payment failure   |
+   | Important  | Push + Email                | Order shipped, appointment reminder|
+   | Standard   | Push OR Email               | New feature, weekly digest        |
+   | Low        | In-app only                 | Social activity, recommendations  |
+   ```
+
+   Rules:
+   - Critical notifications bypass frequency caps (but still respect DND)
+   - Never send SMS for non-critical notifications (highest user annoyance cost)
+   - In-app is the lowest-friction channel — use it generously
+   - Email is async — never rely on it for time-sensitive actions
+   - User channel preferences override the urgency matrix (except Critical/security)
+
+### Frequency Capping
+
+2. **Rate limiting per user:**
+   ```json
+   {
+     "caps": {
+       "push": {"max_per_day": 5, "max_per_hour": 2},
+       "email": {"max_per_day": 3, "max_per_week": 10},
+       "sms": {"max_per_day": 1, "max_per_week": 3},
+       "in_app": {"max_per_day": 20}
+     },
+     "aggregation": {
+       "combine_similar": true,
+       "digest_threshold": 3,
+       "digest_window_minutes": 30
+     }
+   }
+   ```
+
+   Rules:
+   - Caps are per-user, per-channel, across ALL notification types
+   - When cap is reached: queue for next window OR downgrade to lower-urgency channel
+   - Aggregate similar notifications into digests (e.g., "3 new comments" not 3 separate pushes)
+   - Track notification fatigue: if open rate drops below 5%, reduce frequency automatically
+   - Critical/security notifications are exempt from caps but tracked separately
+
+### Preference Management
+
+3. **User preference schema:**
+   ```json
+   {
+     "user_id": "uuid",
+     "global": {
+       "muted": false,
+       "do_not_disturb": {"enabled": true, "start": "22:00", "end": "08:00", "timezone": "America/New_York"}
+     },
+     "channels": {
+       "push": {"enabled": true},
+       "email": {"enabled": true, "digest_mode": "daily"},
+       "sms": {"enabled": false}
+     },
+     "categories": {
+       "marketing": {"push": false, "email": true},
+       "social": {"push": true, "email": false},
+       "transactional": {"push": true, "email": true},
+       "security": {"push": true, "email": true, "sms": true}
+     }
+   }
+   ```
+
+   Rules:
+   - Users can control preferences at: global, channel, and category level
+   - Category-level overrides channel-level (fine-grained control)
+   - Security/transactional notifications: always delivered (legal requirement), but user chooses channel
+   - DND hours: queue notifications and deliver when DND ends (except Critical)
+   - Preference changes take effect immediately (no "takes up to 24 hours")
+
+### Delivery Architecture
+
+4. **System architecture:**
+   ```
+   Event Source → Notification Service → Channel Router → Delivery Providers → Tracking
+
+   Components:
+   1. Event Ingestion: receives trigger events from application services
+   2. Notification Service: applies business logic (templates, personalization, dedup)
+   3. Preference Engine: checks user preferences and caps
+   4. Channel Router: selects delivery channel(s) per urgency matrix + preferences
+   5. Queue (per channel): buffers for rate limiting and retry
+   6. Delivery Providers: FCM/APNs (push), SendGrid/SES (email), Twilio (SMS)
+   7. Tracking: delivery status, opens, clicks, dismissals
+   ```
+
+5. **Delivery guarantees:**
+   - At-least-once delivery with deduplication
+   - Idempotency key per notification (event_type + user_id + dedup_window)
+   - Exponential retry with jitter (max 3 retries per channel)
+   - Dead letter queue for permanently failed deliveries
+   - Track delivery status: queued → sent → delivered → opened → clicked/dismissed
+
+6. **Deduplication:**
+   ```
+   Dedup key = hash(notification_type + user_id + content_hash)
+   Dedup window = configurable per type (default: 1 hour)
+
+   If same dedup key seen within window:
+   - Suppress duplicate
+   - Log suppression (for debugging)
+   - Update existing notification if content changed
+   ```
+
+### Template System
+
+7. **Notification templates:**
+   ```
+   Template: order_shipped
+   Channels: push, email
+   Personalization tokens: {{user.first_name}}, {{order.id}}, {{order.tracking_url}}
+
+   Push:
+     title: "Your order is on its way!"
+     body: "{{user.first_name}}, order #{{order.id}} has shipped. Track it here."
+     action_url: "{{order.tracking_url}}"
+
+   Email:
+     subject: "Order #{{order.id}} shipped"
+     template_id: "tmpl_order_shipped_v2"
+     variables: {first_name, order_id, tracking_url, items}
+   ```
+
+   Rules:
+   - Templates support multi-language (locale selected from user preferences)
+   - Preview rendering available before send (catch token errors)
+   - Version templates (never edit in place — create new version, deprecate old)
+   - A/B test notification copy via experiment-design skill
+
+## Self-check before task completion
+
+Before marking a task done when this skill was active:
+
+- [ ] Did I define an urgency matrix mapping notification types to channels?
+- [ ] Are frequency caps defined per-user, per-channel with aggregation rules?
+- [ ] Do user preferences support global, channel, and category-level control?
+- [ ] Is DND (do not disturb) implemented with timezone awareness?
+- [ ] Is delivery at-least-once with deduplication via idempotency keys?
+- [ ] Are retries exponential with a dead letter queue for failures?
+- [ ] Are templates versioned, multi-language, and previewable?
+- [ ] Are Critical/security notifications exempt from caps but still respect DND?