mindforge-cc 10.0.3 → 11.0.0

package/.mindforge/skills/fine-tuning-workflow/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: fine-tuning-workflow
+version: 1.0.0
+min_mindforge_version: 0.1.0
+status: stable
+triggers: fine tuning, dataset preparation, training config, eval during training, model deployment, model A/B test, LoRA adapter, training data quality, hyperparameter tuning, model versioning, training pipeline, fine tune evaluation
+---
+
+# Skill — Fine-Tuning Workflow
+
+## When this skill activates
+Any task involving LLM fine-tuning, training dataset preparation, LoRA/QLoRA
+adaptation, model evaluation during training, or model deployment with A/B testing.
+
+## Mandatory actions when this skill is active
+
+### Before writing any code
+1. Define the fine-tuning objective (style adaptation, domain knowledge, task specialization).
+2. Audit training data quality (deduplication, format consistency, bias check).
+3. Establish baseline metrics with the un-tuned model.
+
+### During implementation
+- Run evaluation on held-out validation set at regular intervals during training.
+- Implement early stopping on quality degradation.
+- Track training metrics: loss, eval metrics, learning rate schedule.
+
+### After implementation
+- Compare fine-tuned model against baseline on the eval suite.
+- Deploy with canary traffic (shadow or A/B testing).
+- Document the model card with training details and performance.
+
+## Dataset Preparation
+
+### Data Requirements by Objective
+| Objective | Min Examples | Quality Requirement |
+|-----------|-------------|-------------------|
+| Style/tone adaptation | 100-500 | High quality exemplars of target style |
+| Domain knowledge | 1,000-10,000 | Accurate, diverse domain Q&A pairs |
+| Task specialization | 500-5,000 | Varied task examples with edge cases |
+| Instruction following | 1,000+ | Diverse instruction/response pairs |
+
+### Data Format (Instruction Tuning)
+```jsonl
+{"messages": [
+  {"role": "system", "content": "You are a helpful coding assistant."},
+  {"role": "user", "content": "Write a function to reverse a string in Python."},
+  {"role": "assistant", "content": "def reverse_string(s: str) -> str:\n    return s[::-1]"}
+]}
+```
+
+### Data Quality Checklist
+- [ ] Deduplicated (no exact or near-duplicate examples).
+- [ ] Consistent format across all examples.
+- [ ] Balanced across categories/topics.
+- [ ] No PII or sensitive data (unless intentional and consented).
+- [ ] Correct and high-quality responses (garbage in = garbage out).
+- [ ] Diverse inputs (length, complexity, edge cases).
+
+### Data Cleaning Pipeline
+1. **Deduplication**: hash-based exact dedup + embedding-based semantic dedup.
+2. **Format validation**: ensure all examples match expected schema.
+3. **Quality filtering**: remove low-quality examples (too short, incoherent).
+4. **Balance check**: verify distribution across categories.
+5. **Contamination check**: ensure eval data not in training set.
+
+## Training Approaches
+
+### Full Fine-Tuning
+- Updates all model parameters.
+- Use for: significant behavior changes, large datasets.
+- Cost: high (full model in GPU memory, long training time).
+- Risk: catastrophic forgetting of base model capabilities.
+
+### LoRA (Low-Rank Adaptation)
+- Adds small trainable matrices alongside frozen base model.
+- Use for: most fine-tuning tasks (efficient, less forgetting).
+- Cost: low (only adapter weights in GPU memory).
+- Benefit: merge adapter with base model for zero-overhead inference.
+
+### QLoRA (Quantized LoRA)
+- Base model quantized to 4-bit, LoRA adapters in 16-bit.
+- Use for: large models on limited GPU memory.
+- Cost: very low (fits 70B model on single GPU for training).
+- Trade-off: slight quality reduction from quantization.
+
+### Key Hyperparameters
+| Parameter | Typical Range | Notes |
+|-----------|--------------|-------|
+| Learning rate | 1e-5 to 5e-5 | Lower for larger models |
+| Batch size | 4-32 | Larger = more stable, needs more memory |
+| Epochs | 1-5 | More epochs risk overfitting |
+| LoRA rank | 8-64 | Higher = more capacity, more compute |
+| LoRA alpha | 16-128 | Usually 2x rank |
+| Warmup steps | 5-10% of total | Prevents early divergence |
+
+## Evaluation During Training
+
+### Validation Set
+- Hold out 10-20% of data as validation (never train on it).
+- Evaluate every N steps (e.g., every 100 steps or every epoch).
+- Track: validation loss, task-specific metrics.
+
+### Early Stopping
+- Stop training if validation metric doesn't improve for N evaluations.
+- Prevents overfitting (model memorizes training data).
+- Save checkpoint at best validation score, not last step.
+
+### Evaluation Metrics
+| Metric | Use Case | What It Measures |
+|--------|----------|-----------------|
+| Perplexity | General quality | Model confidence on held-out data |
+| ROUGE-L | Summarization | Overlap with reference summaries |
+| Exact Match | Q&A, classification | Correct answer percentage |
+| Human preference | Style/quality | A/B comparison by annotators |
+| Task-specific | Custom tasks | Domain-specific correctness |
+
+## Model Deployment
+
+### Deployment Pipeline
+```
+Train → Evaluate → Register → Shadow Test → Canary → Full Rollout
+```
+
+### Model Registry
+- Version every model with: training data hash, hyperparameters, eval scores.
+- Store model artifacts in versioned storage (S3, GCS, MLflow).
+- Link to training run for full reproducibility.
+
+### Shadow Traffic Testing
+- Deploy new model alongside production model.
+- Route production traffic to both (only serve old model's response).
+- Compare outputs offline (quality, latency, error rate).
+- Promote to canary only if shadow results are satisfactory.
+
+### Canary Rollout
+- Route 5% of traffic to new model.
+- Monitor: quality metrics, latency p99, error rate, user feedback.
+- If metrics are good after 24-48 hours: increase to 25% → 50% → 100%.
+- Rollback instantly if any metric degrades.
+
+## A/B Testing
+
+### Experiment Design
+- Split users randomly (not requests — same user should see same model).
+- Define primary metric (quality score, user satisfaction, task completion).
+- Define guardrail metrics (latency, error rate, cost).
+- Run for statistical significance (typically 1-2 weeks).
+
+### Analysis
+- Compare primary metric between control (old model) and treatment (new model).
+- Verify guardrail metrics haven't degraded.
+- Check for segment effects (does new model help some users but hurt others?).
+- Document results and decision in model card.
+
+## Model Versioning (Model Card)
+
+```yaml
+model_card:
+  name: customer-support-assistant-v3
+  base_model: llama-3-8b
+  adapter: LoRA (rank 32)
+  training_data:
+    source: customer_support_conversations_2024
+    examples: 5,432
+    hash: sha256:def456...
+  hyperparameters:
+    learning_rate: 2e-5
+    epochs: 3
+    batch_size: 16
+    lora_rank: 32
+  evaluation:
+    held_out_accuracy: 0.89
+    human_preference_win_rate: 0.72
+    latency_p99_ms: 340
+  deployed_at: 2024-01-20
+  parent_version: customer-support-assistant-v2
+```
+
+## Self-check before task completion
+
+Before marking a task done when this skill was active:
+
+- [ ] Did I read the full SKILL.md before starting? (Not just the triggers)
+- [ ] Is training data deduplicated, validated, and quality-checked?
+- [ ] Is evaluation running on held-out validation set during training?
+- [ ] Is early stopping configured to prevent overfitting?
+- [ ] Are baseline metrics established for comparison?
+- [ ] Is the model versioned with full training lineage?
+- [ ] Is deployment using canary/A/B testing (not instant full rollout)?

package/.mindforge/skills/fintech-patterns/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: fintech-patterns
+version: 1.0.0
+min_mindforge_version: 10.2.0
+status: stable
+triggers: fintech architecture, payment processing system, PCI-DSS compliance, double-entry ledger, financial reconciliation, KYC workflow, AML detection, transaction processing, financial regulation, banking integration, money movement, payment rail design
+compose: payment-integration
+---
+
+# Skill — Fintech Patterns
+
+## When this skill activates
+This skill activates when building payment processing systems, implementing double-entry accounting ledgers, handling financial transactions, integrating with banking APIs, ensuring PCI-DSS compliance, or implementing KYC/AML regulatory workflows.
+
+## Mandatory actions when this skill is active
+
+### Before writing any code
+1. Design ledger architecture using double-entry accounting principles: every transaction creates equal and opposite debits/credits, with immutable transaction logs, balance snapshots for performance, and idempotency keys to prevent duplicate charges
+2. Map regulatory compliance requirements: PCI-DSS scope (SAQ-A for payment gateway, SAQ-D for card storage), KYC verification levels (identity document, address proof, sanctions screening), AML transaction monitoring thresholds (structuring patterns, velocity checks, geographic risk)
+3. Document money movement flows with state machines: pending → authorized → captured → settled (for cards), initiated → processing → completed → reconciled (for ACH), with explicit rollback/refund paths and partial capture support
+
+### During implementation
+- Implement financial primitives with arbitrary-precision arithmetic: use Decimal types (never floats) for all monetary amounts, store values in smallest currency unit (cents/paise), handle currency conversion with mid-market rates and spread transparency
+- Build idempotent transaction endpoints: require client-generated idempotency keys (UUID v4), cache results for 24 hours, return identical response for duplicate requests (201 for first, 200 for subsequent), prevent phantom charges during network retries
+- Design ledger tables with append-only semantics: never UPDATE transaction records, use compensating transactions for corrections, store audit trail with user attribution, implement row-level checksums for tamper detection
+- Implement three-phase commit for distributed transactions: reserve funds (pessimistic lock), execute payment processing (call external API), commit or rollback based on response, with automatic retry logic for transient failures and dead letter queue for manual review
+- Enforce PCI-DSS compliance boundaries: tokenize card data immediately (Stripe/Adyen tokens), never log full PAN, redact card numbers in UI (show last 4 digits), use TLS 1.2+ for payment gateway communication, implement network segmentation between card data environment and application servers
+
+### After implementation
+- Execute financial reconciliation: match internal ledger balances against bank statements (daily), payment gateway settlement reports (batch ID reconciliation), and third-party wallet providers, with automated alerting for discrepancies >$10 or >0.1%
+- Validate transaction integrity: sum of all debits equals sum of all credits (ledger balance proof), account balance equals sum of transaction deltas (aggregate consistency check), no orphaned transactions without matching counterparty entries
+- Conduct security testing specific to financial systems: SQL injection in payment search, authorization bypass for fund transfers, race conditions in balance checks (concurrent withdrawals), replay attacks on payment endpoints, and IDOR vulnerabilities in transaction history APIs
+
+## Self-check before task completion
+- [ ] All monetary amounts use Decimal/BigDecimal types with explicit currency codes (ISO 4217), never floating-point arithmetic
+- [ ] Transaction endpoints are idempotent with client-provided idempotency keys, cached responses for duplicate requests
+- [ ] Ledger implements double-entry accounting with immutable transaction records, audit trails, and balance proof validation
+- [ ] PCI-DSS scope is minimized: no full card numbers stored, tokenization at payment entry point, encryption for sensitive data (AES-256-GCM)
+- [ ] KYC/AML workflows implemented: identity verification (document upload + liveness check), sanctions screening (OFAC/EU lists), transaction monitoring (velocity limits, geographic risk scoring)
+- [ ] Financial reconciliation automated: daily bank statement matching, payment gateway settlement verification, alerting for discrepancies
+- [ ] State machine transitions documented: pending → processing → settled → reconciled, with explicit rollback/refund paths and timeout handling

package/.mindforge/skills/flutter-architecture/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: flutter-architecture
+version: 1.0.0
+min_mindforge_version: 10.4.0
+status: stable
+triggers: flutter architecture, widget composition pattern, flutter state management, platform channel flutter, dart design pattern, flutter navigation, flutter performance optimization, riverpod provider, flutter plugin development, flutter build runner, flutter layout pattern, flutter app architecture
+---
+
+# Skill — Flutter Architecture & Widget Composition
+
+## When this skill activates
+This skill activates when building Flutter applications, including widget composition strategies, state management implementation, platform channel integration, or establishing scalable app architecture patterns.
+
+## Mandatory actions when this skill is active
+
+### Before writing any code
+1. Choose state management approach based on app complexity (Riverpod for large apps, Provider for medium, setState for simple)
+2. Define navigation strategy (GoRouter for declarative routing, Navigator 2.0 for complex flows)
+3. Establish platform channel contracts for native functionality and document method signatures
+4. Plan widget composition hierarchy to maximize reusability and minimize rebuild scope
+
+### During implementation
+- Keep widget `build()` methods pure and deterministic — move side effects to lifecycle methods or controllers
+- Use `const` constructors wherever possible to enable widget caching and reduce rebuild overhead
+- Implement proper widget keys (GlobalKey, ValueKey, ObjectKey) for stateful widgets in lists
+- Leverage code generation (`build_runner`, `freezed`, `json_serializable`) for data models and state classes
+- Separate business logic from UI using repositories, services, and view models (MVVM pattern)
+- Use platform channels with proper codec (StandardMethodCodec, JSONMethodCodec) and error handling
+- Implement proper dispose() methods to prevent memory leaks in StatefulWidgets and controllers
+
+### After implementation
+- Run Flutter DevTools to profile widget rebuilds, identify expensive builds, and check memory usage
+- Test on both iOS and Android with platform-specific behaviors (back button, system gestures, status bar)
+- Verify hot reload works correctly — stateful widgets preserve state, providers remain intact
+- Check widget test coverage for critical UI logic and integration tests for user flows
+
+## Self-check before task completion
+- [ ] State management solution scales appropriately (no global setState, proper scoping of providers)
+- [ ] Platform channels include both method calls and event channels where needed, with proper error codes
+- [ ] Widget tree depth is reasonable (use composition over deep nesting, extract widgets strategically)
+- [ ] Build performance is acceptable (use `flutter run --profile` to measure frame rendering times)
+- [ ] Navigation handles back button, deep links, and state restoration correctly

package/.mindforge/skills/gaming-backend/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: gaming-backend
+version: 1.0.0
+min_mindforge_version: 10.2.0
+status: stable
+triggers: gaming backend, multiplayer architecture, matchmaking system, game leaderboard, game state synchronization, anti-cheat system, virtual economy design, game server architecture, real-time gaming, player session management, game lobby system, competitive ranking
+compose: real-time-sync
+---
+
+# Skill — Gaming Backend
+
+## When this skill activates
+This skill activates when building real-time multiplayer game servers, matchmaking systems, leaderboards, game state synchronization, anti-cheat systems, virtual economies, player session management, or competitive ranking systems.
+
+## Mandatory actions when this skill is active
+
+### Before writing any code
+1. Design game state synchronization strategy: authoritative server architecture (server validates all actions), client-side prediction with server reconciliation, delta compression for bandwidth optimization, lag compensation (rewind time for hit detection), and tick rate optimization (60 Hz for fast-paced, 20 Hz for strategy)
+2. Model matchmaking algorithm: skill-based rating (ELO/Glicko-2), queue time vs match quality tradeoff, party/premade handling (avoid unfair team compositions), region-based latency constraints (<50ms preferred), and backfill logic for mid-game joins
+3. Map virtual economy flows: currency earn rates (gameplay rewards, daily login, achievements), sinks (cosmetics, upgrades, gacha), faucets (freemium currency), conversion ratios (premium to free currency), and anti-inflation mechanisms (decay, seasonal resets)
+
+### During implementation
+- Implement authoritative game server: validate all player inputs server-side (movement, attacks, item usage), reject impossible actions (speed hacks, teleportation), maintain canonical game state, broadcast state updates to clients at fixed tick rate, handle client disconnects gracefully (AI takeover or pause)
+- Build matchmaking queue system: players enter queue with skill rating and region preferences, matchmaker runs periodically (every 1-5 seconds), expands search criteria over time (relax skill range after 60s, add regions after 90s), create balanced teams (sum of ratings similar), reserve game server instance, notify players
+- Design leaderboard with efficient ranking: use Redis sorted sets (ZADD for score updates, ZREVRANK for rank lookup, ZREVRANGE for top-N), store composite score (wins, kills, time), implement seasonal resets with archival, handle ties deterministically (timestamp tiebreaker), support filtering by region/mode
+- Implement anti-cheat detection: server-side validation (impossible speeds, impossible accuracy), statistical anomaly detection (headshot rate >90%, reaction time <50ms), behavioral fingerprinting (mouse movement patterns), report system with manual review queue, automated bans for blatant cheats with appeal process
+- Build session management: player login creates session token (JWT with short expiry), heartbeat every 30s to maintain session, detect duplicates (kick old session), handle region transfers (migrate session to nearest server), graceful shutdown notifications (5 min warning before maintenance)
+
+### After implementation
+- Load test game servers under realistic conditions: spawn 1000+ concurrent bots with realistic behavior (movement, combat, chat), measure tick rate stability (should not drop below target), validate state synchronization (all clients see same events within latency bounds), identify performance bottlenecks (physics, pathfinding, network I/O)
+- Validate matchmaking quality metrics: measure average queue time (should be <60s for 80th percentile), skill disparity in matches (std dev of player ratings <200), match abandonment rate (<5% pre-game), and player retention after first match
+- Test anti-cheat effectiveness: attempt common exploits (speed hacks via Cheat Engine, aim bots, packet manipulation), verify server rejects invalid actions, check detection latency (should flag anomaly within 3 minutes), test false positive rate (<0.1% of legit players)
+
+## Self-check before task completion
+- [ ] Game server is authoritative: validates all player inputs, rejects impossible actions, maintains canonical state, uses lag compensation for hit detection
+- [ ] Matchmaking balances skill vs queue time: expands search criteria gradually, creates balanced teams, respects region/latency constraints
+- [ ] Leaderboard performs at scale: Redis sorted sets for O(log N) updates, supports millions of players, handles seasonal resets with archival
+- [ ] Anti-cheat detects common exploits: speed hacks, aim bots, statistical anomalies (headshot rate, reaction time), with manual review queue
+- [ ] Session management robust: heartbeat mechanism, duplicate detection, graceful disconnects, region transfer support
+- [ ] Virtual economy balanced: currency earn rates tuned, inflation controls (sinks match faucets), gacha odds transparent and compliant with regulations
+- [ ] Real-time performance meets targets: tick rate stable under load (60 Hz for action, 20 Hz for strategy), latency <100ms for 95th percentile players

package/.mindforge/skills/git-workflow-design/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: git-workflow-design
+version: 1.0.0
+min_mindforge_version: 0.3.0
+status: stable
+triggers: git workflow design, trunk based development, gitflow, branch policy, merge strategy, squash vs rebase, commit standard, branch naming, release branch, hotfix workflow, protected branch, merge queue
+---
+
+# Skill — Git Workflow Design
+
+## When this skill activates
+Any task involving git branching strategies, merge policies, commit standards,
+release workflows, or repository governance.
+
+## Mandatory actions when this skill is active
+
+### Before recommending a workflow
+1. Assess team size and release cadence.
+2. Identify deployment model (continuous vs scheduled releases).
+3. Consider CI/CD maturity and test coverage levels.
+
+### Trunk-Based Development
+
+**Characteristics:**
+- Main branch is always deployable.
+- Short-lived feature branches (< 2 days).
+- CI runs on every commit to main.
+- Feature flags for incomplete work.
+
+**Best for:** small-to-medium teams, continuous deployment, high CI maturity.
+
+**Rules:**
+- Branch from main, merge back to main.
+- No long-lived branches (except main).
+- Feature flags decouple deploy from release.
+- Revert fast if main breaks — don't "fix forward" under pressure.
+
+### GitFlow
+
+**Characteristics:**
+- develop branch for integration.
+- release/* branches for stabilization.
+- hotfix/* branches from main for urgent fixes.
+- Longer release cycles (weekly/monthly).
+
+**Best for:** teams with scheduled releases, multiple versions in production, regulatory requirements.
+
+**Rules:**
+- Feature branches from develop.
+- Release branch cut when ready — only bug fixes after cut.
+- Hotfix from main, merge back to both main AND develop.
+- Tag every release on main.
+
+### Merge strategies
+
+**Squash merge:**
+- Produces clean, linear history on main.
+- One commit per PR — easy to revert entire features.
+- Loses granular commit history from the branch.
+- Best for: feature branches with messy/WIP commits.
+
+**Rebase merge:**
+- Linear history, preserves individual commits.
+- Requires clean, meaningful commits on the branch.
+- Best for: teams that enforce atomic commits.
+
+**Merge commit:**
+- Preserves branch topology (merge bubbles visible).
+- Easy to see "this group of commits was one PR."
+- Best for: teams that value traceability over linearity.
+
+### Branch naming conventions
+
+**Format:** `type/ticket-description`
+
+**Examples:**
+- `feat/PROJ-123-add-oauth-login`
+- `fix/PROJ-456-null-pointer-checkout`
+- `chore/upgrade-react-19`
+- `hotfix/payment-timeout`
+
+**Rules:**
+- Lowercase, hyphen-separated.
+- Include ticket number when applicable.
+- Keep descriptions short but meaningful.
+- No personal names or dates in branch names.
+
+### Protected branch rules
+
+- **Require pull request** — no direct pushes to main/develop.
+- **Require CI pass** — all status checks green before merge.
+- **Require review** — at least 1 approval (2 for critical paths).
+- **Require up-to-date branch** — must be rebased on latest main.
+- **Restrict force-push** — disabled on main, develop, release/*.
+- **Require signed commits** — for regulated environments.
+
+### Merge queue
+
+- Batches multiple approved PRs together.
+- Tests the combined result before merging.
+- Automatically reverts PRs that break the batch.
+- Prevents "works individually, breaks together" scenarios.
+- Available: GitHub merge queue, Mergify, Bors.
+
+### Commit standards
+
+**Conventional Commits format:**
+```
+type(scope): description
+
+[optional body]
+
+[optional footer]
+```
+
+**Types:** feat, fix, refactor, docs, test, chore, perf, ci, build, revert.
+
+**Rules:**
+- Subject line < 72 characters.
+- Imperative mood ("add" not "added").
+- Body explains WHY, not WHAT (the diff shows what).
+- Footer for breaking changes: `BREAKING CHANGE: description`.
+- Enforce with commitlint + husky pre-commit hook.
+
+## 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/graceful-degradation/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: graceful-degradation
+version: 1.0.0
+min_mindforge_version: 10.0.9
+status: stable
+triggers: graceful degradation, circuit breaker cascade, fallback hierarchy, reduced functionality mode, health-based routing, partial availability, degraded response, feature shedding, load shedding, priority-based degradation, degradation strategy, availability tier
+---
+
+# Skill — Graceful Degradation
+
+## When this skill activates
+Any task involving resilience under failure, circuit breakers, fallback hierarchies,
+load shedding, feature shedding, or priority-based degradation design.
+
+## Mandatory actions when this skill is active
+
+### Before writing any code
+1. Classify all features into availability tiers (critical/important/nice-to-have).
+2. Define fallback hierarchy for each external dependency.
+3. Identify degradation triggers and corresponding responses.
+
+### During implementation
+- Circuit breakers on all external service calls.
+- Fallback responses for every dependency (cache → static → error).
+- Feature flags to disable non-critical features under load.
+- Load shedding with priority-based request classification.
+
+### After implementation
+- Chaos test: kill dependencies, spike load, verify partial functionality.
+- Verify system remains usable when any single dependency fails.
+- Document degradation playbook for on-call.
+
+## Availability Tiers
+
+| Tier | Policy | Examples |
+|------|--------|----------|
+| Tier 1: Critical | Never shed | Auth, payments, data persistence, core API |
+| Tier 2: Important | Shed under extreme load | Search, recommendations, notifications |
+| Tier 3: Nice-to-have | Shed early | Personalization, A/B tracking, social features |
+
+## Load Shedding
+
+```
+Priority 1 (Critical):  Health checks, auth, payment finalization
+Priority 2 (High):      Core reads/writes, search
+Priority 3 (Normal):    Recommendations, analytics, batch
+Priority 4 (Low):       Prefetching, enrichment, non-critical webhooks
+```
+
+- At 80% capacity: reject P4. At 90%: reject P3+P4. At 95%: P1 only.
+- Return 503 with `Retry-After`. Never reject P1 (that means full outage).
+
+## Fallback Hierarchies
+
+```
+Live data → Cached (recent) → Static default → Graceful error (hide widget)
+```
+
+- Each level independently deployable and testable.
+- Fallback data pre-computed and stored close to consumer.
+- Never let fallback failure cascade. Log fallback frequency as health signal.
+
+## Circuit Breaker Design
+
+- **Closed** (normal): requests flow, track failure rate.
+- **Open** (tripped): return fallback immediately, no calls to dependency.
+- **Half-Open** (probing): allow 1 request to test recovery.
+- Config: 5 failures/30s → OPEN, 30s timeout → HALF-OPEN, 3 successes → CLOSED.
+
+### Cascade Prevention
+- Timeout hierarchy: A→B=2s, B→C=500ms. When C trips in B, B returns fallback to A.
+- A never sees C's failure — only potentially degraded but fast responses from B.
+
+## Health-Based Routing
+- Each instance reports health score (0-100) based on CPU, errors, latency, memory.
+- Score >80: full traffic. 50-80: reduced traffic. <50: no new traffic, drain.
+
+## Feature Shedding (Shed First)
+1. Search-as-you-type / autocomplete.
+2. Personalized recommendations (ML model calls).
+3. Real-time analytics / activity feeds.
+4. Image/video transcoding.
+5. Non-critical webhooks.
+
+Automated via feature flags tied to system load. Re-enable gradually after recovery.
+
+## Self-check before task completion
+
+- [ ] Are all features classified into availability tiers?
+- [ ] Is there a fallback for every dependency (cache → static → error)?
+- [ ] Are circuit breakers on all external calls?
+- [ ] Is load shedding priority-based with correct request classification?
+- [ ] Does the system remain usable when any single dependency fails?
+- [ ] Are feature flags in place for non-critical shedding?
+- [ ] Is the degradation playbook documented for on-call?