# up

> Analyze workflow and propose improvements with beads integration

- Author: root
- Repository: 01O10/groot
- Version: 20260129183620
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/01O10/groot
- Web: https://mule.run/skillshub/@@01O10/groot~up:20260129183620

---

---
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/<channel>/ (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-<timestamp>` 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 `<up:complete/>` 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=<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:

```
<up:complete reason="no-proposals"/>
```

Or:
```
<up:complete reason="threshold"/>
```

Or:
```
<up:complete reason="criteria-met"/>
```

### 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] <up:complete reason="[reason]"/>
[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 <session>`

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/<name>.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 "<keywords>"` 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/<file>.md`
   - **Skills (HIGH BAR)** → `.groot/nervous/skills/<name>/SKILL.md`
   - Agents → `.groot/nervous/agents/<name>.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 <session>` | 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 "<task title>" -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