workflow-management

name	workflow-management
description	Streamline PayK12 development workflows with intelligent coordination, cost optimization, and continuous feedback loops. Use when orchestrating multi-step tasks, monitoring workflow health, or optimizing development processes across repositories.

PayK12 Workflow Management

Streamline development workflows across the PayK12 multi-repository system with intelligent task coordination, cost tracking, and continuous improvement feedback. This skill provides patterns for workflow optimization, monitoring, and automation.

When to Use This Skill

• Monitoring /bug-fix command execution and success rates
• Analyzing token usage and cost optimization opportunities
• Coordinating multi-step tasks across repositories
• Tracking workflow health metrics and improvements
• Implementing workflow automation strategies
• Planning sprint work and task allocation
• Analyzing performance bottlenecks
• Managing developer productivity

When NOT to Use

• For specific repository development → Use repository-specific skills
• For infrastructure/deployment → Invoke cloud-architect or deployment-engineer
• For individual feature development → Use nextjs-pro, dotnet-pro agents
• For security concerns → Invoke security-auditor agent

Quick Reference

Workflow System Overview

PayK12 Workflow Stack:
├── /bug-fix command (2120+ lines)
│   ├── Phase 1: Analysis
│   ├── Phase 2: Reproduction (Playwright)
│   ├── Phase 3: Implementation
│   ├── Phase 4: Testing
│   └── Phase 5: PR Creation
├── Session logging & cost tracking
├── Agent dispatch & coordination
└── Continuous improvement feedback

Key Metrics to Track

1. Success Rate: % of workflows that complete without manual intervention
2. Iteration Count: Average iterations per bug fix (target: 1-2)
3. Cost Per Bug: Total tokens used divided by bugs fixed
4. Time Per Bug: Wall-clock time from start to merge
5. Agent Utilization: Which agents are most frequently used
6. Context Cache Hit Rate: Cached vs. fresh context loads
7. Token Efficiency: Tokens used per artifact generated

Core Workflow Patterns

Pattern 1: Automated Bug Fix Workflow

The /bug-fix Command Flow:

User: /bug-fix PL-479

1. ANALYSIS PHASE
   ├─ Parse JIRA ticket PL-479
   ├─ Extract requirements
   ├─ Identify repository scope
   ├─ Assess complexity
   └─ Create execution plan

2. REPRODUCTION PHASE
   ├─ Generate test case for bug
   ├─ Run Playwright tests (should fail)
   ├─ Capture failure evidence
   ├─ Document reproduction steps
   └─ Create test baseline

3. IMPLEMENTATION PHASE
   ├─ Dispatch to appropriate agent
   │  ├─ dotnet-pro for API changes
   │  ├─ nextjs-pro for frontend changes
   │  ├─ legacy-modernizer for legacy changes
   │  └─ multi-repo-fixer for cross-repo
   ├─ Implement fix
   ├─ Run local tests
   └─ Update documentation

4. TESTING PHASE
   ├─ Run Playwright tests (should pass)
   ├─ Run unit tests
   ├─ Run integration tests
   ├─ Check code coverage
   └─ Verify no regressions

5. PR CREATION PHASE
   ├─ Create merge request with:
   │  ├─ Clear description
   │  ├─ Testing evidence
   │  ├─ Screenshots/traces if applicable
   │  └─ Auto-link to JIRA ticket
   ├─ Post CI/CD results
   ├─ Wait for reviews
   └─ Merge when approved

FEEDBACK & ITERATION (up to 3 times)
   ├─ Monitor test failures
   ├─ Self-heal common issues
   ├─ Provide diagnostic information
   └─ Attempt auto-fix or escalate

Success Indicators:

• ✅ All tests pass (Playwright, unit, integration)
• ✅ No code coverage regression
• ✅ PR successfully created and auto-linked
• ✅ Documentation updated
• ✅ No manual intervention needed

Pattern 2: Cost Optimization Workflow

Token Usage Breakdown:

Average Cost Per Bug Fix:

Context Loading:        25,000 tokens (35%)
  ├─ Architecture context
  ├─ Repository structure
  ├─ Existing patterns
  └─ Test infrastructure

Analysis Phase:          12,000 tokens (17%)
  ├─ JIRA ticket parsing
  ├─ Code review
  └─ Planning

Reproduction Phase:       8,000 tokens (11%)
  ├─ Test generation
  ├─ Test execution analysis
  └─ Evidence capture

Implementation Phase:    18,000 tokens (25%)
  ├─ Code writing
  ├─ Local testing
  └─ Refinement

Testing Phase:            5,000 tokens (7%)
  ├─ Test monitoring
  ├─ Result analysis
  └─ Coverage check

Total Average:           70,000 tokens (~$2.10/bug fix)

Optimization Opportunities:
├─ Cache context (save 35% → 25,000 tokens)
├─ Reuse test patterns (save 20% of reproduction)
├─ Parallel execution (reduce wall-clock time 30%)
└─ Early termination on simple bugs

Optimization Strategies:

1. Context Caching (saves 8,750 tokens per workflow):

Before: Load context fresh each time
Cost: 25,000 tokens per bug

After: Cache and reuse context
Cost: 16,250 tokens (35% savings)

Action: Implement context-manager agent
Timeline: 6 weeks
ROI: Break-even after 5 bugs

2. Parallel Execution (saves 30% wall-clock time):

Before: Sequential phases (1 → 2 → 3 → 4 → 5)
Time: ~45 minutes per bug

After: Parallel where possible
- Phase 2 & 3 overlap (testing while implementing)
- Phase 1 & 2 analysis done in parallel
Time: ~30 minutes per bug

Implementation: Update /bug-fix workflow
Timeline: 1 week
Impact: 15 more bugs/day throughput

3. Pattern Reuse (saves tokens, improves speed):

First IDOR vulnerability:  70,000 tokens
Second IDOR vulnerability: 35,000 tokens (50% savings)
  └─ Reuse test patterns and fixes

Action: Build pattern library for common bug types
Timeline: 2 weeks (after 10-15 bugs)
Savings: ~30% average cost reduction

Pattern 3: Workflow Health Monitoring

Health Score Calculation:

Overall Workflow Health = (S × 0.3) + (I × 0.25) + (C × 0.2) + (A × 0.25)

Where:
S = Success Rate (target: 95%+)
I = Iteration Efficiency (1-2 iterations ideal)
C = Cost Efficiency (tokens per bug)
A = Agent Accuracy (code quality)

Health Score Interpretation:
90-100 = Excellent ✅ (no action needed)
80-90  = Good ⚠️ (monitor, optimize when needed)
70-80  = Fair ⚠️ (identify bottlenecks)
< 70   = Poor ❌ (investigation required)

Metrics Dashboard:

Last 30 Days Summary:
├─ Bugs Fixed: 47
├─ Success Rate: 91.5% (43/47)
├─ Avg Iterations: 1.4
├─ Avg Cost: $2.15 per bug
├─ Total Cost: $101.05
├─ Avg Time: 38 minutes
├─ Agent Accuracy: 94%
└─ Context Cache Hit Rate: 62%

Trend Analysis:
├─ Cost trending down (-12% vs prev month)
├─ Success rate improving (+5%)
├─ Speed improving (-7 min avg time)
└─ Cache efficiency improving (+8%)

Recommendations:
├─ Deploy context-manager (projected 35% cost savings)
├─ Implement parallel execution (30% speed improvement)
├─ Build IDOR pattern library (50% cost savings for security bugs)
└─ Add code review agent (improve accuracy to 98%)

Estimated Impact (if all implemented):
├─ Cost: $101/month → $52/month (48% savings)
├─ Speed: 38 min → 26 min (31% faster)
├─ Success: 91% → 97% (+6%)
└─ Throughput: 47 bugs → 72 bugs (+53%)

Multi-Repository Coordination

Cross-Repository Bug Fixes

Scenario: Bug requires changes in multiple repositories

Bug: Contact creation fails because validation differs between frontend and API

Step 1: Analysis
├─ Identify affected repositories:
│  ├─ repos/frontend (React validation)
│  ├─ repos/api (C# validation)
│  └─ repos/legacy-api (legacy validation)
├─ Find root cause (one has different rules)
└─ Plan synchronization strategy

Step 2: Design Solution
├─ Decide on source of truth:
│  ├─ Option A: Shared validation schema
│  ├─ Option B: One repo leads, others follow
│  └─ Option C: Message-based synchronization
└─ Determine update order

Step 3: Implementation Order
├─ First: Backend (API) - source of truth
├─ Second: Frontend (React) - sync with API
└─ Third: Legacy API - gradual migration

Step 4: Testing
├─ Test API validation changes
├─ Test Frontend integration with new API
├─ Test Legacy API still works (compatibility mode)
└─ End-to-end workflow test

Step 5: Deployment
├─ Deploy API changes first
├─ Monitor for issues
├─ Deploy frontend changes
├─ Monitor E2E tests
└─ Plan legacy-API deprecation

Coordination Patterns

Pattern 1: Sequential Deployment

repo/api → repo/frontend → (later) repos/legacy-api
Used when: Backward compatibility needed
Risk: Low (version gating)
Speed: Slower (staggered deploys)

Pattern 2: Parallel Deployment

repo/api ─┐
          ├─→ repo/frontend
repos/legacy-api ─┘
Used when: Breaking changes or major refactor
Risk: Medium (coordination required)
Speed: Faster (parallel work)

Pattern 3: Feature Flag Driven

Deploy all changes with flags OFF
Enable flags gradually per region/user
Rollback by disabling flags
Used when: Zero-downtime deployment needed
Risk: Low (easy rollback)
Speed: Medium (flag toggling)

Automation & Self-Healing

Auto-Healing Strategy

Tier 1: Deterministic Fixes (High confidence)

Issue: Formatting violations
Fix: Auto-apply prettier/eslint
Confidence: 100%
Action: Auto-commit, notify user

Issue: Missing nullable type annotations
Fix: Add ? to type signature
Confidence: 98%
Action: Suggest, wait for approval

Tier 2: Heuristic Fixes (Medium confidence)

Issue: Test failing on assertion
Fix: Suggest mock adjustment
Confidence: 75%
Action: Create PR with suggestion, wait for review

Issue: API endpoint not found
Fix: Check version mismatch, suggest compatibility mode
Confidence: 70%
Action: Log issue, escalate to human

Tier 3: Manual Escalation (Low confidence)

Issue: Unexpected algorithm behavior
Fix: Escalate to human with diagnostics
Confidence: < 50%
Action: Provide full context, request human decision

Issue: Design decision conflict
Fix: Escalate with alternatives
Confidence: < 40%
Action: Request human judgment

Best Practices

DO ✅

• Monitor workflow metrics regularly (weekly)
• Implement incremental improvements (1 per sprint)
• Cache reusable context and patterns
• Run cost analysis monthly
• Maintain improvement backlog
• Document successful patterns
• Share patterns across team
• Automate repetitive tasks
• Monitor agent accuracy
• Plan for scale growth

DON'T ❌

• Don't ignore efficiency metrics
• Don't over-engineer before measuring
• Don't skip documentation
• Don't lose track of costs
• Don't implement all optimizations at once
• Don't ignore team feedback
• Don't assume one size fits all bugs
• Don't forget to measure improvements
• Don't create technical debt for speed
• Don't forget to update patterns

Related Resources

• Bug Fix Automation: /bug-fix command (2120+ lines)
• Session Tracking: log-session.sh script
• Context Management: context-manager-integration-plan.md
• Agent Coordination: agent-organizer agent

Troubleshooting

Issue	Indicator	Solution
High costs	> $3/bug average	Analyze token usage, implement caching
Low success rate	< 85% pass rate	Review agent accuracy, add patterns
Slow execution	> 60 min avg time	Profile phases, parallelize where possible
Cache misses	< 50% hit rate	Expand cache policies, reuse patterns
Manual escalations	> 10% of bugs	Improve auto-healing heuristics

Getting Help

For workflow optimization:

• Invoke product-manager agent for strategy
• Invoke performance-engineer for bottleneck analysis
• Invoke agent-organizer for coordination issues
• Check /docs/workflow-engine-guide.md for advanced topics