Workflow Guide

This skill provides extended guidance for the /workflow:* command set. Commands reference specific sections when additional context is needed.

Philosophy

Core Tenets

1. •Do what works, don't overcomplicate - Simple processes that get results beat complex frameworks
2. •Work spans multiple sessions - Structure for continuity without loss of fidelity
3. •Speed + quality + attention to detail wins - Fast execution with high standards
4. •Knowledge compounds - Each solved problem makes future work easier

Vertical Slicing

Build features end-to-end, not layer-by-layer.

Traditional (Horizontal) Approach - Avoid:

1. Build all domain entities
2. Build all repositories
3. Build all use cases
4. Build all API endpoints
5. Build UI
6. Integrate and test

Vertical Slicing Approach - Preferred:

1. Pick highest priority user story
2. Build ONLY what's needed for that story through ALL layers
3. Deploy it
4. Pick next story, repeat

Why Vertical Slicing Works

• •Faster Time to Value - Deploy features as they're ready
• •Reduced Risk - Small slices are testable
• •Better Feedback - Users see progress immediately
• •Easier Integration - Continuous, not big-bang
• •Clear Progress - Working features, not "90% complete" layers

Bottom-Up Implementation

While we plan top-down (user story → layers), we implement bottom-up:

1. •Domain Layer First - Pure business logic, no dependencies
2. •Infrastructure Layer - Data access, external services
3. •Application Layer - Use cases, orchestration
4. •Framework Layer - API endpoints, UI

This order ensures each layer depends only on layers below it.

The Five Commands

/workflow:refine

Purpose: Discover and refine requirements through conversation

Outputs:

• •./planning/<project>/requirements.md - Problem, solution, user stories, requirements
• •PM issue (optional) - Linear or Jira issue creation

When to use: When starting from a vague idea, unclear requirements, or needing stakeholder alignment before planning

/workflow:plan

Purpose: Create implementation plans from requirements

Outputs:

• •./planning/<project>/implementation-plan.md - How to build it
• •./planning/<project>/session-state.md - Continuity tracking

When to use: After requirements are clear (from /workflow:refine or existing documentation)

/workflow:execute

Purpose: Session-based work with progress tracking

Key features:

• •Session state persistence
• •TodoWrite integration
• •Quality checkpoints
• •Compound prompts at boundaries

When to use: Implementing planned work

/workflow:review

Purpose: Flexible code review

Supports:

• •PR reviews (/workflow:review #123)
• •Git ranges (/workflow:review main..HEAD)
• •Files (/workflow:review ./src/auth/)
• •Uncommitted (/workflow:review changes)

When to use: Before merging or deploying

/workflow:compound

Purpose: Capture knowledge from solved problems

Creates: docs/solutions/<category>/<slug>.md

When to use: After solving non-trivial problems

Priority System

P1 - Must Have

Essential for feature completion. Without these, it doesn't work.

• •Core domain logic
• •Primary use case
• •Essential persistence
• •Main user interface
• •Critical path tests

P2 - Should Have

Improves quality but not strictly necessary for initial deployment.

• •Comprehensive validation
• •Detailed error messages
• •Performance optimizations
• •Extended test coverage
• •Logging and monitoring

P3 - Nice to Have

Can be deferred to future iterations.

• •Advanced UI features
• •Analytics integration
• •Detailed documentation
• •Performance metrics
• •Extended customization

Session Continuity

Planning Directory Structure

./planning/
├── <project-name>/
│   ├── requirements.md          # What we're building (from /workflow:refine)
│   ├── implementation-plan.md   # How we're building it (from /workflow:plan)
│   ├── session-state.md         # Multi-session tracking (from /workflow:plan)
│   └── technical-decisions.md   # Key decisions (optional)
└── archive/                     # Completed work

Session State Schema

---
project: [name]
session_count: [N]
status: [planned|in_progress|complete]
progress:
  total_tasks: [X]
  completed: [Y]
  percent: [Z%]
current_layer: [domain|infrastructure|application|framework]
branch: <type>/<issue-key or description>
---
## Current Focus
[What's being worked on]

## Last Session Summary
[Handoff context]

## Session History
[Append-only log]

Branch Naming Convention

Use a consistent <type>/<identifier> pattern for branch names:

Guidelines:

• •Prefer issue keys when available—they link branches to tracking systems
• •Use lowercase with hyphens for descriptions
• •Keep descriptions short (2-4 words)

Handoff Protocol

At session boundaries:

1. •Update session state with progress
2. •Commit work with clear message
3. •Offer compound documentation
4. •Generate detailed handoff summary

Common Pitfalls

Over-Engineering the First Slice

Wrong: Building everything a feature might need

class Task:
    def __init__(self, title, description, status, priority,
                 assignee, labels, attachments, comments, ...):

Right: Building only what the current story needs

class Task:
    def __init__(self, title, description):

Building Horizontal Infrastructure

Wrong: All repository methods upfront

class TaskRepository:
    def create(self, task): ...
    def update(self, task): ...
    def delete(self, task_id): ...
    def find_by_status(self, status): ...

Right: Only what current story needs

class TaskRepository:
    def create(self, task): ...

Premature Abstraction

Wrong: Complex inheritance before patterns emerge

class BaseEntity: ...
class AuditableEntity(BaseEntity): ...
class Task(AuditableEntity): ...

Right: Simple, direct implementation

@dataclass
class Task:
    id: str
    title: str

Skipping Quality Gates

Wrong: Moving to next task with failing tests Right: Fix failures immediately, maintain green builds

80% Done Syndrome

Wrong: Moving to next feature before current is complete Right: Ship complete features, then move on

Extended Guidance

For detailed templates and patterns, reference these sections:

Planning Phase

• •planning/templates.md - Vertical slice, quick, epic, spike, bug fix templates
• •planning/task-breakdown.md - P1/P2/P3 breakdown patterns and estimation

Implementation Phase

• •implementation/quality-checkpoints.md - Per-layer quality gates

PM Integration

• •planning/pm-integration.md - Linear, Jira, and manual workflow guides

Examples

• •examples/planning-example.md - Complete planning walkthrough

Key Principles Summary

Remember

• •YAGNI - Build only what the current story needs
• •Ship Early - Deploy as soon as the slice works
• •Refactor Continuously - Clean up as patterns emerge
• •Stay Vertical - Resist building horizontal layers
• •Compound Knowledge - Each problem solved helps future work

References

Knowledge Compounding

The concept of "compounding" AI assistance—capturing solutions so each problem solved makes future work easier—is adapted from:

• •"How to Use AI to Do Practical Stuff: A New Guide" by Ethan Mollick, Every.to https://every.to/chain-of-thought/how-to-use-ai-to-do-practical-stuff-a-new-guide

This idea drives the /workflow:compound command: systematically documenting solutions creates a knowledge base that accumulates value over time, making the AI assistant increasingly effective for your specific codebase and patterns.