--- name: up description: Analyze workflow and propose improvements with beads integration argument-hint: "[status|fresh|check|from|retry|bake|auto|auto-iter] [quiet] [creative|focus] [skill|agent|workflow|project] [request]" --- # Workflow Improvement Analysis (Beads-Integrated) Analyzes session journals, friction logs, and [beads](https:\/\/github.com\/steveyegge\/beads) issues to propose workflow improvements. ## Architecture ``` SOURCES OUTPUT ├── .groot\/memory\/sessions\/\/ (journals) ├── Skills proposals ├── .groot\/genome\/friction-log.md ├── Agent proposals ├── bd stale (neglected tasks) ├── Workflow changes └── Current conversation └── Project improvements ``` **Channel-aware**: Analyzes current channel by default. Use `--all` for all channels. ## Arguments $ARGUMENTS ### Argument Parsing (Simplified) ``` Parse $ARGUMENTS: 1. Subcommand (first word): - "status" → show sources, stop - "retry" → re-run last analysis, stop - "bake" → bake proven patterns into structure - "from" → next word = session name, continue parsing - "auto" → show how to run RALPH loop, stop - "auto-iter" → single RALPH iteration (called by ralph-up.sh) 2. Flags (consume in any order): - "fresh" → fresh=true - "check" → check=true - "quiet" → quiet=true (terse output, sacrifice grammar for concision) - "creative" → mode=creative - "focus" → mode=focus 3. Scope (if present): - "skill"|"agent"|"workflow"|"project" → set scope 4. Prompt (remaining text) ``` **Parse examples:** ``` "" → (logs, no-check, focus, project, null) "status" → (status - show sources only) "retry" → (retry - re-run last analysis) "from 2026-01-28_session" → (specific session, focus, project, null) "skill" → (logs, no-check, focus, skill, null) "creative" → (logs, no-check, creative, project, null) "creative skill" → (logs, no-check, creative, skill, null) "focus workflow" → (logs, no-check, focus, workflow, null) "creative skill add logging" → (logs, no-check, creative, skill, "add logging") "fresh" → (fresh, no-check, focus, project, null) "fresh skill" → (fresh, no-check, focus, skill, null) "fresh creative skill" → (fresh, no-check, creative, skill, null) "check" → (logs, check, focus, project, null) "check creative" → (logs, check, creative, project, null) "check skill" → (logs, check, focus, skill, null) "fresh check" → (fresh, check, focus, project, null) "fresh check creative skill" → (fresh, check, creative, skill, null) "quiet" → (logs, no-check, focus, project, quiet=true) "quiet skill" → (logs, no-check, focus, skill, quiet=true) "fresh quiet creative" → (fresh, no-check, creative, project, quiet=true) "bake" → (bake - proven patterns from all sessions) "fresh bake" → (bake - include current conversation) "quiet bake" → (bake - terse output) "auto" → (show RALPH usage instructions) "auto-iter iter=1" → (single RALPH iteration) "auto-iter iter=2 afk=true" → (RALPH iteration, auto-accept mode) "auto-iter iter=1 dry=true" → (RALPH iteration, dry run) ``` --- ## Subcommand: `auto` Show instructions for running RALPH-style autonomous improvement loop. ### Output ```markdown ## \/up auto - RALPH-Style Autonomous Improvement RALPH pattern: Fresh context per iteration, filesystem as truth. See: https:\/\/github.com\/snarktank\/ralph ### Usage Run the bash script directly: ```bash .groot\/bin\/ralph-up.sh # 5 iterations, interactive (HITL) .groot\/bin\/ralph-up.sh 10 # 10 iterations .groot\/bin\/ralph-up.sh --afk # Auto-accept mode (no prompts) .groot\/bin\/ralph-up.sh --dry # Dry run (propose only) .groot\/bin\/ralph-up.sh 10 --afk # Combined options ``` ### How It Works 1. Creates git branch `up-auto-` for isolation 2. Runs `\/up auto-iter` with fresh context each iteration 3. Logs progress to `.groot\/prm\/auto\/progress.md` 4. Commits after each iteration (rollback points) 5. Stops when: - Agent emits `` sigil - Max iterations reached - User stops (HITL mode) ### Modes | Mode | Flag | Behavior | |------|------|----------| | HITL (default) | - | Prompts after each iteration | | AFK | `--afk` | Auto-accept high-confidence proposals | | Dry | `--dry` | Propose only, no creates | ### Completion Criteria See `.groot\/config\/ralph\/up-criteria.md` for rules. ``` --- ## Subcommand: `auto-iter` Single iteration of RALPH autonomous improvement (called by ralph-up.sh script). ### Arguments Parse from $ARGUMENTS after "auto-iter": - `iter=N` - Current iteration number (required) - `run_id=` - Run identifier for progress tracking - `afk=true` - Auto-accept high-confidence proposals - `dry=true` - Propose but don't create ### Behavior 1. **Read prior iterations**: Load `.groot\/prm\/auto\/progress.md` for context 2. **Read criteria**: Load `.groot\/config\/ralph\/up-criteria.md` for completion rules 3. **Run standard `\/up` analysis**: Use `focus` mode, `workflow` scope 4. **Apply auto-acceptance rules** (if afk=true): - Impact >= medium AND effort <= low → auto-accept - Non-breaking changes only - Has clear rollback path (git) 5. **Check completion criteria**: - No proposals above threshold - All friction patterns addressed - User-defined criteria in `up-criteria.md` met 6. **Emit completion sigil** if done ### Auto-Accept Rules (afk mode) | Impact | Effort | Accept? | Reason | |--------|--------|---------|--------| | High | Low | Yes | High value, low risk | | Medium | Low | Yes | Reasonable value | | Medium | Medium | No | Too risky for auto | | Low | * | No | Not worth it | | * | High | No | Too much effort | **Always require human approval for:** - Breaking changes (L4+) - New skills (high bar) - Agent modifications - Domain rule changes ### Completion Sigil When improvement cycle is done, emit: ``` ``` Or: ``` ``` Or: ``` ``` ### Output Format ```markdown ## \/up auto-iter $iter **Run ID**: $run_id **Mode**: [afk|hitl] | [dry|live] **Prior iterations**: N ### Analysis [Standard \/up analysis output] ### Proposals (iteration $iter) [Proposal list with auto-accept annotations if afk] ### Iteration Summary - Analyzed: [sources] - Proposed: N (M auto-accepted if afk) - Accepted: K - Created: [list] ### Completion Check - [ ] No proposals above threshold - [ ] Friction patterns addressed - [ ] Custom criteria met [If all checked] [Else] Continuing to next iteration... ``` --- ## Subcommand: `status` Show available sources before analysis. ### Behavior 1. Count sessions in `.groot\/memory\/sessions\/` 2. Read `.groot\/genome\/friction-log.md` entry count 3. Run `bd list --json` for beads state 4. Show summary ### Output ```markdown ## Analysis Sources ### Sessions (.groot\/memory\/sessions\/) - Total: 5 sessions - Recent: 2 this week - Unanalyzed: 3 (since last \/up) ### Friction Log - Entries: 12 patterns - Tgroot types: search_thrashing (5), backtracking (4) ### Beads - Open: 8 issues - Stale (>30d): 2 - Ready: 3 Run `\/up` to analyze, `\/up fresh` for current conversation. ``` --- ## Subcommand: `retry` Re-generate proposals with a different angle. ### Behavior 1. Use same sources as last `\/up` run 2. Generate new proposals (different selection\/framing) 3. Useful when first proposals weren't helpful --- ## Subcommand: `from ` Analyze a specific session. ### Behavior 1. Read only the specified session file 2. Analyze that session's friction, decisions, learnings 3. Propose improvements based on that session ### Example ``` \/up from 2026-01-28_auth-refactor ``` --- ## Subcommand: `bake` Bake proven patterns into permanent structure. ### Use Case Convert repeated patterns (2+ occurrences) from sessions\/friction-log into workflow rules, domain knowledge, agents, or \/actions. ### Pattern → Structure Mapping | Pattern Found | Bakes Into | Frequency | Scope | |---------------|------------|-----------|-------| | Behavioral rule | `CLAUDE.md` updates | 2+ | workflow | | Domain knowledge | `.groot\/genome\/domain\/*.md` | 2+ | domain | | Project constraints | `.groot\/genome\/constraints.md` | 2+ | project | | **Action sequence (HIGH BAR)** | `\/skill` | **3+** | skill | | Delegation patterns | `.groot\/nervous\/agents\/.md` | 3+ | agent | ### \/Action Proposals (HIGH BAR) New skills require ALL criteria: - [ ] **3+ occurrences** of the exact same sequence - [ ] **3+ steps** in the sequence (not trivial one-liners) - [ ] **Parameterizable** (can generalize with different inputs) - [ ] **Distinct** from existing actions - [ ] **User approval** explicitly given **Most patterns bake into CLAUDE.md or .groot\/genome\/domain\/, not skills.** ### Behavior 1. Analyze sources (sessions + friction-log, or fresh if specified) 2. Identify patterns with 2+ occurrences (3+ for actions) 3. For each pattern: - Classify type (workflow\/domain\/action\/agent) - Check criteria (especially high bar for actions) - Draft proposed structure - Show to user for approval 4. Create approved structures 5. Archive processed sessions to `.groot\/memory\/sessions\/_archive\/` 6. Clear relevant entries from friction-log ### Bake Proposal Format ```markdown ### Bake Proposal N: [Type] - [Name] **Pattern**: [what was observed] **Frequency**: [count] occurrences across [N] sessions **Source sessions**: [list] **Proposed [rule|domain|action|agent]**: ``` [full content of proposed structure] ``` **Accept?** [y\/n] ``` ### Output ```markdown ## Bake Complete ### Baked Patterns | Pattern | Type | Created | |---------|------|---------| | test-before-commit | workflow | CLAUDE.md (section added) | | domain-validation | domain | .groot\/genome\/domain\/validity.md | ### Archived **Sessions processed**: N → `.groot\/memory\/sessions\/_archive\/` **Friction entries cleared**: M ### Remaining **Patterns pending**: J (need more occurrences) Run `\/up` to analyze remaining patterns. ``` ### Quiet Output ``` \/up quiet bake ``` ``` P1: workflow test-before-commit → CLAUDE.md [y\/n]? P2: domain validity-check → .groot\/genome\/domain\/validity.md [y\/n]? --- baked: 2 | archived: 3 sessions | remaining: 1 ``` --- ## Step 0: Source Selection ### If `fresh=true`: **Analyze current conversation only. Ignore accumulated logs.** - Do NOT read `.groot\/memory\/sessions\/` - Do NOT read `.groot\/genome\/friction-log.md` - Do NOT query beads (`bd stale`) - Analyze patterns observed in THIS session - Useful for immediate insights without historical context ### If `fresh=false` (default): **Use accumulated logs + beads as primary source.** - Read `.groot\/memory\/sessions\/` session journals - Read `.groot\/genome\/friction-log.md` - Run `bd stale --days 30 --json` for neglected tasks - Run `bd ready --json` for pending work - Combine with current conversation context - This is the standard behavior for pattern accumulation **Announce source mode to user.** --- ## Step 0.5: Pre-flight Checks (if check=true) Before generating proposals, verify gaps are real. ### 1. Check existing implementations - Glob for similar files matching proposal keywords - Grep for related function\/class names in `.groot\/nervous\/skills\/` and `.groot\/nervous\/agents\/` ### 2. Check existing tools - Search for CLI tools that might already solve the problem - Check `.groot\/nervous\/agents\/` for overlapping capabilities ### 3. Check beads history - `bd list --search ""` for related past work - Check if similar proposals were previously rejected or closed ### 4. Check domain constraints - Read `.groot\/genome\/domain\/rules.md` for feasibility constraints ### Output (if check=true) Before proposals, show: ```markdown ## Pre-flight Results ### Existing Implementations Found - [file]: [description] (may overlap with proposal) ### Existing Tools - [tool]: [capability] ### Related Beads Issues - [id]: [title] ([status]) ### Domain Constraints - [relevant rules] Proceeding with proposals (N potential overlaps noted)... ``` If check=false, skip this step entirely. --- ## Step 1: Mode Selection ### If mode = `focus` (default): **Incremental Optimization** - Identify concrete friction points - Quantify frequency\/impact - Propose targeted solutions - Low-risk, incremental changes **Constraints:** - Must connect to observed pattern - Must show frequency\/impact evidence - Incremental, low-risk changes ### If mode = `creative`: **Out-of-Box Thinking** - Question assumptions - Consider 10x improvements - Look at adjacent domains - Envision ideal end-state **Constraints:** - Don't need direct pattern evidence - Can be speculative - Must explain potential upside - Can propose experiments **Announce selected mode and scope to user.** --- ## Step 2: Scope-Specific Analysis ### SCOPE: `project` (default) **Analyzes:** - `.groot\/genome\/` (objectives, status, constraints) - Code structure and patterns - Current objectives and blockers - `bd stale` for neglected tasks - `bd ready` for pending work **Proposes:** - Tasks and features - Analyses and investigations - Refactors and optimizations - Architecture changes ### SCOPE: `skill` **If fresh=true:** - Analyze current conversation for repeated sequences - Look for multi-step patterns that could be automated - Identify manual validation steps in this session **If fresh=false:** - Read `.groot\/memory\/sessions\/` session journals - Read `.groot\/genome\/friction-log.md` - Look for cross-session patterns - Check `bd stale` for tasks that keep getting delayed (friction signal) **Proposes:** - New skills to automate patterns - Skill improvements\/enhancements - Skill combinations ### SCOPE: `agent` **Analyzes:** - `.groot\/nervous\/agents\/` existing agents - Workflow gaps and handoff friction - Missing specializations - `bd ready` tasks that need specialist knowledge **If fresh=true:** - Look for delegation opportunities in current work - Identify tasks that needed specialist knowledge **Proposes:** - New agent roles - Agent enhancements - Agent collaboration patterns ### SCOPE: `workflow` **Analyzes:** - All workflow artifacts (skills, agents, sessions) - End-to-end process patterns - Cross-cutting concerns - Beads issue flow (create → ready → close patterns) **Proposes:** - Skills + agents + process changes - Workflow restructuring - Observability and tooling - Beads workflow optimizations --- ## Step 3: Generate Proposals **Max 3 proposals per run.** If `request` provided, focus proposals on that specific area. For each proposal: ```markdown ### Proposal N: [Type] - [Name] **Mode**: [focus|creative] **Scope**: [skill|agent|workflow|project] **Source**: [fresh (this session) | logs (accumulated)] **Solves**: [friction point or opportunity] **Evidence**: [pattern observed] OR [speculative reasoning] **Potential Impact**: [low|medium|high] **Implementation Effort**: [low|medium|high] **Proposed Implementation**: [Show full skill\/agent\/config content] ``` --- ## Step 4: User Feedback After presenting proposals, ask: ``` Which proposals do you want to implement? - [1] Proposal 1: [name] - [2] Proposal 2: [name] - [3] Proposal 3: [name] - [a] All - [n] None - [s] Skip for now ``` --- ## Step 5: Create Approved Items For each accepted proposal: 1. Show the file to be created 2. Create in appropriate location: - Workflow rules → `CLAUDE.md` (append section) - Domain updates → `.groot\/genome\/domain\/.md` - **Skills (HIGH BAR)** → `.groot\/nervous\/skills\/\/SKILL.md` - Agents → `.groot\/nervous\/agents\/.md` - Project tasks → `bd create` (not markdown files) 3. Confirm creation **Note**: Project tasks are created as beads issues, not markdown in `.groot\/genome\/`. ### \/Action Proposals (HIGH BAR) Only propose new skills when ALL criteria are met: - [ ] 3+ occurrences of the same multi-step sequence - [ ] 3+ steps in the sequence - [ ] Parameterizable (can generalize with different inputs) - [ ] Distinct from existing skills - [ ] User explicitly approves Most patterns should graduate to `CLAUDE.md` (workflow rules) or `.groot\/genome\/domain\/` (knowledge), not skills. --- ## Output Format ```markdown ## Workflow Improvement: [MODE] Mode | [SCOPE] Scope | [SOURCE] Source ### Parsed Arguments - Fresh: [true|false] - Check: [true|false] - Mode: [focus|creative] - Scope: [skill|agent|workflow|project] - Request: [user request or "none"] ### Source [If fresh]: Analyzing current conversation only (no historical logs) [If logs]: Using accumulated logs from .groot\/memory\/sessions\/ + friction-log + beads ### Pre-flight Results (if check=true) [Show existing implementations, tools, beads issues, domain constraints] [Note: N potential overlaps found] ### Beads Context (if not fresh) - Open issues: N - Ready (unblocked): M - Stale (>30d): K ### Analysis [What was analyzed based on scope and source] ### Proposals [Proposal 1...] [Proposal 2...] [Proposal 3...] --- **Accept which proposals?** [1\/2\/3\/a\/n\/s] ``` --- ## Quiet Mode Output Format When `quiet=true`, use extremely terse output. Sacrifice grammar for concision. ```markdown ## \/up [mode] [scope] src: [fresh|logs|session-name] | beads: N open, M stale ### P1: [Type] [Name] solves: [one-liner] impact: [H\/M\/L] | effort: [H\/M\/L] ```impl [minimal implementation or file path] ``` ### P2: ... [1\/2\/3\/a\/n\/s]? ``` **Quiet mode rules:** - No headers like "Parsed Arguments", "Source", etc. - One-line summaries only - Skip explanations - Code blocks for impl only - Single char or short abbrevs (H\/M\/L, src, impl) - **Stay accurate** - terse ≠ vague; all key info must be present --- ## Source Behavior Summary | Source | What it analyzes | Use Case | |--------|------------------|----------| | `logs` (default) | Sessions + friction-log + beads | After multiple logged sessions | | `fresh` | Current conversation only | Immediate analysis, no history | | `from ` | Specific session file | Targeted session analysis | --- ## Mode Behavior Summary | Mode | Approach | Default | |------|----------|---------| | `focus` | Incremental, evidence-based | Yes | | `creative` | Out-of-box, speculative | No | --- ## Scope Behavior Summary | Scope | What it analyzes | What it proposes | |-------|------------------|------------------| | `project` | `.groot\/genome\/`, code, objectives, beads | Tasks (→ bd create), features, refactors | | `skill` | Sessions, friction-log | New\/improved skills | | `agent` | `.groot\/nervous\/agents\/`, workflow gaps | New\/improved agents | | `workflow` | All artifacts + beads flow | Skills + agents + process changes | --- ## Beads Integration ### What `\/up` reads from beads: | Command | Purpose | |---------|---------| | `bd ready --json` | Pending work (context for proposals) | | `bd stale --days 30 --json` | Neglected tasks (friction signal) | | `bd list --status open --json` | Overall backlog size | ### What `\/up` writes to beads: When project scope proposals are accepted: ```bash bd create "" -t task -p 2 -d "From \/up proposal" --json ``` ### Beads as friction signal: - Many stale issues → process problem, not just task problem - Same task types keep appearing → skill\/automation opportunity - Dependencies always blocking → architecture issue --- ## Fresh Mode Use Cases **When to use `\/up fresh`:** - Immediate feedback on current session patterns - Quick analysis without waiting for log accumulation - Testing improvement ideas before logging session - When historical context is irrelevant **When to use default (logged) mode:** - After multiple sessions with accumulated friction - Looking for cross-session patterns - Building on historical learnings - Standard periodic improvement reviews --- ## Relationship with \/snap | \/snap | \/up | |-------|-----| | Creates session journals | Reads session journals | | Detects friction → friction-log | Reads friction-log | | Spawns tasks → beads | Reads beads for context | | Session lifecycle | Analysis + improvement | **Typical flow:** 1. Work → `\/snap commit` (creates journal + beads issues) 2. Repeat across sessions 3. `\/up` (analyzes, proposes new improvements) 4. `\/up bake` (bakes proven patterns into structure) --- ## Constraints - Always show parsed arguments (transparency) - Max 3 proposals (focus) - Explain why each proposal helps - Default mode is `focus` (evidence-based) - Creative mode can fail - that's learning - Fresh mode clearly indicates source is current session only - Use `bd create` for project tasks, not markdown files - **Quiet mode**: terse but accurate; compress presentation, not information