minimal-vibe-coding-kit 0.5.0 → 0.5.2

package/.vibekit/skills/sequential-thinking/examples/branching-exploration.md

@@ -1,474 +1,24 @@
-# Branching Exploration - Example
+# Branching Exploration Example
 
-## Scenario: State Management Library Selection
+## Case: Maintain Imported Syntax Documentation
 
-**Problem:** Choose state management solution for large React application
+The kit needs complete Mermaid syntax coverage without pretending upstream documentation is kit-authored.
 
-**Pattern:** Branching Exploration (multiple valid approaches to compare)
+~~~text
+Thought 1/7: Choose how to maintain syntax references.
+Thought 2/7 [BRANCH rewrite-all from Thought 1]: Rewrite every page locally; strongest voice consistency, highest drift and maintenance cost.
+Thought 3/7 [BRANCH snapshot-plus-overlay from Thought 1]: Keep pinned upstream snapshots and add kit-authored workflow, style, safety, and examples.
+Thought 4/7 [VERIFICATION]: Most imported pages are verbatim Mermaid documentation, while the kit behavior lives in a small overlay.
+Thought 5/7 [CONVERGENCE]: Use snapshot-plus-overlay with a third-party notice and pinned source links.
+Thought 6/7 [VERIFICATION]: Operational links resolve locally, upstream ownership is explicit, and the package includes the notice.
+Thought 7/7 [FINAL]: Keep the hybrid structure and validate provenance plus link integrity.
+~~~
 
-**Structure:** Main analysis → 3 branches → Synthesis → Decision
+## Comparison
 
-**Total thoughts:** 12
+| Option | Strength | Cost |
+| --- | --- | --- |
+| rewrite-all | unified wording | likely syntax drift and large maintenance burden |
+| snapshot-plus-overlay | faithful syntax plus clear kit behavior | requires provenance and link boundaries |
 
----
-
-## Main Chain
-
-### Thought 1: Problem Definition
-
-**Input:**
-```bash
-/sequential-thinking "Problem: Need to choose state management for large React app (50+ components, complex data flow). Requirements: 1) Scalable, 2) Good DevTools, 3) Easy to learn for team, 4) TypeScript support. Options: Redux, MobX, Zustand, Recoil." thoughtNumber=1 totalThoughts=12 nextThoughtNeeded=true
-```
-
-**Output:**
-```json
-{
-  "thoughtNumber": 1,
-  "thoughtContent": "Problem: Need to choose state management for large React app (50+ components, complex data flow). Requirements: 1) Scalable, 2) Good DevTools, 3) Easy to learn for team, 4) TypeScript support. Options: Redux, MobX, Zustand, Recoil.",
-  "totalThoughts": 12,
-  "nextThoughtNeeded": true,
-  "branches": [],
-  "thoughtHistoryLength": 1,
-  "sessionContext": {
-    "sessionId": "conversation",
-    "remainingThoughts": 99
-  }
-}
-```
-
----
-
-### Thought 2: Evaluation Criteria
-
-**Input:**
-```bash
-/sequential-thinking "Evaluation criteria defined: 1) Performance (re-renders), 2) Boilerplate amount, 3) Learning curve (team has 2 weeks), 4) Ecosystem/plugins, 5) Long-term maintainability. Will explore top 3 options: Redux, Zustand, Recoil." thoughtNumber=2 totalThoughts=12 nextThoughtNeeded=true
-```
-
-**Output:**
-```json
-{
-  "thoughtNumber": 2,
-  "thoughtContent": "Evaluation criteria defined: 1) Performance (re-renders), 2) Boilerplate amount, 3) Learning curve (team has 2 weeks), 4) Ecosystem/plugins, 5) Long-term maintainability. Will explore top 3 options: Redux, Zustand, Recoil.",
-  "totalThoughts": 12,
-  "nextThoughtNeeded": true,
-  "branches": [],
-  "thoughtHistoryLength": 2,
-  "sessionContext": {
-    "sessionId": "conversation",
-    "remainingThoughts": 98
-  }
-}
-```
-
----
-
-## Branch A: Redux
-
-### Thought 3: Redux Overview
-
-**Input:**
-```bash
-/sequential-thinking "BRANCH A - Redux: Industry standard, used by 50%+ large apps. Pros: Predictable state, excellent DevTools, huge ecosystem, Redux Toolkit reduces boilerplate. Perfect TypeScript support." thoughtNumber=3 totalThoughts=12 nextThoughtNeeded=true branchFromThought=2 branchId="redux"
-```
-
-**Output:**
-```json
-{
-  "thoughtNumber": 3,
-  "thoughtContent": "BRANCH A - Redux: Industry standard, used by 50%+ large apps. Pros: Predictable state, excellent DevTools, huge ecosystem, Redux Toolkit reduces boilerplate. Perfect TypeScript support.",
-  "totalThoughts": 12,
-  "nextThoughtNeeded": true,
-  "branches": ["redux"],
-  "thoughtHistoryLength": 3,
-  "branchInfo": {
-    "id": "redux",
-    "fromThought": 2
-  },
-  "sessionContext": {
-    "sessionId": "conversation",
-    "remainingThoughts": 97
-  }
-}
-```
-
----
-
-### Thought 4: Redux Trade-offs
-
-**Input:**
-```bash
-/sequential-thinking "BRANCH A continued - Redux downsides: Steeper learning curve (actions, reducers, selectors), more boilerplate even with RTK, team needs 2 weeks training. Architectural overhead for simple use cases. Performance good with proper memoization (reselect)." thoughtNumber=4 totalThoughts=12 nextThoughtNeeded=true branchFromThought=2 branchId="redux"
-```
-
-**Output:**
-```json
-{
-  "thoughtNumber": 4,
-  "thoughtContent": "BRANCH A continued - Redux downsides: Steeper learning curve (actions, reducers, selectors), more boilerplate even with RTK, team needs 2 weeks training. Architectural overhead for simple use cases. Performance good with proper memoization (reselect).",
-  "totalThoughts": 12,
-  "nextThoughtNeeded": true,
-  "branches": ["redux"],
-  "thoughtHistoryLength": 4,
-  "branchInfo": {
-    "id": "redux",
-    "fromThought": 2
-  },
-  "sessionContext": {
-    "sessionId": "conversation",
-    "remainingThoughts": 96
-  }
-}
-```
-
----
-
-## Branch B: Zustand
-
-### Thought 5: Zustand Overview
-
-**Input:**
-```bash
-/sequential-thinking "BRANCH B - Zustand: Minimalist alternative, 1KB size. Pros: Extremely simple API (create store, use hook), no boilerplate, easy to learn (30min tutorial). Good TypeScript support, selector-based rendering optimization." thoughtNumber=5 totalThoughts=12 nextThoughtNeeded=true branchFromThought=2 branchId="zustand"
-```
-
-**Output:**
-```json
-{
-  "thoughtNumber": 5,
-  "thoughtContent": "BRANCH B - Zustand: Minimalist alternative, 1KB size. Pros: Extremely simple API (create store, use hook), no boilerplate, easy to learn (30min tutorial). Good TypeScript support, selector-based rendering optimization.",
-  "totalThoughts": 12,
-  "nextThoughtNeeded": true,
-  "branches": ["redux", "zustand"],
-  "thoughtHistoryLength": 5,
-  "branchInfo": {
-    "id": "zustand",
-    "fromThought": 2
-  },
-  "sessionContext": {
-    "sessionId": "conversation",
-    "remainingThoughts": 95
-  }
-}
-```
-
----
-
-### Thought 6: Zustand Trade-offs
-
-**Input:**
-```bash
-/sequential-thinking "BRANCH B continued - Zustand downsides: Smaller ecosystem (fewer plugins), no official DevTools (community tools exist), less architectural guidance (more freedom = more decisions). Not as battle-tested as Redux in large scale apps. Less hiring pool with Zustand experience." thoughtNumber=6 totalThoughts=12 nextThoughtNeeded=true branchFromThought=2 branchId="zustand"
-```
-
-**Output:**
-```json
-{
-  "thoughtNumber": 6,
-  "thoughtContent": "BRANCH B continued - Zustand downsides: Smaller ecosystem (fewer plugins), no official DevTools (community tools exist), less architectural guidance (more freedom = more decisions). Not as battle-tested as Redux in large scale apps. Less hiring pool with Zustand experience.",
-  "totalThoughts": 12,
-  "nextThoughtNeeded": true,
-  "branches": ["redux", "zustand"],
-  "thoughtHistoryLength": 6,
-  "branchInfo": {
-    "id": "zustand",
-    "fromThought": 2
-  },
-  "sessionContext": {
-    "sessionId": "conversation",
-    "remainingThoughts": 94
-  }
-}
-```
-
----
-
-## Branch C: Recoil
-
-### Thought 7: Recoil Overview
-
-**Input:**
-```bash
-/sequential-thinking "BRANCH C - Recoil: Facebook's experimental library. Pros: Atom-based (fine-grained reactivity), built-in async support, React-like API (hooks), excellent performance with minimal re-renders. TypeScript support good." thoughtNumber=7 totalThoughts=12 nextThoughtNeeded=true branchFromThought=2 branchId="recoil"
-```
-
-**Output:**
-```json
-{
-  "thoughtNumber": 7,
-  "thoughtContent": "BRANCH C - Recoil: Facebook's experimental library. Pros: Atom-based (fine-grained reactivity), built-in async support, React-like API (hooks), excellent performance with minimal re-renders. TypeScript support good.",
-  "totalThoughts": 12,
-  "nextThoughtNeeded": true,
-  "branches": ["redux", "zustand", "recoil"],
-  "thoughtHistoryLength": 7,
-  "branchInfo": {
-    "id": "recoil",
-    "fromThought": 2
-  },
-  "sessionContext": {
-    "sessionId": "conversation",
-    "remainingThoughts": 93
-  }
-}
-```
-
----
-
-### Thought 8: Recoil Trade-offs
-
-**Input:**
-```bash
-/sequential-thinking "BRANCH C continued - Recoil downsides: Still experimental (0.7.x), API changes possible, smaller community, fewer resources/tutorials. Not recommended for production by Meta yet. DevTools exist but less mature than Redux. Hiring challenge." thoughtNumber=8 totalThoughts=12 nextThoughtNeeded=true branchFromThought=2 branchId="recoil"
-```
-
-**Output:**
-```json
-{
-  "thoughtNumber": 8,
-  "thoughtContent": "BRANCH C continued - Recoil downsides: Still experimental (0.7.x), API changes possible, smaller community, fewer resources/tutorials. Not recommended for production by Meta yet. DevTools exist but less mature than Redux. Hiring challenge.",
-  "totalThoughts": 12,
-  "nextThoughtNeeded": true,
-  "branches": ["redux", "zustand", "recoil"],
-  "thoughtHistoryLength": 8,
-  "branchInfo": {
-    "id": "recoil",
-    "fromThought": 2
-  },
-  "sessionContext": {
-    "sessionId": "conversation",
-    "remainingThoughts": 92
-  }
-}
-```
-
----
-
-## Synthesis & Decision
-
-### Thought 9: Comparison Matrix
-
-**Input:**
-```bash
-/sequential-thinking "Comparison across branches: Performance (Recoil > Zustand > Redux), Learning curve (Zustand > Recoil > Redux), Ecosystem (Redux >> Zustand > Recoil), Production readiness (Redux >> Zustand > Recoil), Team ramp-up time: Zustand=2 days, Recoil=5 days, Redux=14 days." thoughtNumber=9 totalThoughts=12 nextThoughtNeeded=true
-```
-
-**Output:**
-```json
-{
-  "thoughtNumber": 9,
-  "thoughtContent": "Comparison across branches: Performance (Recoil > Zustand > Redux), Learning curve (Zustand > Recoil > Redux), Ecosystem (Redux >> Zustand > Recoil), Production readiness (Redux >> Zustand > Recoil), Team ramp-up time: Zustand=2 days, Recoil=5 days, Redux=14 days.",
-  "totalThoughts": 12,
-  "nextThoughtNeeded": true,
-  "branches": ["redux", "zustand", "recoil"],
-  "thoughtHistoryLength": 9,
-  "sessionContext": {
-    "sessionId": "conversation",
-    "remainingThoughts": 91
-  }
-}
-```
-
----
-
-### Thought 10: Context-Specific Analysis
-
-**Input:**
-```bash
-/sequential-thinking "Analyzing for OUR context: We have 2-week deadline, team is mid-level React devs (not state management experts), need production stability, have 50+ components. Redux's learning curve is a blocker. Recoil's experimental status is risky. Zustand fits timeline and stability needs." thoughtNumber=10 totalThoughts=12 nextThoughtNeeded=true
-```
-
-**Output:**
-```json
-{
-  "thoughtNumber": 10,
-  "thoughtContent": "Analyzing for OUR context: We have 2-week deadline, team is mid-level React devs (not state management experts), need production stability, have 50+ components. Redux's learning curve is a blocker. Recoil's experimental status is risky. Zustand fits timeline and stability needs.",
-  "totalThoughts": 12,
-  "nextThoughtNeeded": true,
-  "branches": ["redux", "zustand", "recoil"],
-  "thoughtHistoryLength": 10,
-  "sessionContext": {
-    "sessionId": "conversation",
-    "remainingThoughts": 90
-  }
-}
-```
-
----
-
-### Thought 11: Decision
-
-**Input:**
-```bash
-/sequential-thinking "DECISION: Choose Zustand. Rationale: 1) Meets 2-week learning timeline, 2) Production-ready and stable, 3) Sufficient ecosystem for our needs, 4) Can add Redux DevTools plugin if needed, 5) Easy hiring/onboarding later. Trade-off accepted: Less architectural guidance (we'll create our own patterns)." thoughtNumber=11 totalThoughts=12 nextThoughtNeeded=true
-```
-
-**Output:**
-```json
-{
-  "thoughtNumber": 11,
-  "thoughtContent": "DECISION: Choose Zustand. Rationale: 1) Meets 2-week learning timeline, 2) Production-ready and stable, 3) Sufficient ecosystem for our needs, 4) Can add Redux DevTools plugin if needed, 5) Easy hiring/onboarding later. Trade-off accepted: Less architectural guidance (we'll create our own patterns).",
-  "totalThoughts": 12,
-  "nextThoughtNeeded": true,
-  "branches": ["redux", "zustand", "recoil"],
-  "thoughtHistoryLength": 11,
-  "sessionContext": {
-    "sessionId": "conversation",
-    "remainingThoughts": 89
-  }
-}
-```
-
----
-
-### Thought 12: Implementation Plan
-
-**Input:**
-```bash
-/sequential-thinking "Implementation plan: Week 1: Team reads Zustand docs (2 hours), create initial stores for auth & user data, establish patterns (slices, middleware). Week 2: Migrate existing Context API to Zustand, add DevTools plugin, document patterns. Fallback: If Zustand doesn't scale, Redux migration is straightforward. Analysis complete." thoughtNumber=12 totalThoughts=12 nextThoughtNeeded=false
-```
-
-**Output:**
-```json
-{
-  "thoughtNumber": 12,
-  "thoughtContent": "Implementation plan: Week 1: Team reads Zustand docs (2 hours), create initial stores for auth & user data, establish patterns (slices, middleware). Week 2: Migrate existing Context API to Zustand, add DevTools plugin, document patterns. Fallback: If Zustand doesn't scale, Redux migration is straightforward. Analysis complete.",
-  "totalThoughts": 12,
-  "nextThoughtNeeded": false,
-  "branches": ["redux", "zustand", "recoil"],
-  "thoughtHistoryLength": 12,
-  "status": "complete",
-  "sessionContext": {
-    "sessionId": "conversation",
-    "remainingThoughts": 88,
-    "branchesExplored": 3
-  }
-}
-```
-
----
-
-## Branch Visualization
-
-```
-Thought 1: Problem definition
-  ↓
-Thought 2: Criteria (branch point)
-  ├─→ BRANCH A: Redux (#3, #4)
-  │   ├─ Overview: Industry standard, ecosystem
-  │   └─ Trade-offs: Learning curve, boilerplate
-  │
-  ├─→ BRANCH B: Zustand (#5, #6)
-  │   ├─ Overview: Simple, fast learning
-  │   └─ Trade-offs: Smaller ecosystem, less guidance
-  │
-  └─→ BRANCH C: Recoil (#7, #8)
-      ├─ Overview: Fine-grained, async support
-      └─ Trade-offs: Experimental, risky
-  ↓
-Thought 9: Comparison matrix
-  ↓
-Thought 10: Context analysis
-  ↓
-Thought 11: DECISION → Zustand
-  ↓
-Thought 12: Implementation plan
-```
-
----
-
-## Analysis
-
-### Branch Summary
-
-| Branch | Thoughts | Key Strengths | Key Weaknesses |
-|--------|----------|---------------|----------------|
-| **Redux** | 2 (#3-4) | Ecosystem, production-proven | Learning curve, boilerplate |
-| **Zustand** | 2 (#5-6) | Simple, fast learning | Less ecosystem, guidance |
-| **Recoil** | 2 (#7-8) | Performance, fine-grained | Experimental, risky |
-
-### Decision Factors
-
-**Winner:** Zustand
-
-**Why Zustand won:**
-1. ✅ 2-day learning (vs 14 days for Redux)
-2. ✅ Production-ready (vs experimental Recoil)
-3. ✅ Sufficient for 50 components
-4. ✅ Easy team onboarding
-5. ✅ Migration path to Redux exists if needed
-
-**Why others lost:**
-- **Redux:** 2-week deadline incompatible with 14-day learning curve
-- **Recoil:** Experimental status too risky for production
-
-### Pattern Effectiveness
-
-✅ **Systematic comparison** across all options  
-✅ **Objective evaluation** against criteria  
-✅ **Context-specific** decision (not just "best" in general)  
-✅ **Clear rationale** documented  
-✅ **Fallback plan** included  
-
----
-
-## When to Use Branching Pattern
-
-### ✅ Use When:
-- Multiple valid approaches exist
-- Trade-offs between options
-- Need to compare systematically
-- Stakeholders need rationale
-- No obviously "correct" choice
-
-### ❌ Don't Use When:
-- One clear solution exists
-- Time-constrained (branching takes longer)
-- Options not comparable (apples vs oranges)
-- Decision already made (just need validation)
-
----
-
-## Branching Best Practices
-
-### Do:
-- ✅ Explore each branch fairly (similar depth)
-- ✅ Use consistent evaluation criteria
-- ✅ Create synthesis thought (compare branches)
-- ✅ Document decision rationale clearly
-- ✅ Include fallback/migration paths
-
-### Don't:
-- ❌ Leave branches unexplored (orphan branches)
-- ❌ Bias toward one branch unfairly
-- ❌ Skip synthesis (just pick one)
-- ❌ Forget context-specific factors
-- ❌ Ignore trade-offs
-
----
-
-## Comparison with Other Patterns
-
-| Pattern | Thoughts | Branches | Revisions | Best For |
-|---------|----------|----------|-----------|----------|
-| Linear | 6 | 0 | 0 | Clear solution |
-| Revision | 8 | 0 | 2 | Wrong assumptions |
-| **Branching** | **12** | **3** | **0** | **Multiple options** |
-| Adaptive | 5-20 | 0-2 | 0-1 | Unclear scope |
-
----
-
-## Key Takeaways
-
-1. **Branching enables systematic comparison** - Evaluate all options fairly
-2. **Synthesis is critical** - Don't just explore, compare and decide
-3. **Context matters** - Best option depends on specific requirements
-4. **Document rationale** - Future you (and team) will thank you
-5. **Plan fallbacks** - Acknowledge risk and have backup plan
-
----
-
-**For other patterns:**
-- [linear-reasoning.md](linear-reasoning.md) - Straightforward analysis
-- [revision-pattern.md](revision-pattern.md) - Correcting assumptions
-- [adaptive-depth.md](adaptive-depth.md) - Uncertain scope
+CONVERGENCE closes both branches with repository evidence rather than preference alone.