dev-workflow-planning

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.

/brainstorm [topic or problem]

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

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

4. Approach C: [description, pros, cons]

5. Questions to Resolve

6. [List of unknowns needing clarification]

7. Recommended Approach

8. [Selected approach with justification]

Phase 2: Write Plan

Purpose: Create a detailed, actionable implementation plan.

/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]

Step 2: [Name] (~Xh)

...

Risks & Mitigations

Open Questions

• [Questions to resolve before starting]

Phase 3: Execute Plan

Purpose: Implement the plan systematically with checkpoints.

/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

Structured Patterns Hypothesis-Driven Development 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 PATTERN: Build in verifiable increments

For complex features: 1. Identify smallest testable unit 2. Implement and verify 3. Expand scope incrementally 4. Verify at each expansion 5. Integrate and verify whole

Example: Feature: User authentication - Increment 1: Basic login form (no backend) - Increment 2: API endpoint (hardcoded response) - Increment 3: Database integration - Increment 4: Session management - Increment 5: Password reset flow

Progress Tracking PATTERN: Maintain visible progress

After each action: [X] Step 1: Create database schema [X] Step 2: Implement API endpoints [IN PROGRESS] Step 3: Add frontend form [ ] Step 4: Write tests [ ] Step 5: Deploy to staging

Current: Step 3 of 5 (60% complete) Blockers: None Next: Complete form validation

Work in Progress (WIP) Limits PATTERN: Limit concurrent work to improve flow

WIP limits restrict maximum items in each workflow stage. Benefits: Makes blockers visible, reduces context switching, often increases throughput.

RECOMMENDED LIMITS: | Level | Limit | Rationale | |-------|-------|-----------| | Individual | 2-3 tasks | Minimize context switching | | Team (stories) | Team size + 1 | Allow pairing without blocking | | In Progress column | 3-5 items | Force completion before starting | | Code Review | 2-3 PRs | Prevent review bottleneck |

SETTING WIP LIMITS: 1. Start with team size + 1 2. Monitor for 2-4 weeks 3. If limits never reached -> lower them 4. If constantly blocked -> investigate bottleneck, don't raise limit 5. Adjust based on actual flow data

WHEN TO VIOLATE (thoughtfully): - Emergency production fix - Unblocking another team - Document the exception and review in retro

Session Management Starting a Session Session initialized. - Project: [name] - Goal: [today's objective] - Context loaded: [files, previous decisions] - Plan status: [steps remaining]

Ready to continue from: [last checkpoint]

Ending a Session /summarize

OUTPUT:

Session Summary

Completed

• [List of completed items]

In Progress

• [Current state of incomplete work]

Decisions Made

• [Key decisions with rationale]

Next Session

• [ ] [First task for next time]
• [ ] [Second task]

Context to Preserve

[Critical information for continuity]

Decision Framework When faced with choices:

1. State the decision clearly
2. List options (2-4)
3. For each option:
4. Pros
5. Cons
6. Effort estimate
7. Risk level
8. Recommendation with justification
9. Reversibility assessment

Example: Decision: How to implement authentication?

Recommendation: Sessions for MVP, plan JWT migration for scale.

Integration with Other Skills With Testing Skill /write-plan with TDD:

Step 1: Write failing test Step 2: Implement minimal code Step 3: Verify test passes Step 4: Refactor Step 5: Add edge case tests

With Architecture Skill /brainstorm system design:

1. Requirements clarification
2. Component identification
3. Interface definition
4. Data flow mapping
5. Implementation plan

Definition of Ready / Done (DoR/DoD)

assets/template-dor-dod.md - Checklists for work readiness and completion.

assets/template-work-item-ticket.md - Ticket template with DoR/DoD and testable acceptance criteria.

Key Sections Definition of Ready - User story, bug, technical task checklists Definition of Done - Feature, bug fix, spike completion criteria Acceptance Criteria Templates - Gherkin (Given/When/Then), bullet list, rule-based Estimation Guidelines - Story point reference scale (1-21+), slicing strategies Planning Levels - Roadmap -> Milestone -> Sprint -> Task hierarchy Cross-Functional Coordination - RACI matrix, handoff checklists Do / Avoid GOOD: Do Check DoR before pulling work into sprint Verify DoD before marking complete Size stories using reference scale Slice large stories (>8 points) Document acceptance criteria upfront Include risk buffer in estimates Coordinate handoffs explicitly BAD: Avoid Starting work without clear acceptance criteria Declaring "done" without testing Estimating without understanding scope Working on stories too big to finish in sprint Skipping code review "to save time" Deploying without staging verification Assuming handoffs happen automatically Anti-Patterns Anti-Pattern Problem Fix No DoR Unclear requirements discovered mid-sprint Gate sprint entry with DoR Soft DoD "Done" means different things Written DoD checklist Mega-stories Never finish, hard to track Slice to <8 points Missing AC Built wrong thing Gherkin format AC No ownership Work falls through cracks RACI for every epic Hope-based estimates Always late Use reference scale + buffer Optional: AI/Automation

Note: AI can assist but should not replace human judgment on priorities and acceptance.

Generate acceptance criteria - Draft from story description (needs review) Suggest story slicing - Based on complexity analysis Dependency mapping - Identify blocking relationships AI-augmented planning - Use LLMs to draft plans, but validate assumptions AI-Assisted Planning Best Practices Planning first - Create a plan before coding Scope management - Keep tasks small and verifiable Iterative steps - Ship in increments with checkpoints Human oversight - Validate assumptions and outputs (tests, logs, metrics) Bounded Claims AI-generated acceptance criteria need human review Story point estimates require team calibration Dependency mapping suggestions need validation AI impact on delivery stability requires monitoring Navigation Resources references/planning-templates.md - Plan templates for common scenarios references/session-patterns.md - Multi-session project management references/flow-metrics.md - DORA metrics, WIP limits, flow optimization assets/template-dor-dod.md - DoR/DoD checklists, estimation, cross-functional coordination assets/template-work-item-ticket.md - Work item ticket template (DoR/DoD + acceptance criteria) data/sources.json - Workflow methodology references Related Skills ../software-architecture-design/SKILL.md - System design planning ../docs-ai-prd/SKILL.md - Requirements to plan conversion ../qa-testing-strategy/SKILL.md - TDD workflow integration ../qa-debugging/SKILL.md - Systematic debugging plans