mindforge-cc 10.0.2 → 10.7.0

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

@@ -0,0 +1,119 @@
+---
+name: serverless-patterns
+version: 1.0.0
+min_mindforge_version: 10.1.1
+status: stable
+triggers: serverless pattern, cold start mitigation, function composition, event trigger lambda, stateless function, serverless state management, lambda architecture, function timeout, serverless cost model, ephemeral compute, serverless scaling, function orchestration
+compose: cost-estimation
+---
+
+# Skill — Serverless Patterns
+
+## When this skill activates
+Any task involving serverless function design, cold start optimization,
+function composition, event-driven architectures using FaaS platforms,
+or cost modeling for serverless workloads.
+
+## Mandatory actions when this skill is active
+
+### Before writing any code
+1. Identify the trigger type (HTTP, queue, schedule, storage event, stream).
+2. Determine state requirements and where state will live (DynamoDB, Redis, S3).
+3. Estimate invocation volume and duration for cost projection.
+4. Decide composition pattern (Step Functions vs choreography vs direct invoke).
+
+### During implementation
+- Keep functions focused (single responsibility).
+- Externalize all state (no reliance on local filesystem or memory between invocations).
+- Implement idempotency keys for retry-safe operations.
+- Set appropriate timeout values (not max — just enough + buffer).
+- Use structured logging with correlation IDs for distributed tracing.
+- Checkpoint long-running work before timeout boundary.
+
+### After implementation
+- Verify cold start latency meets SLA requirements.
+- Confirm cost model aligns with budget (invocations × duration × memory).
+- Test retry and failure scenarios end-to-end.
+- Monitor concurrency limits and throttling metrics.
+
+## Cold Start Mitigation
+
+### Techniques
+1. **Provisioned concurrency** — Pre-warm N instances (cost trade-off).
+2. **Bundle optimization** — Smaller deployment = faster init.
+3. **Avoid VPC** — VPC attachment adds 5-10s cold start (only if DB needed).
+4. **Lazy initialization** — Defer heavy setup until first request needs it.
+5. **Connection pooling** — Use RDS Proxy or connection pool service.
+6. **Language choice** — Go/Rust cold start < Python < Java/Node.
+
+### When cold start matters
+- Synchronous user-facing APIs (matters a lot).
+- Async queue processors (usually doesn't matter).
+- Scheduled jobs (doesn't matter at all).
+
+## Composition Patterns
+
+### Step Functions (Orchestration)
+- Central coordinator manages workflow state.
+- Built-in retry, catch, timeout per step.
+- Visual debugging of execution history.
+- Best for: complex workflows, human approval steps, long-running processes.
+
+### Choreography (Event-Driven)
+- Each function emits events, others react.
+- No single point of failure.
+- Harder to debug end-to-end.
+- Best for: loosely coupled, independent scaling per step.
+
+### Fan-Out / Fan-In
+- Dispatch N parallel tasks → aggregate results.
+- Use SQS/SNS for fan-out, DynamoDB for aggregation.
+- Handle partial failures gracefully.
+
+## State Management
+
+| State Type | Solution | Use When |
+|-----------|----------|----------|
+| Session state | DynamoDB / Redis | Auth tokens, cart |
+| Workflow state | Step Functions | Multi-step processes |
+| Cache | ElastiCache / DAX | Repeated reads |
+| File state | S3 | Large objects |
+| Event state | Event carried | Pass between functions |
+
+## Cost Model
+
+```
+Monthly cost = (invocations × $0.20/1M) + (GB-seconds × $0.0000166667)
+```
+
+### Cost comparison triggers
+- If >1M invocations/hour sustained → consider containers.
+- If function runs >15min → containers or batch.
+- If always-on with predictable load → containers cheaper.
+- If spiky/unpredictable → serverless wins on cost.
+
+## Trigger Patterns
+
+| Trigger | Pattern | Key Concern |
+|---------|---------|-------------|
+| HTTP (API Gateway) | Request/response | Cold start latency |
+| SQS | Queue consumer | Batch size, visibility timeout |
+| Schedule (cron) | Periodic job | Idempotency on overlap |
+| S3 event | File processor | Duplicate events possible |
+| DynamoDB stream | Change capture | Ordering guarantees |
+| Kinesis | Stream processor | Shard iterator, checkpointing |
+
+## Timeout Strategy
+- Set timeout = expected p99 duration + 20% buffer.
+- Checkpoint work before 80% of timeout.
+- Implement dead-letter queues for timed-out invocations.
+- Never set timeout to maximum "just in case."
+
+## Self-check
+- [ ] Function is idempotent (safe to retry).
+- [ ] State externalized (no local filesystem reliance).
+- [ ] Timeout set appropriately (not max).
+- [ ] Cold start measured and within SLA.
+- [ ] Cost model validated against expected traffic.
+- [ ] Dead-letter queue configured for failures.
+- [ ] Correlation IDs propagated for tracing.

package/.mindforge/skills/skill-creator-meta/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: skill-creator-meta
+version: 1.0.0
+min_mindforge_version: 10.0.5
+status: stable
+triggers: create skill, skill creator, author skill, build skill, new skill, skill development, skill writing, skill testing, skill eval, meta-skill, skill optimization, skill iteration
+compose: eval-harness
+---
+
+# Skill — Skill Creator Meta (Iterative Skill Authoring & Optimization)
+
+## When this skill activates
+
+When creating, authoring, testing, or optimizing MindForge skills. This is the
+meta-skill that governs the lifecycle of all other skills — from initial interview
+through eval-driven iteration to final registration. Use whenever a new skill needs
+to be created, an existing skill needs optimization, or skill quality needs
+systematic validation.
+
+Core principle: **Eval-driven iteration** — skills are not "done" until they
+demonstrably outperform the no-skill baseline on realistic test cases.
+
+## Mandatory actions when this skill is active
+
+### Before skill creation begins
+
+1. **Interview for specification:**
+   - What does this skill do? (one-sentence purpose)
+   - When should it trigger? (specific user intents, not vague categories)
+   - What is the output format? (file, inline response, structured data)
+   - What edge cases exist? (partial matches, ambiguous triggers, conflicting skills)
+   - What dependencies does it have? (other skills via compose, external tools, MCP servers)
+
+2. **Validate against existing skills:**
+   - Check MANIFEST.md for trigger overlap (jaccard > 0.3 = conflict)
+   - Verify the skill covers a genuinely distinct capability
+   - If overlap exists: either extend existing skill or document why separation is needed
+
+3. **Define the skill schema constraints:**
+   - SKILL.md must be under 500 lines (enforced)
+   - YAML frontmatter must include: name, version, min_mindforge_version, status, triggers
+   - Optional: compose (list of skill dependencies activated alongside)
+   - Body must include: "When this skill activates", "Mandatory actions when this skill is active" (Before/During/After), "Self-check before task completion"
+
+### During skill creation
+
+**Phase 1 — Draft:**
+- Write the SKILL.md following the schema exactly
+- Triggers should be 8-15 phrases covering natural language variations
+- Body should be action-oriented (imperative verbs, numbered steps)
+- Include concrete examples where behavior might be ambiguous
+
+**Phase 2 — Create test cases:**
+```
+.mindforge/evals/[skill-name]/
+├── test-cases.json   # 2-3 realistic prompts complex enough to trigger loading
+├── assertions.json   # objectively verifiable success criteria
+└── benchmark.json    # aggregated results across iterations
+```
+
+Test case structure:
+```json
+{
+  "test_cases": [
+    {
+      "id": "tc-001",
+      "prompt": "realistic user prompt that should trigger this skill",
+      "context": "any relevant project state",
+      "expected_behaviors": ["specific", "verifiable", "outcomes"],
+      "should_trigger": true
+    }
+  ]
+}
+```
+
+**Phase 3 — Parallel evaluation:**
+- Run each test case WITH the skill loaded (experimental condition)
+- Run each test case WITHOUT the skill loaded (baseline condition)
+- Compare outputs on defined assertions
+- Skill must demonstrably improve output quality over baseline
+
+**Phase 4 — Trigger optimization:**
+- Generate 20 trigger evaluation queries:
+  - 10 that SHOULD trigger the skill (true positives)
+  - 10 that should NOT trigger (true negatives — related but distinct intents)
+- Test trigger matching accuracy
+- Iterate on name/description/triggers up to 5 times until precision > 90%
+
+**Phase 5 — User review:**
+- Present: skill draft, test case outputs, benchmark scores, trigger accuracy
+- Collect feedback on: missing behaviors, unnecessary behaviors, trigger gaps
+- Document feedback for improvement phase
+
+**Phase 6 — Improvement:**
+- Generalize from specific feedback to patterns
+- Bundle repeated helper logic into `scripts/` directory within skill folder
+- Rewrite sections that received negative feedback
+- Ensure changes don't regress previously-passing test cases
+
+**Phase 7 — Final iteration:**
+- Rerun all test cases against improved skill
+- Compare to previous iteration (must not regress)
+- If regression: investigate, fix, rerun
+
+### After skill creation
+
+1. **Register in MANIFEST.md:**
+   - Add entry with name, version, triggers, status
+   - Verify no trigger conflicts with existing entries
+
+2. **Verify file structure:**
+   ```
+   .mindforge/skills/[skill-name]/
+   ├── SKILL.md          # the skill definition (required)
+   ├── scripts/          # helper scripts if needed (optional)
+   └── README.md         # usage examples (optional)
+   ```
+
+3. **Store eval artifacts:**
+   ```
+   .mindforge/evals/[skill-name]/
+   ├── test-cases.json
+   ├── assertions.json
+   ├── benchmark.json
+   └── iterations/       # historical results per iteration
+   ```
+
+4. **Final quality gate:**
+   - Skill passes all test cases
+   - Trigger precision > 90% on 20-query eval set
+   - Skill outperforms baseline on all assertions
+   - No trigger conflicts in MANIFEST.md
+   - Under 500 lines
+
+## Self-check before task completion
+
+Before marking a skill creation task done:
+
+- [ ] Did I interview for edge cases and dependencies?
+- [ ] Did I create eval test cases (2-3 realistic prompts)?
+- [ ] Did I run parallel comparison (with-skill vs baseline)?
+- [ ] Did I optimize triggers with 20 evaluation queries (10 should, 10 should-not)?
+- [ ] Did I iterate based on user feedback?
+- [ ] Did I verify no trigger conflicts in MANIFEST.md?
+- [ ] Is the skill under 500 lines?
+- [ ] Does the final iteration outperform all previous iterations?

package/.mindforge/skills/sprint-retrospective-facilitation/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: sprint-retrospective-facilitation
+version: 1.0.0
+min_mindforge_version: 10.1.0
+status: stable
+triggers: sprint retrospective, retro facilitation, retrospective format, four Ls retrospective, sailboat retrospective, timeline retrospective, retro action item, team health signal, retro pattern detection, improvement tracking, retro activity, facilitation technique
+---
+
+# Sprint Retrospective Facilitation
+
+## When this skill activates
+
+This skill activates when planning, facilitating, or improving sprint retrospectives.
+It provides multiple retrospective formats, facilitation techniques for psychological
+safety, action item design principles, and pattern detection across retros to drive
+continuous team improvement.
+
+## Mandatory actions when this skill is active
+
+### Before
+
+1. **Select format based on team state** — Rotate formats to prevent staleness. Choose
+   based on what the team needs right now (celebration, problem-solving, future-focus).
+2. **Prepare the space** — Set up the board/template, send pre-retro prompts if using
+   async input, confirm time-box with team.
+3. **Review previous retro actions** — Check completion status of last retro's action
+   items. This is the first agenda item every time.
+
+### During
+
+4. **Retrospective formats (rotate these):**
+
+   - **4Ls (Liked / Learned / Lacked / Longed-for):**
+     Balanced format covering positives and gaps. Good default.
+     Liked = what went well; Learned = new insights; Lacked = what was missing;
+     Longed-for = wishes for the future.
+
+   - **Sailboat:**
+     Visual metaphor. Wind = forces helping us; Anchor = forces slowing us;
+     Rocks = risks ahead; Island = our goal/destination.
+     Good for teams needing to name risks they have been avoiding.
+
+   - **Timeline:**
+     Map sprint events chronologically, then discuss emotions/energy at each point.
+     Good for sprints with many events or high drama.
+     Reveals patterns in when energy drops or rises.
+
+   - **Start / Stop / Continue:**
+     Simple and direct. Start = new practices to try; Stop = practices hurting us;
+     Continue = practices working well. Good for action-oriented teams.
+
+   - **Mad / Sad / Glad:**
+     Emotion-focused. Good for teams that need to process feelings before solutions.
+     Validates that emotions are legitimate data.
+
+5. **Facilitation principles:**
+   - **Psychological safety first** — Explicitly state: "This is a blame-free zone.
+     We are examining the system, not judging individuals."
+   - **Equal voice** — Use silent writing before discussion. Prevents loud voices from
+     dominating. Everyone contributes before anyone speaks.
+   - **Time-box per section** — Strict timekeeping. Brainstorm (10 min), group/vote
+     (5 min), discuss top items (25 min), actions (10 min).
+   - **Dot-voting** — Each person gets 3 votes. Discuss only the top-voted items.
+     This prevents discussing everything superficially.
+   - **Facilitator does not contribute** — The facilitator manages process, not content.
+     If the facilitator has opinions, they participate as a team member and delegate
+     facilitation.
+
+6. **Action item design (SMART):**
+   - **Specific** — "Add integration test for payment flow" not "improve testing"
+   - **Measurable** — Clear definition of done
+   - **Assigned** — One owner (not "the team")
+   - **Realistic** — Achievable within next sprint
+   - **Time-boxed** — Due date before next retro
+   - Maximum 3 action items per retro (more = none get done)
+
+7. **Pattern detection across retros:**
+   - Track themes that recur across multiple retros.
+   - If the same issue appears 3+ times, it is systemic — escalate to leadership or
+     dedicate a sprint to fixing it.
+   - Maintain a "retro theme tracker" showing issue frequency over time.
+   - Celebrate patterns that disappear (proof that retros drive improvement).
+
+8. **Team health signals to monitor:**
+   - Participation level (are people engaged or checked out?)
+   - Action item completion rate (are retros driving change?)
+   - Theme recurrence (are the same problems persisting?)
+   - Energy/morale trend (is the team trajectory improving?)
+   - Psychological safety indicators (are people raising hard topics?)
+
+### After
+
+9. **Publish retro summary** — Share action items and key themes with the team within
+   24 hours. Keep it brief.
+10. **Track action items** — Add to sprint backlog or team board. Review completion at
+    next retro opening.
+11. **Rotate facilitator** — Different person each sprint builds shared ownership of
+    team improvement.
+12. **Evolve the process** — If retros feel stale, try a new format. If attendance
+    drops, investigate why. The retro itself should improve over time.
+
+## Self-check before task completion
+
+- [ ] Previous retro action items reviewed for completion status
+- [ ] Format selected intentionally (not just defaulting to the same one)
+- [ ] Psychological safety explicitly established at the start
+- [ ] Equal voice mechanisms used (silent writing, voting)
+- [ ] Discussion time-boxed with strict facilitation
+- [ ] Maximum 3 SMART action items generated
+- [ ] Each action item has a single owner and due date
+- [ ] Recurring themes identified and tracked
+- [ ] Summary published within 24 hours

package/.mindforge/skills/stakeholder-communication/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: stakeholder-communication
+version: 1.0.0
+min_mindforge_version: 10.3.0
+status: stable
+triggers: stakeholder communication, technical translation, non-technical explanation, executive reporting technical, risk communication, engineering status update, technical storytelling, cross-functional communication, engineering metrics reporting, progress communication, technical presentation, stakeholder alignment
+---
+
+# Stakeholder Communication
+
+## When this skill activates
+
+This skill activates when translating technical concepts for non-technical audiences, writing executive status reports, communicating risks and tradeoffs, presenting technical work to cross-functional teams, or aligning stakeholders on technical decisions. It applies to engineers, tech leads, and engineering managers who interface with product, design, executives, or customers.
+
+## Mandatory actions when this skill is active
+
+### Before communicating with stakeholders
+
+1. **Identify the audience** — Executives care about business impact, timelines, and risks. Product managers care about feature tradeoffs and user impact. Designers care about constraints and implementation feasibility. Tailor the message to the audience.
+2. **Define the communication goal** — Are you informing (status update), persuading (proposal approval), or aligning (shared understanding)? Different goals require different structures.
+3. **Anticipate questions** — What will stakeholders ask? Prepare answers for: "How long will this take?", "What happens if we skip this?", "What's the risk?", "Can we do X instead?"
+4. **Remove jargon** — Read your draft out loud. If you use terms like "idempotency," "eventual consistency," or "distributed lock," either define them or use simpler language. Jargon creates confusion, not credibility.
+
+### During stakeholder interactions
+
+#### Technical Translation Principles
+
+- **Start with outcomes, not implementation** — Don't say "We're migrating from REST to GraphQL." Say "Users will get faster page loads because we'll fetch only the data they need, not the entire object."
+- **Use analogies for complex concepts** — Distributed systems are like postal mail (messages can arrive out of order). Caching is like a notepad (faster but can be outdated). Load balancing is like grocery store checkout lanes (distributes work evenly).
+- **Quantify whenever possible** — "This will improve performance" is vague. "This will reduce page load from 3 seconds to 1 second for 80% of users" is concrete.
+- **Avoid binary thinking** — Technical decisions rarely have a single "right" answer. Frame as tradeoffs: "Option A is faster but harder to maintain. Option B is slower but more reliable."
+
+#### Executive Reporting
+
+- **Use BLUF (Bottom Line Up Front)** — Lead with the conclusion: "Migration is on track for Q3 launch" or "We discovered a critical security issue that delays launch by 2 weeks." Executives don't have time for preamble.
+- **Structure as Situation-Complication-Resolution** — Situation: what's the context? Complication: what's the problem or opportunity? Resolution: what are we doing about it?
+- **Report in threes** — Three key accomplishments, three blockers, three upcoming milestones. Human brains chunk information in threes. More than that, and retention drops.
+- **Surface risks early** — Executives hate surprises. If there's a 30% chance of delay, say so now. Don't wait until it's a certainty.
+- **Show trend lines, not snapshots** — Don't just report current status. Show momentum: "Test coverage increased from 60% to 75% over the past month."
+
+#### Risk Communication
+
+- **Use likelihood + impact matrix** — Classify risks as High/Medium/Low likelihood and High/Medium/Low impact. High-likelihood + High-impact risks need mitigation plans immediately.
+- **Describe risks in business terms** — "The database could fail" is technical. "If the database fails, users can't place orders, costing $X/hour in lost revenue" is business risk.
+- **Always pair risks with mitigations** — Don't just say "We might miss the deadline." Say "We might miss the deadline. To mitigate, we're cutting feature X and adding 2 engineers to the critical path."
+- **Avoid crying wolf** — Reserve "critical" for genuine emergencies. If every risk is critical, stakeholders tune out.
+
+#### Cross-Functional Alignment
+
+- **Run decision-making meetings, not information dumps** — Send status updates via email or Slack. Use synchronous meetings only for decisions that require discussion and alignment.
+- **Document decisions in real-time** — Designate a note-taker. Write down: decision made, who owns it, by when, and any open questions. Share notes immediately after the meeting.
+- **Use the RACI model** — For every decision or project, clarify: Responsible (who does the work), Accountable (who owns the outcome), Consulted (who gives input), Informed (who needs to know). Ambiguity causes dropped work and conflict.
+- **Create shared mental models** — Draw diagrams during discussions. Visuals align faster than words. Use whiteboards, Miro, or Excalidraw.
+
+#### Progress Communication
+
+- **Set expectations early** — At project kickoff, define what "done" looks like, milestones, and communication cadence. Prevents misalignment later.
+- **Use percent-complete cautiously** — Software projects are non-linear. "80% complete" often means "50% of the hardest work remains." Instead, report: completed milestones, in-progress work, and blockers.
+- **Celebrate milestones publicly** — When you ship a feature, complete a migration, or hit a quality goal, share it with the team and stakeholders. Momentum builds morale.
+- **Adjust timelines transparently** — If the deadline slips, explain why, by how much, and what's being done to prevent further slips. Hiding delays destroys trust.
+
+#### Technical Presentations
+
+- **Start with the "so what"** — First slide: what is this, why does it matter, what should the audience do with this information. Hook attention immediately.
+- **One idea per slide** — Dense slides are unreadable. One chart, one diagram, or one key point per slide. Use speaker notes for details.
+- **Demo, don't describe** — If possible, show the thing working. Live demos (with a backup video) are 10x more compelling than screenshots.
+- **End with a call to action** — What do you want stakeholders to do? Approve the proposal? Provide feedback? Assign resources? Make the ask explicit.
+
+### After stakeholder communication
+
+- **Verify understanding** — After a presentation or status update, ask: "What questions do you have?" or "Does this make sense?" Silence doesn't mean alignment; it often means confusion.
+- **Summarize in writing** — Follow up with a concise summary: key decisions, action items, owners, and deadlines. Spoken agreements fade; written agreements persist.
+- **Track communication effectiveness** — If stakeholders repeatedly ask the same questions, your communication isn't landing. Adjust format, frequency, or content.
+- **Collect feedback** — Periodically ask stakeholders: "Are my status updates helpful? Too detailed? Not detailed enough?" Course-correct before dissatisfaction builds.
+
+## Self-check before task completion
+
+- [ ] Message is tailored to the specific audience (execs, product, design, customers)
+- [ ] Communication goal is clear (inform, persuade, or align)
+- [ ] Jargon is removed or defined; analogies are used for complex concepts
+- [ ] Outcomes and business impact are emphasized over implementation details
+- [ ] Risks are quantified with likelihood + impact and paired with mitigations
+- [ ] Executive reports use BLUF (Bottom Line Up Front) and report in threes
+- [ ] Decisions are documented with RACI (Responsible, Accountable, Consulted, Informed)
+- [ ] Written follow-up summarizes key decisions, action items, and deadlines

package/.mindforge/skills/state-management/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: state-management
+version: 1.0.0
+min_mindforge_version: 0.1.0
+status: stable
+triggers: state management architecture, server state pattern, client state design, zustand store, tanstack query pattern, url state management, form state handling, optimistic update pattern, cache invalidation strategy, state machine design, global state pattern, state synchronization
+---
+
+# Skill — State Management
+
+## When this skill activates
+Any task involving state architecture decisions, choosing between state libraries,
+implementing caching strategies, designing optimistic updates, or modeling complex
+UI state flows.
+
+## Mandatory actions when this skill is active
+
+### Before writing any code
+1. Categorize the state: Is it server state, client state, URL state, or form state?
+2. Select the appropriate tool for the category (see below).
+3. Map data flow direction and identify single sources of truth.
+
+### During implementation
+- Server state (TanStack Query): define query keys, stale times, cache invalidation triggers, and prefetch points.
+- Client state (Zustand): keep stores small and focused, use selectors for render optimization.
+- URL state: encode shareable state in search params, decode with validation.
+- Form state (react-hook-form): define schema validation (Zod), handle submission lifecycle, surface errors.
+- Optimistic updates: update UI immediately, queue mutation, rollback on error with user feedback.
+
+### After implementation
+- Verify no prop drilling exists where a store or query would be cleaner.
+- Confirm cache invalidation triggers fire correctly on mutations.
+- Test offline/error scenarios for optimistic updates.
+
+## State categories and tools
+
+### Server State — TanStack Query
+- **Fetch**: `useQuery` with structured query keys (`['todos', { filter }]`).
+- **Cache**: configure `staleTime` and `gcTime` per query type.
+- **Invalidate**: `queryClient.invalidateQueries` on related mutations.
+- **Prefetch**: `queryClient.prefetchQuery` on hover/route transition.
+
+### Client State — Zustand
+- Simple global store with typed slices.
+- Use selectors (`useStore(state => state.count)`) to prevent unnecessary re-renders.
+- Persist to localStorage only when explicitly needed.
+- Avoid putting server-fetched data in Zustand — that belongs in TanStack Query.
+
+### URL State
+- Search params as state source for filters, pagination, sort.
+- Makes state shareable via URL (copy-paste, bookmarks).
+- Parse and validate on read (never trust raw URL input).
+
+### Form State — react-hook-form
+- Schema validation with Zod (`zodResolver`).
+- Handle submission states: idle, submitting, success, error.
+- Surface field-level errors immediately, form-level errors on submit.
+- Reset form state on successful submission.
+
+## Patterns
+
+### Optimistic Updates
+```typescript
+// 1. Snapshot previous state
+const previous = queryClient.getQueryData(['todos']);
+// 2. Optimistically update
+queryClient.setQueryData(['todos'], (old) => [...old, newTodo]);
+// 3. Mutate server
+try { await api.createTodo(newTodo); }
+catch {
+  // 4. Rollback on error
+  queryClient.setQueryData(['todos'], previous);
+  toast.error('Failed to create todo');
+}
+```
+
+### Cache Invalidation Strategies
+- **Stale-while-revalidate**: serve cached, refetch in background.
+- **Time-based**: `staleTime: 5 * 60 * 1000` for slowly changing data.
+- **Event-based**: invalidate on mutation success, WebSocket message, or focus.
+
+### State Machines (XState)
+Use for complex flows with defined states and transitions:
+- Auth flow (idle → authenticating → authenticated → error).
+- Multi-step forms (step1 → step2 → review → submitted).
+- Define guards for conditional transitions.
+
+## Anti-patterns to avoid
+- Prop drilling through 4+ component levels (use context or store).
+- Putting server state in global store (use TanStack Query).
+- Global store for state that only one component uses (use local state).
+- Over-memoization (`useMemo`/`useCallback` without measured need).
+- Derived state stored separately (compute it, don't sync it).
+
+## Self-check before task completion
+
+Before marking a task done when this skill was active:
+
+- [ ] Did I categorize all state correctly (server/client/URL/form)?
+- [ ] Did I select the right tool for each category?
+- [ ] Are optimistic updates properly handling rollback on error?
+- [ ] Is cache invalidation tested for mutation scenarios?
+- [ ] No prop drilling through more than 2-3 levels?
+- [ ] No server state duplicated in client stores?

package/.mindforge/skills/stream-processing/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: stream-processing
+version: 1.0.0
+min_mindforge_version: 10.6.0
+status: stable
+triggers: stream processing architecture, event streaming pattern, windowing strategy stream, exactly-once stream processing, stream state management, Kafka streaming, Flink processing, stream join pattern, late event handling, stream aggregation, watermark strategy, event time processing
+compose: streaming-architecture
+---
+
+# Skill — Stream Processing
+
+## When this skill activates
+This skill activates when designing real-time data pipelines, implementing event streaming architectures, or building low-latency aggregation systems. Use when data must be processed continuously as it arrives rather than in batch intervals.
+
+## Mandatory actions when this skill is active
+
+### Before writing any code
+1. Define processing semantics requirements: at-most-once (fast, lossy), at-least-once (duplicates possible), exactly-once (consistency critical)
+2. Select windowing strategy based on use case: tumbling (fixed non-overlapping), sliding (overlapping intervals), session (activity-based gaps)
+3. Design watermark strategy for handling late events: fixed delay, percentile-based, or custom heuristic with acceptable lateness window
+4. Establish state management approach: in-memory (fast but limited), RocksDB (scalable), remote store (shared state) with checkpointing frequency
+
+### During implementation
+- Implement event time processing using timestamps from event payload rather than processing time to handle out-of-order events correctly
+- Configure watermarks with balance between latency and completeness: too aggressive drops late events, too conservative increases latency
+- Design stateful operations with appropriate state backend and checkpointing: every 5-60 seconds based on throughput and failure recovery requirements
+- Build stream joins with care for state size: time-bounded joins, interval joins, or temporal table joins to prevent unbounded state growth
+- Implement exactly-once semantics using transactional producers, idempotent consumers, and two-phase commit when required
+- Handle late events with configurable strategy: drop and log, emit to side output, update previous window results with allowed lateness
+- Design backpressure handling: flow control to slow down producers, buffer sizing, and scaling policies for consumer parallelism
+
+### After implementation
+- Monitor stream processing lag metrics: consumer group lag, watermark delay, late events dropped, and checkpoint duration
+- Build observability dashboards: throughput (events/sec), latency percentiles (p50/p95/p99), error rates, and state size growth
+- Create alerting on critical conditions: lag exceeding SLA, checkpoint failures, repeated consumer rebalancing, state size approaching limits
+- Document failure recovery procedures: checkpoint restoration, consumer group reset, and data replay strategies
+
+## Self-check before task completion
+- [ ] Processing semantics (at-least-once or exactly-once) verified with end-to-end tests including failure injection
+- [ ] Watermark strategy handles late events appropriately with acceptable data loss or latency trade-off documented
+- [ ] State management configured with checkpointing and tested with recovery from checkpoint after failure
+- [ ] Stream joins bounded in time with monitoring for state size growth and cleanup of expired state
+- [ ] Backpressure scenarios tested with producer slowdown and consumer scaling validated under load