mindforge-cc 10.0.3 → 11.0.0

package/.mindforge/skills/deployment-workflow/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: deployment-workflow
+version: 1.0.0
+min_mindforge_version: 10.0.5
+status: stable
+triggers: deploy, deployment, staged rollout, canary, feature flag rollout, rollback plan, production release, release pipeline, ship to production, go live, launch pipeline, release workflow
+---
+
+# Skill — Deployment Workflow (Staged Production Release Pipeline)
+
+## When this skill activates
+
+When deploying code to staging or production, planning a release, setting up
+feature flags, or managing rollback strategies. Use for any transition from
+"code is ready" to "code is live and monitored." Covers the full lifecycle from
+pre-deploy verification through post-deploy health confirmation.
+
+Core principle: **Never deploy blind** — every release has a rollback plan,
+success thresholds, and monitoring before it is considered complete.
+
+## Mandatory actions when this skill is active
+
+### Before deployment begins
+
+1. **Select depth level based on risk:**
+
+   | Level | Time | When to use | Scope |
+   |-------|------|-------------|-------|
+   | Quick | 5-10 min | Hotfix, docs, config | Git clean + tests only |
+   | Standard | 15-30 min | Feature, refactor | Full pipeline |
+   | Deep | 30-60 min | Breaking change, infra | Backup + load test + canary |
+
+2. **Pre-deploy checklist (all levels):**
+   - [ ] Working directory is clean (`git status` shows no uncommitted changes)
+   - [ ] All tests pass (`npm test` / `pytest` / equivalent)
+   - [ ] No lint errors or type errors
+   - [ ] CHANGELOG updated with version and summary
+   - [ ] Branch is rebased on latest main
+   - [ ] PR approved (if applicable)
+
+3. **Risk assessment:**
+   - Does this touch auth, payments, or PII? (triggers security review)
+   - Does this require a database migration? (adds rollback complexity)
+   - Does this change public API contracts? (requires versioning)
+   - What is the blast radius if this fails? (single user vs all users)
+
+### During deployment
+
+**Phase 1 — Build & Bundle:**
+- Compile/transpile all source
+- Run type checker (zero errors required)
+- Bundle analysis: warn if any chunk exceeds 250KB
+- Generate source maps for production debugging
+- Tag commit with version: `git tag v[X.Y.Z]`
+
+**Phase 2 — Staging:**
+- Deploy to staging environment
+- Run health check endpoint (HTTP 200 within 30s)
+- Execute smoke test suite (critical paths only)
+- Verify environment variables are set correctly
+- Check database connectivity and migration status
+
+**Phase 3 — Production (select strategy):**
+
+| Strategy | Use when | Process |
+|----------|----------|---------|
+| Quick | Low risk, fast rollback | Deploy all at once, monitor 5 min |
+| Rolling | Medium risk | Replace instances 25% at a time, 2 min between |
+| Canary | High risk, new feature | 5% → 25% → 50% → 100%, monitor at each step |
+
+**Phase 4 — Monitoring (mandatory for all strategies):**
+- Watch error rates for 15 minutes post-deploy
+- Compare P95 latency to pre-deploy baseline
+- Check business metrics (conversion, signup, core actions)
+- Verify no new error types in exception tracker
+
+**Decision thresholds:**
+```
+GREEN (proceed):  Error rate < 10% above baseline
+YELLOW (investigate): Error rate 10-100% above baseline
+RED (rollback):   Error rate > 2x baseline OR P95 > 3x baseline
+```
+
+**Feature flag lifecycle (when applicable):**
+```
+DEPLOY (flag OFF) → ENABLE (team only) → CANARY (5% users) →
+GRADUAL (25% → 50% → 75%) → FULL (100%) → CLEANUP (remove flag)
+```
+
+- Each stage requires minimum 1 hour soak time (24 hours for GRADUAL steps)
+- Monitor flag-specific metrics at each stage
+- Rollback = disable flag (instant, < 1 minute)
+
+### After deployment
+
+1. **Health verification:**
+   - [ ] All health endpoints return 200
+   - [ ] Error rate < 1% (absolute, not relative)
+   - [ ] No new exception types in monitoring
+   - [ ] P95 latency within acceptable range
+   - [ ] Business metrics stable (no cliff)
+
+2. **Rollback procedures (know these BEFORE deploying):**
+
+   | Method | Time | When to use |
+   |--------|------|-------------|
+   | Feature flag disable | ~1 min | Flag-guarded changes |
+   | Git revert + redeploy | ~5 min | Code-only changes |
+   | Database rollback | ~15 min | Migration-dependent changes |
+
+3. **Post-deploy documentation:**
+   - Update DEPLOYMENT.md with:
+     - Phase timestamps (start, staging, production, verified)
+     - Commit hash deployed
+     - Strategy used
+     - Any issues encountered and resolution
+     - Final status: SUCCESS / ROLLED_BACK / PARTIAL
+
+4. **Metrics baseline:**
+   - Record current performance metrics as new baseline
+   - Archive previous baseline for comparison
+   - Update alerting thresholds if performance improved
+
+## Self-check before task completion
+
+Before marking a deployment task done:
+
+- [ ] Did I verify all pre-deploy checks pass (tests, lint, types)?
+- [ ] Did I document the rollback plan BEFORE deploying?
+- [ ] Did I set up monitoring and define success thresholds?
+- [ ] Did I wait the minimum soak time before declaring success?
+- [ ] Did I record the deployment in DEPLOYMENT.md with timestamps?
+- [ ] Is the error rate below 1% post-deploy?
+- [ ] Did I update the metrics baseline?
+- [ ] If using feature flags: is the cleanup step scheduled?

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

@@ -0,0 +1,113 @@
+---
+name: design-system
+version: 1.0.0
+min_mindforge_version: 10.0.7
+status: stable
+triggers: design system architecture, component library design, design token system, storybook documentation, variant pattern design, theme architecture, atomic design pattern, component documentation standard, design system versioning, token based theming, component catalog, ui component library
+---
+
+# Design System
+
+## When this skill activates
+
+This skill activates when the user is designing, building, or maintaining a design
+system or component library. This includes design token architecture, atomic design
+methodology, component API design, Storybook documentation, variant patterns, theme
+architecture (dark/light/custom), design system versioning strategy, contribution
+models, and component catalog organization.
+
+## Mandatory actions
+
+### Before
+
+1. Identify the target frameworks and platforms (React, Vue, Svelte, iOS, Android, web components).
+2. Determine the team size and contribution model (centralized team vs federated).
+3. Assess existing UI components and visual inconsistencies to address.
+4. Review brand guidelines and design specifications (Figma, Sketch, or equivalent).
+5. Identify theming requirements (dark mode, white-label, multi-brand).
+
+### During
+
+**Design Tokens:**
+- **Primitive tokens:** Raw values with no semantic meaning (colors: `blue-500: #3B82F6`, spacing: `space-4: 16px`, typography: `font-size-lg: 18px`).
+- **Semantic tokens:** Meaningful aliases that reference primitives (`color-primary: {blue-500}`, `color-text-default: {gray-900}`, `spacing-inline-md: {space-4}`).
+- **Component tokens:** Scoped to specific components (`button-padding-x: {spacing-inline-md}`, `button-bg-primary: {color-primary}`).
+- Store tokens in a tool-agnostic format (JSON/YAML) and generate platform-specific outputs (CSS custom properties, Swift/Kotlin constants, SCSS variables).
+- Use Style Dictionary or Tokens Studio for token transformation pipelines.
+- Token naming convention: `{category}-{property}-{variant}-{state}` (e.g., `color-text-primary-hover`).
+
+**Atomic Design Methodology:**
+- **Atoms:** Smallest indivisible elements (Button, Input, Icon, Label, Badge).
+- **Molecules:** Groups of atoms functioning together (SearchBar = Input + Button, FormField = Label + Input + ErrorMessage).
+- **Organisms:** Complex sections composed of molecules (Header = Logo + Nav + SearchBar, Card = Image + Title + Description + Actions).
+- **Templates:** Page layouts without real content (defines the skeleton/grid).
+- **Pages:** Templates populated with real content (final implementation).
+- Not every component fits neatly — use atomic levels as guidance, not strict rules.
+
+**Component API Design:**
+- Props interface is the public contract. Design it carefully.
+- Use variants via props, not CSS class names (`<Button variant="primary">` not `<Button className="btn-primary">`).
+- Prefer composition over configuration (slot-based patterns, children, render props).
+- Limit prop count: if > 8 props, consider splitting into sub-components.
+- Use TypeScript/PropTypes for full type safety on component interfaces.
+- Default props to the most common use case (progressive disclosure).
+- Forward refs and spread remaining props for extensibility.
+
+**Storybook Documentation:**
+- One story file per component, co-located with the component source.
+- Stories for every meaningful state: default, hover, focus, disabled, loading, error, empty.
+- Use args/controls for interactive prop exploration.
+- Include the a11y addon and verify each story passes accessibility checks.
+- Write MDX documentation pages for usage guidelines and do/don't examples.
+- Chromatic or Percy for visual regression testing on every PR.
+
+**Versioning:**
+- Semantic versioning (semver) for the component library package.
+- **Major:** Breaking API changes (prop removal, renamed component, changed behavior).
+- **Minor:** New components, new variants, additive features.
+- **Patch:** Bug fixes, accessibility improvements, style corrections.
+- Maintain a changelog (auto-generated from conventional commits).
+- Support at least one previous major version during migration period.
+- Pin design system version in consuming applications.
+
+**Theming:**
+- CSS custom properties for runtime theme switching (no rebuild required).
+- Theme object structure mirrors semantic token hierarchy.
+- Support: light, dark, and system-preference (prefers-color-scheme).
+- White-label: allow consumers to override semantic tokens without touching components.
+- Test all components in all supported themes (visual regression).
+- Provide a ThemeProvider component for React/Vue context-based theming.
+
+**Contribution Model:**
+- RFC process for new components (proposal → review → build → document → release).
+- Review criteria: accessibility, responsiveness, theme support, documentation, tests.
+- Component readiness checklist before merging into the system.
+- Deprecation policy: announce → mark deprecated → migration guide → remove after N versions.
+- Office hours or design system team review for proposed additions.
+
+**Accessibility (Built-in):**
+- Every component must meet WCAG 2.1 AA as a minimum.
+- Keyboard navigation, focus management, and ARIA attributes are non-negotiable.
+- Color contrast ratios enforced via tokens (4.5:1 for text, 3:1 for UI elements).
+- Screen reader testing as part of component QA.
+- Document accessibility patterns in component documentation.
+
+### After
+
+1. Verify token pipeline generates correct outputs for all target platforms.
+2. Confirm Storybook coverage includes all component states and variants.
+3. Validate theme switching works across all components without visual regressions.
+4. Check accessibility audit passes for every component in the catalog.
+5. Ensure versioning and changelog are current and accurate.
+6. Validate contribution documentation is clear for new contributors.
+
+## Self-check before task completion
+
+- [ ] Design tokens follow the three-tier hierarchy (primitive → semantic → component).
+- [ ] Components follow atomic design principles with clear categorization.
+- [ ] Component APIs use props for variants and composition for flexibility.
+- [ ] Storybook documents all states with interactive controls and accessibility checks.
+- [ ] Versioning follows semver with a maintained changelog.
+- [ ] Theming supports light/dark/system with CSS custom properties.
+- [ ] Contribution model includes RFC process and readiness checklist.
+- [ ] Accessibility meets WCAG 2.1 AA across all components and themes.

package/.mindforge/skills/developer-onboarding/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: developer-onboarding
+version: 1.0.0
+min_mindforge_version: 10.0.8
+status: stable
+triggers: developer onboarding, first day script, time to first commit, starter task, onboarding checklist, readme driven, local setup, onboarding buddy, knowledge transfer, ramp up plan, new hire guide, dev environment setup
+---
+
+# Developer Onboarding
+
+## When this skill activates
+
+This skill activates when creating or improving developer onboarding processes, writing setup scripts, curating starter tasks, designing ramp-up plans, or reducing time-to-first-commit for new team members. It applies to both new hire onboarding and existing developers joining a new project.
+
+## Mandatory actions when this skill is active
+
+### Before
+
+1. Identify the target developer profile (junior/senior, frontend/backend/fullstack, intern/FTE).
+2. Measure current time-to-first-commit (if unknown, estimate from last onboarding).
+3. Inventory existing onboarding materials (README, wiki, setup scripts, recorded sessions).
+4. Identify the most common setup failures (from Slack history, onboarding feedback).
+5. Determine who will act as onboarding buddy for new joiners.
+
+### During
+
+**North Star Metric: Time-to-First-Commit**
+- Target: < 4 hours from laptop opening to merged PR.
+- Measure: first commit to main branch (not just local setup complete).
+- Track this metric for every new joiner. If it degrades, fix the onboarding immediately.
+- This metric reveals every broken doc, missing tool, and outdated step.
+
+**First-Day Setup Script:**
+- One command should set up everything: `make setup` or `./scripts/setup.sh`.
+- Script must handle: dependency installation, environment variables, database setup, seed data, test run.
+- Script must be idempotent (safe to run multiple times).
+- Script must detect and report issues clearly (missing tool versions, port conflicts).
+- Script must work on all team platforms (macOS, Linux; Windows via WSL if needed).
+- Include a final verification step: "Setup complete. Running tests... All 47 tests passed."
+
+**README-Driven Development:**
+- If it is not in the README, it does not exist for new developers.
+- README must answer: How do I run it? How do I test it? How do I deploy it? Where do I ask questions?
+- Keep setup instructions in the README (not a wiki that gets stale).
+- Test the README quarterly: have someone follow it literally on a fresh machine.
+- Mark prerequisites explicitly: Node 20+, Docker, PostgreSQL 15, etc.
+
+**Starter Tasks (Good First Issues):**
+- Label issues explicitly: `good-first-issue`, `starter-task`, `onboarding`.
+- Scope: achievable in 2-4 hours, touches 1-3 files, has clear acceptance criteria.
+- Include: link to relevant code, example of similar completed work, who to ask.
+- Types that work well: fix a typo in UI, add a missing validation, write a test for uncovered code, update a dependency.
+- Avoid: tasks requiring deep domain knowledge, cross-service changes, or ambiguous requirements.
+
+**Onboarding Buddy System:**
+- Assign a buddy for the first 2 weeks (not the manager, a peer).
+- Buddy responsibilities: pair on first PR, answer "dumb" questions, review first 3 PRs same-day.
+- Buddy should proactively check in (don't wait for the new dev to ask).
+- Rotate buddy duty across team (prevents knowledge silos, spreads empathy).
+
+**Knowledge Transfer:**
+- Record short Loom videos of key workflows (deploy process, debugging common issues, release flow).
+- Keep recordings under 10 minutes (people don't watch long videos).
+- Store in a discoverable location (project wiki, onboarding channel pinned messages).
+- Update when workflows change (stale videos are worse than no videos).
+- Architecture diagram: one page showing services, databases, and data flow.
+
+**Ramp-Up Plan (4-Week Template):**
+- **Week 1**: Environment setup, explore codebase, first starter task merged, meet team.
+- **Week 2**: First bug fix (real issue from backlog), attend architecture walkthrough, pair with buddy.
+- **Week 3**: Small feature (scoped, designed by senior, implemented independently), first code review given.
+- **Week 4**: Independent work on medium-scoped task, contribute to team process (improve a doc, fix flaky test).
+- Checkpoint at end of each week: buddy + manager assess progress, adjust plan if needed.
+
+**Common Pitfalls to Prevent:**
+- Setup docs reference tools that are no longer used.
+- Env vars documented in one place but actual required set has grown.
+- "Ask Bob" for access — Bob is on vacation. Document the process instead.
+- Tests pass on CI but fail locally due to missing env vars or services.
+- New dev changes something they shouldn't because boundaries aren't documented.
+
+### After
+
+1. New developer has a merged PR within the target timeframe.
+2. Setup script runs without manual intervention on a fresh machine.
+3. All blockers encountered are fixed in the onboarding materials immediately.
+4. Feedback collected from new developer (what was confusing, what was missing).
+5. Onboarding materials updated based on feedback.
+
+## Self-check before task completion
+
+- [ ] Setup script is one command and runs successfully on a clean machine.
+- [ ] README contains all information needed to run, test, and deploy locally.
+- [ ] At least 3 starter tasks are labeled and ready for the next new joiner.
+- [ ] Ramp-up plan exists with weekly milestones and checkpoints.
+- [ ] Onboarding buddy is assigned and knows their responsibilities.
+- [ ] Architecture diagram is current and accessible.
+- [ ] Time-to-first-commit metric is tracked and below the 4-hour target.
+- [ ] Feedback loop exists: every new joiner improves the process for the next one.

package/.mindforge/skills/developer-productivity-metrics/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: developer-productivity-metrics
+version: 1.0.0
+min_mindforge_version: 10.7.0
+status: stable
+triggers: developer productivity metrics, DORA metrics implementation, developer experience survey, flow metric, cognitive load measurement, engineering effectiveness, developer satisfaction, deployment frequency, lead time metric, change failure rate, developer velocity, engineering metric dashboard
+---
+
+# Skill — Developer Productivity Metrics
+
+## When this skill activates
+
+This skill activates when the user is designing or implementing developer productivity measurement systems. This includes DORA metrics (deployment frequency, lead time, change failure rate, MTTR), developer experience surveys, flow metrics, cognitive load measurement, engineering effectiveness tracking, developer satisfaction scoring, velocity metrics, and engineering metric dashboards.
+
+## Mandatory actions when this skill is active
+
+### Before writing any code
+
+1. Identify the goal of measurement: improve developer experience, justify platform investment, identify bottlenecks, or benchmark against industry.
+2. Survey developers to understand perceived friction points before instrumenting metrics (avoid measuring the wrong thing).
+3. Establish a baseline for each metric category (DORA, flow, satisfaction) to track improvement over time.
+4. Define metric ownership: who monitors, who acts on findings, and what decision-making authority they have.
+5. Commit to "metrics for improvement, not punishment" — avoid individual developer tracking or performance reviews based on these metrics.
+
+### During implementation
+
+- **DORA Metrics (Four Keys):**
+  - **Deployment Frequency:** Count deployments to production per day/week. Elite: multiple per day. High: once per day to once per week.
+  - **Lead Time for Changes:** Time from commit to production deploy. Elite: under 1 hour. High: under 1 day.
+  - **Change Failure Rate:** Percentage of deployments causing incidents. Elite: 0-15%. High: 16-30%.
+  - **Mean Time to Restore (MTTR):** Time from incident detection to resolution. Elite: under 1 hour. High: under 1 day.
+- **Flow Metrics (SPACE Framework):**
+  - **Satisfaction:** Developer experience survey (quarterly, 10-15 questions, NPS score). Track: tooling satisfaction, cognitive load, collaboration quality.
+  - **Performance:** DORA metrics + throughput (PRs merged, features shipped per sprint).
+  - **Activity:** Commits, PRs, code reviews. Use as context, not performance indicator.
+  - **Communication:** PR review time, unblocking time, documentation quality.
+  - **Efficiency:** Time in flow state (4+ hours uninterrupted), meeting load, context switches per day.
+- **Cognitive Load Measurement:** Survey-based (scale 1-10): "How many systems do you need to understand to complete typical tasks?" "How often do you context switch?" "How easy is it to find information?"
+- **Engineering Effectiveness Dashboard:** Single dashboard showing DORA metrics, flow metrics, developer satisfaction, and trend lines. Refresh daily. Include comparisons to industry benchmarks (DORA State of DevOps Report).
+- **Avoid Vanity Metrics:** Lines of code written, commits per day, hours logged. These measure activity, not impact. Focus on outcomes (features shipped, incidents prevented, time saved).
+- **Privacy Guardrails:** Aggregate metrics at team level (minimum 5 developers). Never track individual developer productivity. Anonymize survey responses.
+
+### After implementation
+
+- Verify DORA metrics are auto-collected from CI/CD pipelines and incident management systems (no manual entry).
+- Confirm developer experience surveys run quarterly with at least 70% response rate.
+- Validate that engineering effectiveness dashboard refreshes daily and includes trend lines.
+- Ensure metrics are reviewed in team retrospectives with action items to address bottlenecks.
+- Check that metrics are never used for individual performance reviews (enforce via policy).
+
+## Self-check before task completion
+
+- [ ] DORA four keys are auto-collected and tracked (deployment frequency, lead time, change failure rate, MTTR).
+- [ ] Developer experience survey runs quarterly with 70%+ response rate.
+- [ ] Flow metrics cover satisfaction, performance, activity, communication, and efficiency.
+- [ ] Cognitive load is measured via survey and tracked over time.
+- [ ] Engineering effectiveness dashboard refreshes daily and shows trend lines.
+- [ ] Metrics are aggregated at team level (minimum 5 developers) to protect individual privacy.
+- [ ] Metrics are reviewed in retrospectives with action items to improve developer experience.

package/.mindforge/skills/distributed-consensus/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: distributed-consensus
+version: 1.0.0
+min_mindforge_version: 10.1.1
+status: stable
+triggers: distributed consensus, raft algorithm, paxos, leader election, split-brain prevention, quorum read, quorum write, consensus protocol, distributed lock, linearizability, strong consistency, consensus group
+---
+
+# Skill — Distributed Consensus
+
+## When this skill activates
+Any task involving strong consistency requirements in distributed systems,
+leader election, distributed locks, quorum-based reads/writes,
+or preventing split-brain scenarios in clustered systems.
+
+## Mandatory actions when this skill is active
+
+### Before writing any code
+1. Confirm consensus is actually needed (not everything requires strong consistency).
+2. Identify what data requires linearizability vs what can be eventually consistent.
+3. Choose existing implementation (etcd, ZooKeeper, Consul) — never build your own.
+4. Size the cluster (odd numbers only: 3 for most, 5 for critical).
+
+### During implementation
+- Use established consensus systems (etcd/ZooKeeper/Consul) — do NOT implement Raft/Paxos yourself.
+- Implement fencing tokens for all distributed locks.
+- Handle network partitions explicitly (what happens when consensus is lost?).
+- Set appropriate timeouts for leader election (not too short = flapping, not too long = unavailability).
+- Use consensus ONLY for metadata/coordination — never for high-throughput data plane.
+
+### After implementation
+- Test split-brain scenarios (network partition between nodes).
+- Verify leader election completes within acceptable time.
+- Confirm fencing tokens prevent stale operations.
+- Load test to ensure consensus doesn't become a bottleneck.
+- Monitor cluster health (leader stability, replication lag).
+
+## Raft Consensus (Most Common)
+
+### How It Works
+1. **Leader Election**: Nodes start as followers. If no heartbeat from leader within timeout, a follower becomes a candidate and requests votes.
+2. **Log Replication**: Leader receives writes, appends to log, replicates to followers.
+3. **Commitment**: Entry is committed when majority (quorum) acknowledges.
+4. **Safety**: Only one leader per term. Committed entries are never lost.
+
+### Key Properties
+- Strong leader (all writes go through leader).
+- Leader elected by majority vote.
+- Log entries committed when replicated to majority.
+- Cluster tolerates (N-1)/2 failures (3 nodes tolerates 1, 5 tolerates 2).
+
+## Quorum Mathematics
+
+### Formulas
+```
+N = total nodes
+W = write quorum (nodes that must acknowledge a write)
+R = read quorum (nodes that must respond to a read)
+
+Strong consistency: R + W > N
+Write availability: W ≤ N (can tolerate N-W failures for writes)
+Read availability: R ≤ N (can tolerate N-R failures for reads)
+```
+
+### Common Configurations
+| N | W | R | Consistency | Write Tolerance | Read Tolerance |
+|---|---|---|-------------|-----------------|----------------|
+| 3 | 2 | 2 | Strong | 1 failure | 1 failure |
+| 5 | 3 | 3 | Strong | 2 failures | 2 failures |
+| 5 | 3 | 1 | Eventual reads | 2 failures | 4 failures |
+
+## Split-Brain Prevention
+
+### The Problem
+Network partition can create two groups, each believing it's the leader.
+
+### Solutions
+1. **Majority quorum**: Only the partition with majority can elect a leader.
+2. **Fencing tokens**: Monotonically increasing token with every lock acquisition. Storage rejects operations with stale tokens.
+3. **Epoch numbers**: Leader increments epoch on election. Older epochs are rejected.
+4. **External witness**: Third-party arbiter breaks ties (but introduces dependency).
+
+### Fencing Token Pattern
+```
+Client A acquires lock → token=42
+Client A pauses (GC, network)
+Client B acquires lock → token=43
+Client A resumes, sends write with token=42
+Storage rejects: 42 < 43 (stale token)
+```
+
+## When to Use Consensus
+
+### Good Use Cases
+- Leader election for worker coordination.
+- Distributed configuration management.
+- Service discovery and membership.
+- Distributed locks (with fencing tokens).
+- Metadata storage (small, infrequently written).
+
+### Anti-Patterns (DON'T use consensus for)
+- High-throughput data writes (consensus = bottleneck at ~10K writes/sec).
+- Large data storage (consensus stores small metadata, not big data).
+- Read-heavy workloads (use eventual consistency + caching instead).
+- Every database write (use consensus for critical metadata only).
+
+## Practical Systems
+
+### etcd
+- Raft-based, Kubernetes uses it for cluster state.
+- Key-value store with watch capabilities.
+- Best for: service discovery, config, leader election.
+
+### ZooKeeper
+- ZAB protocol (similar to Raft).
+- Hierarchical namespace with ephemeral nodes.
+- Best for: distributed locks, barriers, leader election.
+
+### Consul
+- Raft-based, service mesh integration.
+- Service discovery + health checking + KV store.
+- Best for: service mesh, multi-datacenter coordination.
+
+## Failure Scenarios to Test
+
+1. **Leader crash**: New leader elected within timeout. No committed data lost.
+2. **Network partition (minority isolated)**: Majority continues. Minority becomes read-only or unavailable.
+3. **Network partition (even split)**: Neither side has majority → cluster unavailable until partition heals.
+4. **Slow node**: Doesn't affect consensus (majority can proceed without it).
+5. **Clock skew**: Raft uses logical clocks — physical clock skew shouldn't matter.
+6. **Disk full on leader**: Leader steps down, new election.
+
+## Self-check
+- [ ] Consensus is genuinely needed (not over-engineering eventual consistency).
+- [ ] Using established system (etcd/ZooKeeper/Consul) — not custom implementation.
+- [ ] Cluster size is odd (3 or 5).
+- [ ] Fencing tokens implemented for distributed locks.
+- [ ] Network partition behavior tested and documented.
+- [ ] Consensus used only for coordination/metadata (not data plane).
+- [ ] Leader election timeout tuned (not too short, not too long).
+- [ ] Monitoring: leader stability, replication lag, cluster health.