nw-ai-workflow-tutorials

name	nw-ai-workflow-tutorials
description	AI workflow tutorial patterns — non-deterministic output handling, outcome-based verification, and agent workflow step design
disable-model-invocation	true

AI Workflow Tutorial Patterns

Tutorials for AI-powered tools face a unique challenge: output is non-deterministic. Traditional tutorials show exact expected output; AI workflow tutorials define success by outcome.

The Non-Determinism Contract

State this early in any AI workflow tutorial:

> **AI output varies between runs.** Your output will look different from
> the examples in this tutorial. That is normal. We define success by
> what your code *does*, not what the agent *says*.

Timing Expectations

AI agents work in cycles with processing pauses. Users interpret silence as failure. Always set timing expectations:

## Step 3: Let the Agent Work (~5 minutes)

\`\`\`
/nw:deliver "feature description"
\`\`\`

This takes 3-5 minutes. The agent works in phases with 20-60 second
pauses between visible output. This is normal processing, not a hang.

Provide a "is it stuck?" diagnostic:

> **If you see no output for 2+ minutes**: Check the status bar at
> the bottom of Claude Code. A pulsing indicator means it is still
> working. If the indicator is gone, press Enter to prompt it.

Output Reading Guide

Teach users to read agent output by annotating a realistic example:

### Reading the Output

You will see phases scroll by. Here is what each means:

\`\`\`
● nw-solution-architect(...)     <- Planning what to build
  ⎿  Done (3 tool uses · 25s)   <- Phase complete, took 25 seconds

● nw-software-crafter(...)       <- Writing and testing code
  ⎿  Done (10 tool uses · 1m)   <- This is the longest phase

● nw-software-crafter-reviewer(...)  <- Independent quality check
  ⎿  Done (8 tool uses · 42s)
\`\`\`

Messages You Can Safely Ignore

Internal coordination messages confuse new users. Provide an explicit safe-to-ignore list:

### Messages you can safely ignore

These lines appear during normal operation and are not errors:

- `PreToolUse:Task hook error` -- DES validation checkpoint
- `DES_MARKERS_MISSING` -- Internal formatting check, auto-retries
- `⎿ SubagentStop` -- Agent coordination signal

Think of these as the agent's internal quality gates. They ensure
every step follows the engineering protocol.

Success Verification

Replace exact-output matching with outcome-based verification:

Traditional tutorial (deterministic):

You should see:
\`\`\`
Hello, World!
\`\`\`

AI workflow tutorial (non-deterministic):

**Verify success:**

\`\`\`bash
pytest tests/ -v
\`\`\`

All tests should pass. The exact number of tests may vary (the agent
sometimes adds extra tests beyond your originals). What matters: zero
failures.

\`\`\`bash
ls src/auth/
\`\`\`

You should see at least: `__init__.py`, `handlers.py`, `models.py`.
File names may differ slightly. The agent chose names based on its
analysis of your requirements.

Progressive Trust Building

Structure AI workflow tutorials to build trust incrementally:

Level 1: Micro-success (Step 1-2)

• Trivially small task where AI succeeds visibly
• User can verify independently within 30 seconds
• Example: generate a single function from one test

Level 2: Small feature (Step 3-4)

• Multi-step task with checkpoint verification
• User starts to trust the process
• Example: implement a module with 3-5 tests

Level 3: Full workflow (Step 5+)

• Complete feature delivery end-to-end
• User understands how to verify and intervene
• Example: full TDD delivery with review and mutation testing

Handling Divergence

When user output differs from the tutorial:

### What if my output looks different?

The agent generates code based on your specific tests and context.
Common variations:

| Tutorial shows | You might see | Both are correct because |
|---------------|---------------|------------------------|
| `class AuthHandler` | `def handle_auth()` | Function vs class is a style choice; tests verify behavior |
| 3 implementation steps | 2 or 4 steps | Agent may split or combine based on complexity |
| `jwt.encode(...)` | `create_token(...)` | Naming varies; the test contract is what matters |

**The rule**: if `pytest tests/ -v` passes, the implementation is correct
regardless of how it differs from the examples.

Recovery Patterns

AI workflows can fail or produce unexpected results. Provide escape hatches:

> **If tests fail after delivery**: Run `/nw:deliver` again with the same
> description. The agent detects existing code and failing tests, then
> fixes them. This is a resume, not a restart.

> **If the agent seems confused**: Start fresh with `git stash` to save
> your current state, then `git checkout step-2` to reset to the last
> known-good checkpoint.

> **If you want to start over entirely**: `git checkout main` returns
> to the original starter state.