# Waterfall

> Sequential staged processing — each stage must pass before the next begins

- Skill: `rlaope/waterfall` (Agent Skill)
- Install (CLI): `npx skillmds@latest add rlaope/waterfall`
- Raw SKILL.md: https://api.skillmd.com/api/skills/rlaope/waterfall/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: rlaope (https://skillmd.com/u/rlaope)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/rlaope/waterfall

---


When this skill is invoked, you MUST follow this exact output sequence.

## Step 1: Header (print IMMEDIATELY)

```
[BW] waterfall mode — sequential stages with gates...
```

## Step 2: Define stages

Analyze the user's task and break it into sequential stages. Each stage has a gate condition that MUST pass before proceeding.

Default waterfall (adapt based on task):
1. **analyze** — understand requirements, identify affected files, map dependencies
2. **implement** — write the code changes
3. **verify** — run type checks, linters, tests
4. **integrate** — ensure changes work with existing code (import checks, no regressions)
5. **finalize** — clean up, format, commit-ready state

Print the waterfall:
```
[BW] waterfall stages:
  1. analyze    → gate: scope documented
  2. implement  → gate: all files written
  3. verify     → gate: type check + tests pass
  4. integrate  → gate: no broken imports
  5. finalize   → gate: formatted, no warnings
```

## Step 3: Execute each stage sequentially

For EACH stage, print entry and exit:

```
[BW] ┌─ stage 1: analyze
```

Execute the stage work. Assign the best-fit agent per stage:
- analyze: pm-product or tech-fullstack
- implement: tech-{domain} specialist
- verify: tech-testing or critic-code
- integrate: tech-fullstack
- finalize: tech-config or tech-writer

When stage completes, evaluate the gate:

```
[BW] └─ stage 1: analyze — PASS (3 files, 2 domains identified)
```

or if gate fails:

```
[BW] └─ stage 2: implement — FAIL (missing error handler in auth.ts)
[BW] ↻ retrying stage 2 (attempt 2/3)
[BW] ┌─ stage 2: implement (retry)
```

## Step 4: Gate failure handling

- Each stage gets max 3 attempts
- If a stage fails 3 times, the waterfall halts:
```
[BW] ✗ waterfall halted at stage 2: implement
[BW]   reason: {failure description}
[BW]   completed: stages 1/5
[BW]   run ./waterfall to resume from stage 2
```

## Step 5: Waterfall complete

```
[BW] ═══════════════════════════════════
[BW] waterfall complete: {N} stages, all gates passed
[BW] ═══════════════════════════════════
```

After writing the meeting log footer to `.bestwork/state/meeting.jsonl`, also append a decisions entry to `.bestwork/context/decisions.md`. Create the file and directory if they do not exist.

Format:
```markdown
## {date}: {task}
- **Mode**: waterfall ({N} stages)
- **Verdict**: {COMPLETE/HALTED at stage N}
- **Key agents**: {comma-separated agent list}
- **Summary**: {1-sentence summary of what was processed}
```

## Custom waterfalls

Users can define custom stage orders:
- `./waterfall test-first` — verify → implement → verify → finalize (TDD)
- `./waterfall security` — analyze → implement → security-audit → verify → finalize
- `./waterfall docs` — analyze → implement → document → verify → finalize

## State persistence

Save waterfall state to `.bestwork/state/waterfall.json`:
```json
{
  "created": "<ISO timestamp>",
  "task": "<user's original request>",
  "stages": [
    { "name": "analyze", "status": "complete", "attempts": 1 },
    { "name": "implement", "status": "running", "attempts": 1 }
  ],
  "currentStage": 1
}
```

This enables resuming a halted waterfall with `./waterfall` (picks up from last incomplete stage).

## Rules

- Stages are STRICTLY sequential — never parallelize across stages
- Each gate must be evaluated with concrete evidence (not just "looks good")
- Gate checks should run actual commands when possible (tsc, test runner, linter)
- Max 3 retries per stage before halt
- Save state after each stage completion for resume capability
- Write meeting log to `.bestwork/state/meeting.jsonl` with stage transitions