workflow-optimizer Purpose
Guide users through the SDD workflow by determining current position, recommending next steps, identifying parallel work opportunities, and tracking progress.
Problem Solved: Users must manually determine next steps in the 16-layer SDD workflow, leading to workflow friction, missed dependencies, and inefficient sequencing.
Solution: Analyze completed artifacts, determine workflow position, and provide prioritized recommendations for next steps with clear rationale.
When to Use This Skill
Use workflow-optimizer when:
Completed an artifact and need guidance on next steps Starting documentation and need workflow overview Want to identify parallel work opportunities Need progress report on documentation completion Unsure which artifacts to create next
Do NOT use when:
Need skill recommendation for specific task (use skill-recommender) Need project context (use context-analyzer) Validating artifacts (use trace-check or quality-advisor) Skill Inputs Input Type Required Description project_root string Yes Root path of project to analyze completed_artifact string No ID of just-completed artifact (e.g., PRD-00) focus_area string No Optional filter: "core-workflow", "quality", "planning" Skill Workflow Step 1: Analyze Project State
Scan project to determine documentation status:
Artifact Discovery:
Discover all artifacts
find {project_root}/docs -name ".md" -o -name ".yaml" -o -name "*.feature"
Status Extraction: Extract status from Document Control section:
Draft In Review Approved Superseded Deprecated
Project State Model:
project_state: scan_timestamp: 2025-11-29T14:30:00Z artifacts_by_type: BRD: total: 3 approved: 2 draft: 1 latest: BRD-03 PRD: total: 2 approved: 1 draft: 1 latest: PRD-00 EARS: total: 0 # ... etc total_artifacts: 25 approved_artifacts: 18 draft_artifacts: 7
Step 2: Determine Workflow Position
Map artifacts to SDD workflow layers:
Layer Definition:
workflow_layers: layer_1: type: BRD name: Business Requirements prerequisite: null description: "Business objectives and stakeholder needs"
layer_2: type: PRD name: Product Requirements prerequisite: BRD description: "Product features and user needs"
layer_3: type: EARS name: Formal Requirements prerequisite: PRD description: "WHEN-THE-SHALL formal requirements"
layer_4: type: BDD name: Behavior Tests prerequisite: EARS description: "Gherkin acceptance scenarios"
layer_5: type: ADR name: Architecture Decisions prerequisite: BDD description: "Technical decision records"
layer_6: type: SYS name: System Requirements prerequisite: ADR description: "Technical system specifications"
layer_7: type: REQ name: Atomic Requirements prerequisite: SYS description: "Detailed atomic requirements"
layer_8: type: IMPL name: Implementation Plan prerequisite: REQ optional: true description: "WHO/WHEN project management"
layer_9: type: CTR name: Interface Contracts prerequisite: [IMPL, REQ] optional: true description: "API contracts and schemas"
layer_10: type: SPEC name: Technical Specifications prerequisite: REQ description: "YAML implementation specs"
layer_11: type: TASKS name: Implementation Tasks prerequisite: SPEC description: "Code generation task lists - flows to Code layer"
Position Calculation:
workflow_position: completed_layers: [1, 2] # BRD, PRD done in_progress_layers: [3] # EARS in progress blocked_layers: [4, 5, 6, 7, 10, 11] # Waiting on prerequisites ready_layers: [3] # Can start now optional_ready: [8, 9] # Optional, prereqs met
current_position: layer: 3 type: EARS status: in_progress
progress_percentage: 18% # 2 of 11 layers complete
Step 3: Identify Required Next Steps
Determine mandatory next artifacts:
Dependency Analysis:
dependency_graph: PRD-00: completed: true downstream_required: - EARS (Layer 3) - formal requirements - BDD (Layer 4) - test scenarios downstream_optional: - IMPL (Layer 8) - if complex project
EARS (to be created): upstream_required: - PRD-00 ✓ (completed) will_enable: - BDD (Layer 4) - ADR (Layer 5)
Next Steps Priority:
Priority Artifact Rationale P0 EARS Required downstream from PRD, blocks BDD and ADR P1 BDD Can start once EARS begun, enables ADR P2 ADR Requires BDD completion Step 4: Identify Parallel Opportunities
Find work that can proceed in parallel:
Parallelization Rules:
parallel_opportunities: rule_1: name: "EARS and BDD overlap" condition: "EARS in progress" parallel_work: "BDD scenarios for completed EARS" benefit: "Faster progress through testing layer"
rule_2: name: "Multiple feature tracks" condition: "Multiple BRDs exist" parallel_work: "PRD for each BRD" benefit: "Parallel feature development"
rule_3: name: "ADR independence" condition: "Technical decisions needed" parallel_work: "ADRs can be written in parallel" benefit: "Architecture decisions don't block each other"
Parallel Work Output:
parallel_opportunities: can_parallelize: - track: "Feature A" current: EARS-01 parallel: "Start BDD-01 scenarios for EARS-01 requirements"
- track: "Feature B"
current: PRD-00 complete
parallel: "Start EARS-02 while Feature A progresses"
blocked_parallelization: - item: "SPEC creation" blocker: "REQ layer incomplete" unblock_by: "Complete REQ-01 through REQ-05"
Step 5: Calculate Progress Metrics
Generate progress report:
Progress Metrics:
progress_report: overall: layers_complete: 2 total_layers: 12 percentage: 17%
by_layer: - layer: 1 (BRD) status: complete artifacts: 3 approved: 2
- layer: 2 (PRD)
status: complete
artifacts: 2
approved: 1
- layer: 3 (EARS)
status: in_progress
artifacts: 0
target: 3 (based on PRD features)
- layer: 4 (BDD)
status: blocked
blocker: "EARS incomplete"
estimated_remaining: artifacts: 25 layers: 10
critical_path: - EARS (blocks BDD) - BDD (blocks ADR) - REQ (blocks SPEC) - SPEC (blocks TASKS)
Step 6: Generate Recommendations
Provide actionable next-step guidance:
Recommendation Format:
recommendations: context: completed_artifact: PRD-00 workflow_position: Layer 2 complete progress: 17%
next_steps: - priority: P0 action: "Create EARS document" artifact_type: EARS skill: doc-ears rationale: "Required downstream from PRD-00. EARS formalizes product features into WHEN-THE-SHALL requirements." estimated_effort: "Medium (2-4 hours)" blocks: [BDD, ADR]
- priority: P1
action: "Start BDD scenarios"
artifact_type: BDD
skill: doc-bdd
rationale: "Can begin once EARS started. Write scenarios for completed requirements."
estimated_effort: "Medium (2-4 hours)"
parallel_with: EARS
- priority: P2
action: "Consider ADR for key decisions"
artifact_type: ADR
skill: doc-adr
rationale: "If architectural decisions needed, document early. Requires BDD completion."
estimated_effort: "Low-Medium (1-3 hours)"
condition: "After BDD progress"
parallel_opportunities: - "Feature B: Start PRD-03 while Feature A progresses through EARS/BDD" - "Technical: Draft ADRs for known architecture decisions"
blocked_items: - item: "SPEC creation" reason: "Requires REQ completion (Layer 7)" unblock_path: "Complete layers 3-7 first"
workflow_guidance: current_focus: "EARS creation for PRD-00 features" short_term: "Complete EARS → BDD → ADR sequence" medium_term: "Progress through SYS → REQ → SPEC"
progress_summary: completed: "BRD-01, BRD-02, BRD-03, PRD-01, PRD-00" in_progress: "None" next_milestone: "Complete Layer 3 (EARS)" overall: "17% complete (2/12 layers)"
Example Usage Example 1: Post-PRD Guidance
User Request: "I just finished PRD-00, what should I do next?"
Workflow Recommendations:
completed: PRD-00 position: Layer 2 complete
next_steps: 1. Create EARS-01 (P0) - Formalize PRD-00 features into WHEN-THE-SHALL requirements - Run: /skill doc-ears
- Start BDD scenarios (P1)
- Can begin once EARS requirements defined
- Run: /skill doc-bdd
parallel_opportunity: "If other BRDs exist, you can create their PRDs in parallel"
progress: "17% → 25% after EARS completion"
Example 2: Project Overview
User Request: "Where am I in the documentation workflow?"
Workflow Status:
project_status: completed_layers: - Layer 1 (BRD): 3 documents ✓ - Layer 2 (PRD): 2 documents ✓
in_progress: - Layer 3 (EARS): 0 documents, target 5
blocked: - Layers 4-11: Waiting on upstream completion
progress: 18%
critical_path: EARS → BDD → ADR → SYS → REQ → SPEC → TASKS
recommended_focus: "Complete EARS layer to unblock BDD and ADR"
Example 3: Parallel Work Identification
User Request: "What can I work on in parallel?"
Parallel Opportunities:
current_tracks: track_a: name: "Core Platform" position: EARS creation next: BDD scenarios
track_b: name: "Partner Integration" position: BRD complete next: PRD creation (independent of Track A)
parallel_work: - "Track B PRD can proceed while Track A completes EARS" - "ADRs for known decisions can be drafted early" - "BDD scenarios can start once first EARS requirements defined"
sequential_requirements: - "SPEC requires REQ completion - no parallel path" - "TASKS requires SPEC - sequential"
Integration with Other Skills Integration Description context-analyzer Provides artifact inventory and traceability data skill-recommender Receives workflow position for better skill suggestions doc-flow Can be invoked by doc-flow for workflow orchestration project-mngt Shares planning concepts (MVP, phases) Quality Gates Definition of Done Project state analyzed Workflow position calculated Next steps prioritized (P0, P1, P2) Parallel opportunities identified Progress metrics calculated Actionable recommendations generated Performance Targets Metric Target Analysis latency <1s for 50 artifacts Recommendation generation <500ms Progress calculation <200ms Traceability
Required Tags:
@prd: PRD.000.004 @adr: ADR-000
Upstream Sources Source Type Reference PRD-00 Product Requirements PRD-00 ADR-000 Architecture Decision ADR-000 Downstream Artifacts Artifact Type Reference doc-flow Skill Consumer Workflow orchestration project-mngt Skill Consumer Release planning integration Version Information
Version: 1.0.0 Created: 2025-11-29 Status: Active Author: AI Dev Flow Framework Team