Workflow Complexity Reduction Initiative

[github-actions]

Problem

Several agentic workflows have grown to excessive complexity (600+ lines), making them difficult to maintain, debug, and test. Large workflows have multiple concerns mixed together, increasing cognitive load and reducing code quality.

Workflows Needing Refactoring

Workflow	Lines	Priority
copilot-session-insights.md	748	HIGH
ci-coach.md	725	HIGH
daily-copilot-token-report.md	680	MEDIUM
prompt-clustering-analysis.md	639	MEDIUM
developer-docs-consolidator.md	623	MEDIUM

Recommended Approach

1. Extract Common Functionality

• Move reusable components to .github/workflows/shared/
• Create focused include files for specific capabilities
• Use imports: to compose workflows from modules

2. Split by Concern

• Separate data collection from analysis
• Separate analysis from reporting
• Use workflow chaining for multi-phase operations

3. Maximum Size Guidelines

• Target: 400-500 lines maximum per workflow
• Ideal: 200-300 lines for most workflows
• Hard limit: 600 lines (refactor above this)

Refactoring Template

# Before (750 lines)
---
description: Large monolithic workflow
---
[... 750 lines of mixed concerns ...]

# After (3 focused workflows)

# workflow-1-collect.md (200 lines)
---
description: Data collection phase
imports:
  - shared/data-collectors.md
---
[... focused collection logic ...]

# workflow-2-analyze.md (250 lines)
---
description: Analysis phase
imports:
  - shared/analytics.md
  - shared/trending-charts.md
---
[... focused analysis logic ...]

# workflow-3-report.md (150 lines)
---
description: Reporting phase
imports:
  - shared/reporting.md
---
[... focused reporting logic ...]

Success Criteria

• All workflows reduced to < 600 lines
• No single workflow has > 3 distinct concerns
• Shared functionality extracted to reusable includes
• Each workflow has clear, focused purpose
• Documentation updated with refactoring patterns

Expected Benefits

• Maintainability: +20 points (easier to understand and update)
• Testability: +15 points (smaller units to test)
• Reusability: +25 points (shared includes benefit multiple workflows)
• Debugging: +30 points (easier to isolate issues)

Estimated Effort

• Per workflow: 4-8 hours
• Total for 5 workflows: 20-40 hours (2-5 days)

Implementation Plan

1. Phase 1 (Week 1-2): Refactor copilot-session-insights.md and ci-coach.md
2. Phase 2 (Week 3-4): Refactor daily-copilot-token-report.md and prompt-clustering-analysis.md
3. Phase 3 (Week 5): Refactor developer-docs-consolidator.md
4. Phase 4 (Week 6): Document refactoring patterns and create guidelines

Related

• Agent Performance Report: [Discussion Link]
• Part of technical debt reduction initiative
• Supports long-term maintainability goals

---

Source: Agent Performance Analyzer
Priority: HIGH
Category: Technical Debt
Impact: High (affects maintainability of 5 critical workflows)

AI generated by Agent Performance Analyzer - Meta-Orchestrator