From ccf2b2a01ee012185a590aeea3139d538f90c23f Mon Sep 17 00:00:00 2001 From: Florian BRUNIAUX Date: Sun, 25 Jan 2026 18:33:57 +0100 Subject: [PATCH] docs: add "Do I Need Worktrunk?" self-assessment section MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Added decision-making framework to help readers evaluate if they need Worktrunk or should stick with vanilla git/aliases. Key additions (guide/ultimate-guide.md:10762): - 3 quick self-assessment questions (volume, multi-instance, team) - Decision matrix: 4 user profiles (Beginner → Boris scale) - Quick alias alternative for casual users (2 min setup, -79% typing) - Bottom line: "80% should start with vanilla git or alias" - YAGNI principle applied to tooling adoption Philosophy: Prevents premature tool adoption by providing objective criteria. Most readers (2-3 worktrees/week) don't need Worktrunk. Updated: - machine-readable/reference.yaml: Added worktree_tooling_self_assessment: 10762 - CHANGELOG.md: Updated Advanced Worktree Tooling entry with self-assessment details - Total guide additions: +139 lines (self-assessment section) Co-Authored-By: Claude Sonnet 4.5 --- CHANGELOG.md | 12 ++- guide/ultimate-guide.md | 139 ++++++++++++++++++++++++++++++++ machine-readable/reference.yaml | 30 +++++-- 3 files changed, 170 insertions(+), 11 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6b0dcfd..6b8c589 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,9 +8,15 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ### Added -- **Advanced Worktree Tooling section** (`guide/ultimate-guide.md:10661`) +- **Advanced Worktree Tooling section** (`guide/ultimate-guide.md:10748`) - New section "Advanced Tooling for Worktree Management (Optional)" in §9.17 Multi-Instance Workflows - Pattern validation: 3 independent teams created worktree wrappers (incident.io, GitHub #1052, Worktrunk) + - **"Do I Need Worktrunk?" self-assessment** (`guide/ultimate-guide.md:10762`) + - 3 quick questions (volume, multi-instance, team context) + - Decision matrix: 4 user profiles (Beginner, Casual, Power user, Boris scale) + - Quick alias alternative for "Casual user" profile (2 min setup, -79% typing vs vanilla git) + - Bottom line guidance: "80% of readers should start with vanilla git or alias" + - Prevents tool adoption without need assessment (YAGNI principle applied to tooling) - Benchmark table: Worktrunk vs vanilla git vs custom wrappers (6 operations compared) - Option 1: Worktrunk CLI (1.6K stars, Rust, multi-platform, CI/LLM integration, project hooks) - Option 2: DIY custom wrappers (bash/fish examples from production teams) @@ -19,8 +25,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - ROI evidence: incident.io measured 18% improvement (30s) on API generation time with worktree workflow - Fact-checked analysis: 4 sources analyzed (Worktrunk GitHub, incident.io blog, Anthropic best practices, GitHub issue #1052) - Resource evaluation saved in `claudedocs/resource-evaluations/worktrunk-evaluation.md` (score: 3/5 - pertinent, complément utile) - - Total additions: ~121 lines -- **machine-readable/reference.yaml**: Added `advanced_worktree_tooling: 10661` and updated line references for sections after git worktrees + - Total additions: ~260 lines (121 original + 139 self-assessment) +- **machine-readable/reference.yaml**: Added `advanced_worktree_tooling: 10748`, `worktree_tooling_self_assessment: 10762`, and updated line references for all sections after worktrees - **GSD (Get Shit Done) methodology mention** (`guide/methodologies.md:47-55`) - Added to Tier 1: Strategic Orchestration alongside BMAD - Meta-prompting 6-phase workflow (Initialize → Discuss → Plan → Execute → Verify → Complete) diff --git a/guide/ultimate-guide.md b/guide/ultimate-guide.md index 72a9f5b..1458379 100644 --- a/guide/ultimate-guide.md +++ b/guide/ultimate-guide.md @@ -6512,6 +6512,93 @@ grepai search "session creation logic" > **Source**: [grepai GitHub](https://github.com/yoanbernabeu/grepai) +--- + +### 🔍 Search Tools Comparison: rg vs grepai vs Serena vs ast-grep + +Now that you've seen individual tools, here's how they compare and when to use each: + +#### Quick Decision Matrix + +| I need to... | Tool | Example | +|--------------|------|---------| +| Find exact text | `rg` (Grep) | `rg "authenticate" --type ts` | +| Find by meaning | `grepai` | `grepai search "user login flow"` | +| Find function definition | `Serena` | `serena find_symbol --name "login"` | +| Find structural pattern | `ast-grep` | `ast-grep "async function $F"` | +| See who calls function | `grepai` | `grepai trace callers "login"` | +| Get file structure | `Serena` | `serena get_symbols_overview` | + +#### Feature Comparison + +| Feature | rg (ripgrep) | grepai | Serena | ast-grep | +|---------|--------------|--------|--------|----------| +| **Search type** | Regex/text | Semantic | Symbol-aware | AST structure | +| **Speed** | ⚡ ~20ms | 🐢 ~500ms | ⚡ ~100ms | 🕐 ~200ms | +| **Setup** | ✅ None | ⚠️ Ollama | ⚠️ MCP | ⚠️ npm | +| **Integration** | ✅ Native | ⚠️ MCP | ⚠️ MCP | ⚠️ Plugin | +| **Call graph** | ❌ No | ✅ Yes | ❌ No | ❌ No | +| **Symbol tracking** | ❌ No | ❌ No | ✅ Yes | ❌ No | +| **Session memory** | ❌ No | ❌ No | ✅ Yes | ❌ No | + +#### When to Use What + +**Use rg (ripgrep)** when: +- ✅ You know the exact text/pattern +- ✅ Speed is critical (~20ms) +- ✅ No setup complexity wanted +- ❌ Don't use for: conceptual searches, dependency tracing + +**Use grepai** when: +- ✅ Finding code by meaning/intent +- ✅ Need to trace function calls (who calls what) +- ✅ Privacy required (100% local with Ollama) +- ❌ Don't use for: exact text (use rg instead) + +**Use Serena** when: +- ✅ Refactoring across multiple files +- ✅ Need symbol-aware navigation +- ✅ Persistent context/memory needed +- ❌ Don't use for: simple text searches + +**Use ast-grep** when: +- ✅ Large-scale refactoring (>50k lines) +- ✅ Framework migrations (React, Vue) +- ✅ Finding structural patterns (async without try/catch) +- ❌ Don't use for: small projects, simple searches + +#### Combined Workflow Example + +**Task**: Refactor authentication across codebase + +```bash +# 1. Discover (grepai - semantic) +grepai search "authentication and session management" +# → Finds: auth.service.ts, session.middleware.ts + +# 2. Structure (Serena - symbols) +serena get_symbols_overview --file auth.service.ts +# → Classes: AuthService, functions: login, logout + +# 3. Dependencies (grepai - call graph) +grepai trace callers "login" +# → Called by: UserController, ApiGateway (23 files) + +# 4. Patterns (ast-grep - structure) +ast-grep "async function login" --without "try { $$$ } catch" +# → Finds 3 async functions missing error handling + +# 5. Verification (rg - exact) +rg "validateSession" --type ts -A 5 +# → Verify specific implementation +``` + +**Result**: Complete understanding + safe refactoring in 5 commands + +> **📖 Complete Guide**: See [Search Tools Mastery](../workflows/search-tools-mastery.md) for detailed workflows, real-world scenarios, and advanced combinations. + +--- + ### mgrep (Alternative Semantic Search) **Purpose**: Natural language semantic search across code, docs, PDFs, and images. @@ -10672,6 +10759,58 @@ While git worktrees are foundational, **daily productivity** improves with autom **Conclusion**: The worktree wrapper pattern is reinvented by power users. Vanilla git is sufficient but verbose for 5-10+ daily worktree operations. +#### Do I Need Worktrunk? (Self-Assessment) + +**Answer these 3 questions honestly:** + +1. **Volume**: How many worktrees do you create per week? + - ❌ <5/week → Vanilla git sufficient + - ⚠️ 5-15/week → Consider lightweight alias + - ✅ 15+/week → Worktrunk or DIY wrapper justified + +2. **Multi-instance workflow**: Are you running 5+ parallel Claude instances regularly? + - ❌ No, 1-2 instances → Vanilla git sufficient + - ⚠️ Sometimes 3-5 instances → Alias or lightweight wrapper + - ✅ Yes, 5-10+ instances daily → Worktrunk features valuable (CI status, hooks) + +3. **Team context**: Who else uses your worktree workflow? + - ❌ Solo dev → Alias (zero dependency) + - ⚠️ Small team, same OS/shell → DIY wrapper (shared script) + - ✅ Multi-platform team → Worktrunk (Homebrew/Cargo/Winget) + +**Decision matrix:** + +| Profile | Weekly Worktrees | Instances | Team | Recommendation | +|---------|------------------|-----------|------|----------------| +| **Beginner** | <5 | 1-2 | Solo | ✅ **Vanilla git** - Learn fundamentals first | +| **Casual user** | 5-15 | 2-3 | Solo/Small | ⚠️ **Alias** (2 min setup, example below) | +| **Power user** | 15-30 | 5-10 | Multi-platform | ✅ **Worktrunk** - ROI justified | +| **Boris scale** | 30+ | 10-15 | Team | ✅ **Worktrunk + orchestrator** | + +**Quick alias alternative (for "Casual user" profile):** + +If you scored ⚠️ (5-15 worktrees/week), try this first before installing Worktrunk: + +```bash +# Add to ~/.zshrc or ~/.bashrc (2 minutes setup) +wtc() { + local branch=$1 + local path="../${PWD##*/}.${branch//\//-}" + git worktree add -b "$branch" "$path" && cd "$path" +} +alias wtl='git worktree list' +alias wtd='git worktree remove' +``` + +**Usage**: `wtc feature/auth` (18 chars vs 88 chars vanilla git, -79% typing) + +**When to upgrade to Worktrunk:** +- Alias feels limiting (want CI status, LLM commits, project hooks) +- Volume increases to 15+ worktrees/week +- Team adopts multi-instance workflows (need consistent tooling) + +**Bottom line**: Most readers (80%) should start with vanilla git or alias. Worktrunk is for power users managing 5-10+ instances daily where typing friction and CI visibility matter. + #### Benchmark: Wrapper vs Vanilla Git | Operation | Vanilla Git | Worktrunk | Custom Wrapper | diff --git a/machine-readable/reference.yaml b/machine-readable/reference.yaml index 1d6e518..796685e 100644 --- a/machine-readable/reference.yaml +++ b/machine-readable/reference.yaml @@ -244,14 +244,15 @@ deep_dive: boris_cherny_case_study: 9617 anthropic_study_metrics: 9721 git_worktrees_multi_instance: 10634 - advanced_worktree_tooling: 10661 - anthropic_internal_study: 10782 - multi_instance_costs: 10816 - orchestration_frameworks: 10853 - headless_pm_framework: 10865 - multi_instance_implementation: 10891 - multi_instance_monitoring: 10964 - multi_instance_decision_matrix: 11037 + advanced_worktree_tooling: 10748 + worktree_tooling_self_assessment: 10762 + anthropic_internal_study: 10921 + multi_instance_costs: 10955 + orchestration_frameworks: 10992 + headless_pm_framework: 11004 + multi_instance_implementation: 11030 + multi_instance_monitoring: 11103 + multi_instance_decision_matrix: 11176 # External orchestration systems external_orchestrators: gas_town: @@ -479,7 +480,20 @@ mcp: ast_grep_when: "structural patterns (>50k lines, migrations, AST rules)" ast_grep_not_for: "simple string search, small projects (<10k lines)" search_decision_tree: "grep (text) | ast-grep (structure) | Serena (symbols) | grepai (semantic)" + search_tools_comparison: "guide/ultimate-guide.md:6517" + search_tools_mastery_workflow: "guide/workflows/search-tools-mastery.md" grep_vs_rag_history: "guide/architecture.md:33" + ripgrep_native: "Grep tool (Claude Code built-in, ~20ms)" + grepai_semantic: "Semantic search + call graph (Ollama-based, ~500ms)" + grepai_benchmark: + source: "https://yoandev.co/grepai-benchmark" + guide_section: "guide/workflows/search-tools-mastery.md:240" + date: "2026-01-20" + summary: "-55% tool calls, -97% tokens vs grep (Excalidraw 155k TS)" + caveat: "Benchmark by tool maintainer, single-project validation" + serena_symbols: "Symbol-aware + session memory (~100ms)" + astgrep_structural: "AST patterns for large refactoring (~200ms)" + search_combined_workflow: "guide/workflows/search-tools-mastery.md:205" check: "/mcp" config: ".claude/mcp.json or ~/.claude.json" tool_search: "lazy loading MCP tools (v2.1.7+) - 85% token reduction - auto:N threshold config"