workflow-orchestration

Orchestrates agent workflow for non-trivial tasks: plan-first mode, subagent use, self-improvement loops, verification before done, and autonomous bug fixing. Use for any task with 3+ steps, architectural decisions, bug reports, or when the user corrects the agent. Ensures plans go in tasks/todo.md, lessons in tasks/lessons.md, and changes stay minimal and provably correct.

SKILL.md

---
name: workflow-orchestration
description: Orchestrates agent workflow for non-trivial tasks: plan-first mode, subagent use, self-improvement loops, verification before done, and autonomous bug fixing. Use for any task with 3+ steps, architectural decisions, bug reports, or when the user corrects the agent. Ensures plans go in tasks/todo.md, lessons in tasks/lessons.md, and changes stay minimal and provably correct.
---

# Workflow Orchestration

## When This Skill Applies

- Any non-trivial task (3+ steps or architectural decisions)
- When something goes sideways during execution
- After any user correction
- When given a bug report or failing CI
- When verifying behavior before marking work complete

---

## 1. Plan Mode (Default)

- **Enter plan mode** for every non-trivial task. Do not start implementation without a plan.
- **If something goes sideways**: STOP and re-plan immediately. Do not keep pushing.
- Use plan mode for **verification steps** as well as building.
- **Write detailed specs upfront** to reduce ambiguity (inputs, outputs, edge cases, success criteria).

---

## 2. Subagent Strategy

- Use subagents **liberally** to keep the main context window clean.
- Offload **research, exploration, and parallel analysis** to subagents.
- For complex problems, use **more compute via subagents** (e.g. multiple agents in parallel where appropriate).
- **One task per subagent** for focused execution; give clear, self-contained instructions.

---

## 3. Self-Improvement Loop

- **After ANY correction from the user**: update `tasks/lessons.md` with the pattern.
- Write **rules for yourself** that prevent the same mistake.
- Iterate on these lessons until mistake rate drops.
- **Review lessons at session start** for the relevant project.

---

## 4. Verification Before Done

- **Never mark a task complete** without proving it works.
- When relevant: **diff behavior** between main and your changes.
- Ask: *"Would a staff engineer approve this?"*
- **Run tests, check logs, demonstrate correctness** before presenting.

---

## 5. Demand Elegance (Balanced)

- For **non-trivial changes**: pause and ask *"Is there a more elegant way?"*
- If a fix feels hacky: *"Knowing everything I know now, implement the elegant solution."*
- **Skip** for simple, obvious fixes; do not over-engineer.
- Challenge your own work before presenting it.

---

## 6. Autonomous Bug Fixing

- When given a **bug report**: fix it. Do not ask for hand-holding.
- **Point at logs, errors, failing tests** – then resolve them.
- Zero context switching required from the user.
- **Fix failing CI tests** without being told how.

---

## Task Management

| Practice | Action |
|----------|--------|
| **Plan first** | Write plan to `tasks/todo.md` with checkable items |
| **Verify plan** | Check in before starting implementation |
| **Track progress** | Mark items complete as you go |
| **Explain changes** | High-level summary at each step |
| **Document results** | Add review section to `tasks/todo.md` |
| **Capture lessons** | Update `tasks/lessons.md` after corrections |

---

## Core Principles

- **Simplicity first**: Make every change as simple as possible. Impact minimal code.
- **No laziness**: Find root causes. No temporary fixes. Senior developer standards.
- **Minimal impact**: Changes touch only what is necessary. Avoid introducing new bugs.