testing-workflows-with-subagents

# Testing Workflows With Subagents

## Overview

**Testing workflows is TDD applied to orchestrator instructions and command documentation.**

You find real execution failures (git logs, error reports), create test scenarios that reproduce them, watch subagents follow ambiguous instructions incorrectly (RED), fix the instructions (GREEN), and verify subagents now follow correctly (REFACTOR).

**Core principle:** If you didn't watch an agent misinterpret the instructions in a test, you don't know if your fix prevents the right failures.

**REQUIRED BACKGROUND:** You MUST understand superpowers:test-driven-development before using this skill. That skill defines the fundamental RED-GREEN-REFACTOR cycle. This skill applies TDD to workflow documentation.

## When to Use

Use when:
- Creating new commands (`.claude/commands/*.md`, `/spectacular:*`)
- Editing orchestrator prompts for subagents
- Updating workflow documentation in commands
- You observed real execution failures (wrong branches, skipped steps, misinterpreted instructions)
- Instructions involve multiple steps where order matters
- Agents work under time pressure or cognitive load

Don't test:
- Pure reference documentation (no workflow steps)
- Single-step commands with no ambiguity
- Documentation without actionable instructions

## TDD Mapping for Workflow Testing

| TDD Phase | Workflow Testing | What You Do |
|-----------|------------------|-------------|
| **RED** | Find real failure | Check git logs, error reports for evidence of agents misinterpreting instructions |
| **Verify RED** | Create failing test scenario | Reproduce the failure with test repo + pressure scenario |
| **GREEN** | Fix instructions | Rewrite ambiguous steps with explicit ordering, warnings, examples |
| **Verify GREEN** | Test with subagent | Same scenario with fixed instructions - agent follows correctly |
| **REFACTOR** | Iterate on clarity | Find remaining ambiguities, improve wording, re-test |
| **Stay GREEN** | Re-verify |