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"

  layer_12:
    type: IPLAN
    name: Execution Plans
    prerequisite: TASKS
    description: "Session-based execution plans"

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, 12]  # 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: 17%  # 2 of 12 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

  2. 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-12: Waiting on upstream completion

  progress: 17%

  critical_path:
    EARS → BDD → ADR → SYS → REQ → SPEC → TASKS → IPLAN

  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