Development Workflow

Overview

A structured approach to feature development using progressive disclosure - starting high-level and adding detail at each stage. Four phases transform ideas into executable tasks: Discovery → Requirements → Research & Design (the bridge) → Sequencing → Implementation.

Core principle: Progressive disclosure from generic understanding to system-specific adaptation to execution detail. Each artifact layer reveals more specificity than the last.

Progressive Disclosure Explained

Like Anthropic's Agent Skills architecture, this workflow uses progressive disclosure to manage complexity:

Level 1: Requirements (High-level, generic)

What needs to be solved?
Written generically, not tied to specific implementation

Level 2: Design (Medium detail, system-specific)

THE BRIDGE: Adapts generic requirements to your system
Your tools, people, process, existing architecture
How the solution fits your specific context

Level 3: Sequencing (Higher detail, work decomposition)

How to order and decompose the work
Risk, resources, dependencies, proof-of-concept

Level 4: Implementation (Maximum detail, executable)

Every action specified (2-5 min tasks)
Exact file paths, complete code, test commands

Why this matters: You can't jump from generic requirements directly to code. You need the intermediate layers to bridge understanding to execution.

When to Use

Use this workflow when:

Starting new feature development from scratch
You have generic requirements that need adaptation to your system
Need the "bridge" from what to how in your specific context
Working on features requiring architectural decisions

Don't use for:

Bug fixes (may jump straight to implementation)
Well-defined tasks with system-specific design already done
Small refactorings where the bridge isn't needed

The Flow (Progressive Disclosure)

Development Flow Diagram

mermaid

graph TD
    %% Phase 1: Discovery & Ideation
    brainstorm@{ shape: rounded, label: "Brainstorm" }
    elicit@{ shape: rounded, label: "Elicit" }
    sensemaking@{ shape: rounded, label: "Sense Making" }
    framing@{ shape: rounded, label: "Problem Framing" }
    whiteboard@{ shape: doc, label: "Whiteboard\n(Phase 1)" }
    
    %% Phase 2: Research & Design - The Bridge
    requirements@{ shape: doc, label: "Requirements\nDocument" }
    gather@{ shape: rect, label: "Gather Software &\nSystem Context" }
    gaps@{ shape: rect, label: "Identify Gaps" }
    hypothesis@{ shape: rect, label: "Solutions\nHypothesis" }
    patterns@{ shape: rect, label: "Identify Existing Patterns\nAND/OR\nResearch Working Patterns" }
    whiteboard2@{ shape: doc, label: "Whiteboard\n(Phase 2)" }
    design@{ shape: doc, label: "Design\nDocument" }
    
    %% Phase 3 & 4: Progressive Disclosure
    sequencing@{ shape: doc, label: "Sequencing\nDocument" }
    implementation@{ shape: doc, label: "Task\nImplementation Plan" }
    
    %% Phase 1 Flow
    brainstorm --> whiteboard
    elicit --> whiteboard
    sensemaking --> whiteboard
    framing --> whiteboard
    
    %% Phase 1 to Phase 2 transition
    whiteboard --> requirements
    
    %% Phase 2 Flow - The Bridge
    requirements --> gather
    gather --> gaps
    gaps --> hypothesis
    hypothesis --> patterns
    patterns --> hypothesis
    
    %% Phase 2 outputs
    hypothesis --> whiteboard2
    patterns --> whiteboard2
    whiteboard2 --> design
    
    %% Phase 3 Flow
    requirements --> sequencing
    design --> sequencing
    whiteboard -.-> sequencing
    whiteboard2 -.-> sequencing
    
    %% Phase 4 Flow
    sequencing --> implementation
    
    %% Styling
    classDef ideation fill:#fff4cc,stroke:#f4c430,stroke-width:2px
    classDef research fill:#ffe4cc,stroke:#ff9933,stroke-width:2px
    classDef doc1 fill:#e6f3ff,stroke:#4a90e2,stroke-width:2px
    classDef doc2 fill:#d1e7dd,stroke:#0f5132,stroke-width:2px
    classDef doc3 fill:#cfe2ff,stroke:#084298,stroke-width:3px
    classDef doc4 fill:#d4edda,stroke:#28a745,stroke-width:3px
    
    brainstorm:::ideation
    elicit:::ideation
    sensemaking:::ideation
    framing:::ideation
    
    gather:::research
    gaps:::research
    hypothesis:::research
    patterns:::research
    
    whiteboard:::doc1
    whiteboard2:::doc1
    requirements:::doc2
    design:::doc2
    sequencing:::doc3
    implementation:::doc4

Legend

Yellow - Discovery & Ideation activities (Phase 1)
Orange - Research & Design activities (Phase 2 - THE BRIDGE)
Light blue - Whiteboards (informal)
Green - Requirements & Design (Level 1 & 2)
Blue - Sequencing (Level 3)
Dark green - Implementation Plan (Level 4 - maximum detail)
Solid arrows - Primary flow
Dotted arrows - Optional/weak inputs

Progressive Disclosure Levels

Requirements (Light green) - Generic, high-level
Design (Green) - System-specific, medium detail ← THE BRIDGE
Sequencing (Blue) - Work decomposition, higher detail
Implementation (Dark green) - Maximum detail, executable

The Four Phases (Progressive Disclosure)

Phase 1: Discovery & Ideation → Requirements

Goal: Frame the problem at a high level

Activities:

Brainstorm - Generate ideas, explore possibilities
Elicit - Extract user needs, clarify requirements
Sense Making - Connect dots, identify patterns
Problem Framing - Define the actual problem to solve

First Output: Whiteboard document (informal, exploratory)

Second Output: Requirements Document (formal, high-level, generic)

Skills used:

writing-requirements-documents - Transform whiteboard into formal requirements
Focus: Generic problem statement, not yet system-specific

Progressive disclosure level: High-level, generic understanding

Phase 2: Research & Design (The Bridge)

Goal: Adapt generic requirements to your specific system context

This is the bridge: Requirements are written generically. Design adapts them to your tools, people, process, and existing system architecture.

Activities (iterative loop):

Gather Software & System Context
- Read codebase architecture docs
- Identify relevant modules/components
- Understand constraints
Identify Gaps
- What's missing?
- What needs to change?
- What patterns don't exist yet?
Solutions Hypothesis
- Propose approach adapted to system
- Consider alternatives
- Evaluate trade-offs
Identify Existing Patterns AND/OR Research Working Patterns
- Search codebase for similar implementations
- Research best practices externally (Perplexity, web search)
- Feed findings back to hypothesis

Intermediate Output: Whiteboard (Phase 2) - captures research findings

Final Output: Design Document - system-specific technical design

Skills used:

evaluate-against-architecture-principles - validate design choices
May use web_search, code search

Progressive disclosure level: Medium detail - adapted to system context

Phase 3: Sequencing

Goal: Decompose design into ordered work units

Inputs:

Requirements (strong input)
Design (strong input)
Whiteboards (weak input - may or may not be referenced)

Activities:

Break design into logical phases
Identify dependencies
Order tasks for incremental delivery
Consider risk, resources, proof-of-concept needs

Output: Sequencing Document - work breakdown with ordering rationale

Skills used: None specific

Progressive disclosure level: Higher detail - work decomposition

Phase 4: Implementation Plan

Goal: Maximum detail - every action specified

Input: Sequencing Document

Output: Task Implementation Plan - bite-sized tasks (2-5 min each)

REQUIRED SKILL: writing-plans

Each task is one action (TDD cycle)
Exact file paths, complete code examples
Test commands with expected output
Commit after each task

Progressive disclosure level: Maximum detail - executable instructions

Execution After Planning

Once Task Implementation Plan exists, choose execution approach:

Option 1: Subagent-Driven Development (same session) REQUIRED SKILL: subagent-driven-development

Fresh subagent per task
Code review between tasks
Fast iteration with quality gates

Option 2: Executing Plans (parallel session) REQUIRED SKILL: executing-plans

Open new session in worktree
Batch execution with checkpoints
More autonomous execution

Decision Points

When to loop back during Research & Design?

Research loop continues until solution hypothesis is solid
Patterns research feeds back to hypothesis iteratively
Design complete when system-specific approach is clear

When to split into multiple workflows?

Feature too large (>20 tasks in implementation plan)
Multiple independent subsystems
Parallel development needed

When to skip phases?

Skip Discovery: Problem already well-understood, requirements exist
Never skip: Requirements → Research & Design → Sequencing → Implementation
The Bridge is mandatory: Can't go straight from generic requirements to implementation

Example Workflow

plaintext

User: "We need better validation for our citation links"

Phase 1: Discovery & Ideation
- Brainstorm: What could go wrong with links?
- Elicit: What validation already exists?
- Sense Making: Links break = docs become unreliable
- Problem Framing: Need automated validation before commit
Output: Whiteboard with problem understanding
Output: Requirements Doc (FR1-FR5 with block anchors)
Level: HIGH-LEVEL, GENERIC

Phase 2: Research & Design (The Bridge)
- Requirements exist, now adapt to our system
- Gather: Read citation-manager code, git hooks, existing validation
- Identify Gaps: No pre-commit validation, no link checker
- Solutions Hypothesis: Add git hook calling validation script
- Research Patterns: How do other tools do this? (remark-validate-links)
- Update Phase 2 Whiteboard with findings
Output: Design Document (hook architecture, validation script design)
Level: MEDIUM DETAIL, SYSTEM-SPECIFIC

Phase 3: Sequencing
- Input: Requirements + Design (+ optional whiteboard context)
- Break into phases: Phase 1 (validation script), Phase 2 (git hook), Phase 3 (tests)
- Sequence by risk: Prove validation logic first, then integrate
Output: Sequencing Document with ordered phases
Level: HIGHER DETAIL, WORK DECOMPOSITION

Phase 4: Implementation Plan
- Input: Sequencing Document
- Break each phase into 2-5 min tasks
- Task 1: Write failing test for validation
- Task 2: Implement minimal validator
- ... (12 tasks total with exact code)
Output: Task Implementation Plan
Level: MAXIMUM DETAIL, EXECUTABLE

Execution:
- Choose subagent-driven-development (same session)
- Execute tasks with code review checkpoints
- Complete with finishing-a-development-branch

Visual Reference

See Development Flow Diagram for complete flowchart showing:

Discovery activities → Whiteboard → Requirements (yellow → light blue)
Research & Design loop creating system-specific design (orange → green)
Sequencing with strong inputs from Requirements/Design (blue)
Implementation Plan with maximum detail (dark green)
Progressive disclosure: each layer more specific than the last

Red Flags

🚩 Starting Design without Requirements (skipping high-level understanding) 🚩 Starting Implementation without Sequencing (no work decomposition) 🚩 Skipping Research & Design phase (no bridge to system context) 🚩 Treating Requirements as system-specific (they should be generic) 🚩 Treating Design as generic (it should be adapted to your system) 🚩 Going straight from Requirements to Implementation (missing 2 layers of disclosure)

Integration with Other Skills

Required in this workflow:

writing-requirements-documents - Phase 1 (Requirements)
evaluate-against-architecture-principles - Phase 2 (Design validation)
writing-plans - Phase 4 (Implementation Plan)
subagent-driven-development OR executing-plans - Execution

May be used:

Web search tools - During Research & Design phase

Leads to:

finishing-a-development-branch - After execution completes

Remember: Progressive disclosure means each layer adds specificity. Requirements are generic. Design adapts to system. Sequencing decomposes work. Implementation specifies every action. Don't skip the bridge (Research & Design) - it's where generic becomes executable.

Search AI Tools

enforcing-development-workflow

Install this agent skill to your Project

SKILL.md