dev-workflow-planning

What this skill does

# Workflow Planning Skill - Quick Reference

This skill enables structured, systematic development workflows. The assistant should apply these patterns when users need to break down complex projects, create implementation plans, or execute multi-step development tasks with clear checkpoints.

**Inspired by**: Obra Superpowers patterns for structured agent workflows.

---

## Quick Reference

| Command | Purpose | When to Use |
|---------|---------|-------------|
| `/brainstorm` | Generate ideas and approaches | Starting new features, exploring solutions |
| `/write-plan` | Create detailed implementation plan | Before coding, after requirements clarification |
| `/execute-plan` | Implement plan step-by-step | When plan is approved, ready to code |
| `/checkpoint` | Review progress, adjust plan | Mid-implementation, after major milestones |
| `/summarize` | Capture learnings, document decisions | End of session, before context reset |

## When to Use This Skill

The assistant should invoke this skill when a user requests:

- Break down a complex feature into steps
- Create an implementation plan
- Brainstorm approaches to a problem
- Execute a multi-step development task
- Track progress on a project
- Review and adjust mid-implementation

---

## The Three-Phase Workflow

### Phase 1: Brainstorm

**Purpose**: Explore the problem space and generate potential solutions.

```text
/brainstorm [topic or problem]

OUTPUT:
1. Problem Understanding
   - What are we solving?
   - Who is affected?
   - What are the constraints?

2. Potential Approaches (3-5)
   - Approach A: [description, pros, cons]
   - Approach B: [description, pros, cons]
   - Approach C: [description, pros, cons]

3. Questions to Resolve
   - [List of unknowns needing clarification]

4. Recommended Approach
   - [Selected approach with justification]
```

### Phase 2: Write Plan

**Purpose**: Create a detailed, actionable implementation plan.

```text
/write-plan [feature or task]

OUTPUT:
## Implementation Plan: [Feature Name]

### Goal
[Single sentence describing the outcome]

### Success Criteria
- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Criterion 3

### Steps (with estimates)

#### Step 1: [Name] (~Xh)
- What: [specific actions]
- Files: [files to modify/create]
- Dependencies: [what must exist first]
- Verification: [how to confirm done]

### Risks & Mitigations
| Risk | Likelihood | Impact | Mitigation |
|------|-----------|--------|------------|
| Risk 1 | Medium | High | Plan B if... |

### Open Questions
- [Questions to resolve before starting]
```

#### Dependency Graph for Parallel Execution

When a plan will be executed with multiple subagents, each task **must** declare its dependencies explicitly. This enables the orchestrator to determine which tasks can run in parallel.

```text
### Task Dependency Graph

| Task ID | Name | depends_on | Files | Agent Scope |
|---------|------|------------|-------|-------------|
| T1 | Setup database schema | [] | db/schema.sql | db-engineer |
| T2 | Create API routes | [T1] | src/routes/*.ts | backend-dev |
| T3 | Build auth middleware | [T1] | src/middleware/auth.ts | backend-dev |
| T4 | Frontend components | [] | src/components/*.tsx | frontend-dev |
| T5 | Integration tests | [T2, T3, T4] | tests/integration/*.test.ts | qa-agent |
```

**Rules for dependency graphs:**
- Every task declares `depends_on: []` with explicit task IDs (empty array = no blockers).
- Tasks with no dependencies can start immediately (in parallel).
- No circular dependencies — the graph must be a DAG (directed acyclic graph).
- Each task should specify its file ownership to prevent parallel conflicts.

#### Parallel Execution Strategies

**Swarm Waves (Accuracy-First)** — Launch one subagent per unblocked task, in dependency-respecting waves. Wait for each wave to complete before launching the next. Best for production code and complex interdependencies.

**Super Swarms (Speed-First)** — Launch as many subagents as possible at once, regardless of dependencies. Best for prototypes and greenfield scaffolding. Expect merge conflicts.

See [references/planning-templates.md](references/planning-templates.md) for the full swarm-ready plan template.

### Phase 3: Execute Plan

**Purpose**: Implement the plan systematically with checkpoints.

```text
/execute-plan [plan reference]

EXECUTION PATTERN:
1. Load the plan
2. For each step:
   a. Announce: "Starting Step X: [name]"
   b. Execute actions
   c. Verify completion
   d. Report: "Step X complete. [brief summary]"
3. After completion:
   a. Run all verification criteria
   b. Report final status
```

---

## Worktree-First Delivery

For production coding sessions, wrap `/execute-plan` with a delivery guardrail:

1. Create one isolated worktree per feature.
2. Execute only the approved plan scope in that worktree.
3. Run repo-defined quality gate(s) before PR (example: `npm run test:analytics-gate`).
4. Open one focused PR per feature branch.

```bash
./scripts/git/feature-workflow.sh start <feature-slug>
cd .worktrees/<feature-slug>
# implement plan steps
../../scripts/git/feature-workflow.sh gate
../../scripts/git/feature-workflow.sh pr --title "feat: <summary>"
```

---

## Agent Session Management

**Key rules from production experience (Feb 2026):**

- **One feature per session.** Context exhaustion causes rework. A sprawling session (38 messages, 3+ continuations) produced multiple errors; a focused session (5 messages) shipped clean.
- **Write a plan before touching 3+ files.** Sessions with pre-written numbered plans had near-zero rework.
- **Verify SDK types before executing plan steps.** Documentation may describe APIs that no longer match actual TypeScript definitions.

See [references/session-patterns.md](references/session-patterns.md) for the full production evidence table and checkpoint protocol for long sessions.

---

## Command Preflight Protocol

Before broad edits, tests, or reviews — run a 60-second preflight:
1. `pwd` / `git branch --show-current` / `ls -la`
2. `test -e <path>` to verify target paths before heavy commands
3. `npx <tool> --help` to validate flags before first use
4. Quote paths containing `[]`, `*`, `?`, or spaces

See [references/operational-checklists.md](references/operational-checklists.md) for the full git/branch safety preflight, E2E/server preflight, shell safety gate, and SDK type verification.

---

## Structured Patterns

### Hypothesis-Driven Development

```text
PATTERN: Test assumptions before committing

Before implementing:
1. State hypothesis: "If we [action], then [expected outcome]"
2. Define experiment: "To test this, we will [minimal test]"
3. Execute experiment
4. Evaluate: "Hypothesis confirmed/rejected because [evidence]"
5. Proceed or pivot based on result
```

### Incremental Implementation

Build in verifiable increments: smallest testable unit → implement and verify → expand scope → verify at each expansion → integrate and verify whole.

See [references/planning-templates.md](references/planning-templates.md) for an authentication feature example with 5 increments.

### Progress Tracking

```text
PATTERN: Maintain visible progress

[X] Step 1: Create database schema
[X] Step 2: Implement API endpoints
[IN PROGRESS] Step 3: Add frontend form
[ ] Step 4: Write tests

Current: Step 3 of 4 (75% complete)
Blockers: None
Next: Complete form validation
```

### Work in Progress (WIP) Limits

Limit concurrent work: individual (2-3 tasks), team stories (team size + 1), in-progress column (3-5 items), code review (2-3 PRs). If limits are never reached, lower them. If constantly blocked, investigate the bottleneck.

See [references/planning-templates.md](references/planning-templates.md) for the full WIP limits reference and setting guidelines.

---

## Milestone Checkpointing and Scope Budgeting

For multi-step execution, constrain scope and checkpoint progress at milestone boundaries.

- Define explicit session scope at start: `1-2` deliverables only.
- If a