lazyriver

Files (5)

• SKILL.md
• bundle.mjs
• lazyriver-workflow.bundled.js
• lazyriver-workflow.js
• river.js

SKILL.md (first lines)

<!-- introduction-gate: If introduction.md exists in this skill's directory AND
     the marker file /tmp/.skill-intro-lazyriver does NOT exist, read introduction.md,
     present its contents to the user, then create the marker: touch /tmp/.skill-intro-lazyriver
     Do NOT delete introduction.md — it lives in a protected directory.
     Do this BEFORE executing any skill logic below. -->

# LazyRiver — Goal-Seek Loop

Run a **goal** — not a plan — to **sufficiency**. `/lazyriver` is the goal-seek half of
the executor model: give it an insight to reach, a hypothesis to test, or a design to
converge on, and it runs a `probe → journal → judge → steer` loop until the goal is met,
then emits either a **plan** (hand to `/devspec`) or a **direct answer** (hand to the user).

**See Also:** `docs/executor-model-devspec.md` (Plan #822 — the two-mode executor: this
skill is the goal-seek activity, distinct from the plan-execution activity that
`/wavemachine` / `/nextwave` run).

> **This is NOT a variant of `/wavemachine` or `/nextwave`.** Those execute a *known DAG to
> completeness* (plan-execution). `/lazyriver` seeks a *goal to sufficiency* (goal-seek).
> Different termination condition, different parallelizability, different agency profile.
> Conflating the two is the exact conceptual error Plan #822 fixes — see
> **Epistemic vs Artifact Dependency** below.

---

## Invocation

```
/lazyriver <goal statement>
```

Optional:

```
/lazyriver <goal statement> --resume <journal-path>
```

`<goal statement>` is a goal, not a task list. It terminates on a **judgment** ("are we
there?"), not a checklist:

| Goal type | Example |
|-----------|---------|
| Understand | `/lazyriver "understand why merges stall on the kahuna branch"` |
| Test a hypothesis | `/lazyriver "is the 1.18× pool advantage real or measurement noise?"` |
| Converge a design | `/lazyriver "get to an executor model we trust"` |
| Root-cause | `/lazyriver "find the root cause of the reseed fidelity loss"` |

`--resume <journal-path>` reopens a prior session's **findings journal** (see below) and
continues the loop from the accumulated state — the loop never starts cold if a journal
exists. This is what makes a cord-fire (escalation) recoverable rather than terminal.

---

## Core Loop

Each **leg** of the loop is one recorded, resumable unit. A leg runs four steps in order:

```
Loop (each leg):
  1. Probe   — run the current leg: research, experiment, implement-a-spike, or analyze.
               The probe is chosen by Step 4 of the *previous* leg (or the goal, on leg 1).
  2. Journal — append this leg's findings to the durable per-session journal.
  3. Judge   — sufficiency gate: "are we there yet?"
                 SUFFICIENT       → emit output (plan | answer) → TERMINATE
                 DIMINISHING/CAP  → escalation cord fires → ESCALATE to user
                 NOT YET          → continue to Step 4
  4. Steer   — formulate the next probe *from what this leg just taught*:
               "given what we now know, what is the single most informative next probe?"
               → set it as leg N+1's Probe → goto 1
```

The order is load-bearing: **journal before judge** (so the sufficiency call is made
against a durable record, and a cord-fire never loses the leg it just ran), and **judge
before steer** (so you never formulate a next probe for a goal that is already met).

This is a `ralph-wiggum` loop *unrolled*: a raw `while not done: try()` retry is agency ≈ 0.
Unrolling upgrades it three ways — **+ agency** (Step 4 judges the result and steers the
next probe), **+ memory** (Step 2's journal accumulates; the loop gets smarter each leg),
and **+ durability** (each leg is a recorded, resumable unit). LazyRiver = ralph-wiggum
**with a brain and a notebook.** Without the sufficiency gate and the escalation cord it
would just be an *expensive infinite loop* — the characteristic ralph failure mode.

---

## Execution Modes — in-session vs. background Workflow

The `probe → journal → judge → steer` loop above runs two ways; the *logic is
identical*, only *where it runs* differs:

- **In-session (synchronous).** The main agent runs the loop directly in its own
  context — the original mode. Best for a short goal-seek you want to watch, or
  when you are already the agent doing the probing.
- **Background Workflow (detached, #844).** The loop runs as a **background
  Workflow** — `skills/lazyriver/lazyriver-workflow.bundled.js` — so the
  operator's session stays interactive while the goal-seek floats. Same
  architecture the wave engine uses (`per-wave-workflow.js`); it completes the
  executor model's symmetry — both plan-execution *and* goal-seek run as
  background Workflows sharing the substrate, keeping their distinct logic.

**Launching the background Workflow** — invoke the Workflow tool with
`scriptPath: skills/lazyriver/lazyriver-workflow.bundled.js` and `args` (a JSON
object):

| arg | meaning |
|-----|---------|
| `goal` | the goal statement (required) |
| `journalPath` | durable markdown path the leg agents append to and `resume` reopens (**required** — the Workflow script has no filesystem, so the launcher supplies the path; all journal I/O + timestamps happen inside the leg agents, which have Bash/Write) |
| `maxLegs` | leg-count cap (default 10) |
| `resume` | `true` to rehydrate from an existing `journalPath` — the loop never starts cold if a journal exists. Resume is a "keep probing" signal: the diminishing cord counter **resets** (fresh legs, not an instant re-fire); raise `maxLegs` to resume past a leg-cap |

**The verdict** the Workflow returns — the driver *surfaces* it; it is **never a
silent background stall**:

- `{ outcome: 'sufficient', output: { kind: 'plan' | 'answer', content }, journalPath, legs }`
  — the goal is met; hand `output` to `/devspec` (plan) or the user (answer), per the Output Contract.
- `{ outcome: 'escalated', reason, journalPath, legs }` — the **escalation cord**
  fired (`cord:diminishing` = 2 consecutive zero-finding legs, or `cord:leg-cap`).
  The driver surfaces the journal + the sufficiency question to the operator,
  exactly like a wave HOLD. The journal is intact and `resume`-able (CT-04).

From Wave-Engineering/claudecode-workflow, MIT.

More from Wave-Engineering/claudecode-workflow