Gap Recommendations

Gap Recommendations

Detailed specifications for missing capabilities identified in workflow coverage analysis.

Gap Summary by Stage

Stage 1: INPUT RECEPTION (⚠️ Partial)
├── Gap: Task classification/routing
├── Gap: Priority assignment
└── Gap: Request type detection

Stage 2: CONTEXT GATHERING (✅ Covered)
└── Gap: Context caching

Stage 3: PLANNING (✅ Covered)
├── Gap: Complexity estimation
└── Gap: Effort prediction

Stage 4: EXECUTION (✅ Covered)
├── Gap: Error recovery
├── Gap: Rollback mechanism
└── Gap: Retry logic

Stage 5: VERIFICATION (✅ Strongest)
└── Gap: Performance verification

Stage 6: OUTPUT DELIVERY (⚠️ Partial)
├── Gap: PR workflow
├── Gap: Changelog generation
└── Gap: Release notes

Priority Matrix

P1: High Priority Gaps

Gap: Task Classification & Routing

Stage: Input Reception

Current State: Tasks are manually classified by the orchestrator based on pattern matching.

Problem: No systematic way to:

• Categorize incoming requests
• Route to appropriate workflow
• Assign default priority
• Detect task type (bug, feature, refactor, research)

Proposed Solution: task-classifier skill

name: task-classifier
description: Classify incoming tasks by type, complexity, and route to appropriate workflow
triggers:
  - New task received
  - User request ambiguous
  - Workflow selection needed

Specification:

INPUT: Raw user request

CLASSIFICATION DIMENSIONS:
1. Type: bug | feature | refactor | research | documentation | configuration
2. Complexity: simple | moderate | complex
3. Scope: single-file | multi-file | cross-module | system-wide
4. Domain: code | infrastructure | documentation | testing

OUTPUT:
- Recommended workflow (simple, full, investigation)
- Suggested assets to load
- Estimated delegation needs
- Risk assessment

Example Behavior:

flowchart TD
    INPUT["User: Fix the login bug"]

    C1{"Contains error<br/>keywords?"}
    C2{"Scope<br/>specified?"}
    C3{"Reproduction<br/>steps given?"}

    CLASS["Classification:<br/>Type: bug<br/>Complexity: unknown<br/>Workflow: investigation"]

    INPUT --> C1
    C1 -->|"Yes"| C2
    C2 -->|"No"| C3
    C3 --> CLASS

Gap: Error Recovery & Rollback

Stage: Execution

Current State: When sub-agents fail, the orchestrator must manually handle recovery.

Problem: No systematic way to:

• Detect failed operations
• Rollback partial changes
• Retry with different approach
• Escalate appropriately

Proposed Solution: error-recovery skill + enhancements to subagent-contract

name: error-recovery
description: Handle execution failures with structured recovery strategies
triggers:
  - Agent returns BLOCKED
  - Tool execution fails
  - Verification reveals errors

Specification:

RECOVERY STRATEGIES:
1. Retry (transient failures)
   - Max retries: 3
   - Backoff: exponential
   - Conditions: network, timeout, rate-limit

2. Rollback (partial completion)
   - Track changes made
   - Reverse in LIFO order
   - Verify rollback success

3. Alternative (different approach)
   - Identify alternative agents
   - Try different decomposition
   - Escalate if no alternatives

4. Escalate (unrecoverable)
   - Document what was tried
   - Explain blocker clearly
   - Request user guidance

Example Behavior:

flowchart TD
    FAIL["Agent returns<br/>BLOCKED"]

    Q1{"Transient<br/>failure?"}
    Q2{"Rollback<br/>possible?"}
    Q3{"Alternative<br/>available?"}

    RETRY["Retry with<br/>backoff"]
    ROLLBACK["Rollback<br/>changes"]
    ALTERNATE["Try<br/>alternative"]
    ESCALATE["Escalate to<br/>user"]

    FAIL --> Q1
    Q1 -->|"Yes"| RETRY
    Q1 -->|"No"| Q2
    Q2 -->|"Yes"| ROLLBACK
    Q2 -->|"No"| Q3
    Q3 -->|"Yes"| ALTERNATE
    Q3 -->|"No"| ESCALATE

P2: Medium Priority Gaps

Gap: PR Workflow

Stage: Output Delivery

Current State: git-commit-helper assists with commits, but PR creation is manual.

Problem: No systematic way to:

• Create pull requests from commits
• Generate PR descriptions
• Link to related issues
• Request reviewers

Proposed Solution: pr-workflow skill

name: pr-workflow
description: Create and manage pull requests with proper descriptions and linking
triggers:
  - Task completion with commits
  - User requests PR creation
  - Branch ready for review

Specification:

PR CREATION FLOW:
1. Analyze commits on branch
2. Generate description from commit messages
3. Link related issues (if mentioned)
4. Suggest reviewers (if configured)
5. Create PR via gh CLI
6. Report PR URL

DESCRIPTION TEMPLATE:
## Summary
[Auto-generated from commits]

## Changes
[List of modified files with brief descriptions]

## Testing
[Inferred from test file changes]

## Related Issues
[Extracted from commit messages]

Example Behavior:

sequenceDiagram
    participant O as Orchestrator
    participant PR as pr-workflow
    participant GH as gh CLI

    O->>PR: Create PR for feature branch
    PR->>GH: git log main..HEAD
    GH-->>PR: Commit list
    PR->>PR: Generate description
    PR->>GH: gh pr create
    GH-->>PR: PR URL
    PR-->>O: PR created: [URL]

Gap: Changelog Generation

Stage: Output Delivery

Current State: No automated changelog from commits.

Problem: No systematic way to:

• Generate changelog entries
• Categorize by type (feat, fix, etc.)
• Link to commits/PRs
• Format for various audiences

Proposed Solution: changelog-generator command

name: changelog-generator
description: Generate changelog entries from conventional commits
triggers:
  - User invokes /changelog
  - Release preparation

Specification:

INPUT: Git commit range (default: since last tag)

PROCESS:
1. Parse conventional commit messages
2. Categorize by type (feat, fix, docs, etc.)
3. Extract scope and description
4. Link to commit SHAs
5. Format as markdown

OUTPUT:
## [Version] - YYYY-MM-DD

### Added
- feat(scope): description (#commit)

### Fixed
- fix(scope): description (#commit)

### Changed
- refactor(scope): description (#commit)

P3: Lower Priority Gaps

Gap: Complexity Estimation

Stage: Planning

Current State: Complexity is assessed manually during planning.

Problem: No systematic way to:

• Estimate task complexity
• Predict effort required
• Identify risk factors
• Compare approaches

Proposed Solution: complexity-estimator skill

name: complexity-estimator
description: Estimate task complexity based on codebase analysis
triggers:
  - Planning phase
  - Multiple approaches possible
  - Effort assessment needed

Specification:

COMPLEXITY FACTORS:
1. Files affected (count, coupling)
2. Lines of code (estimated changes)
3. Dependencies (internal, external)
4. Test coverage requirements
5. Documentation needs
6. Risk of regression

OUTPUT:
- Complexity score: 1-10
- Confidence: high/medium/low
- Key risk factors
- Recommended approach

Gap: Context Caching

Stage: Context Gathering

Current State: Context is re-gathered each session.

Problem: No systematic way to:

• Cache frequently-used context
• Persist across sessions
• Invalidate on changes
• Share between agents

Proposed Solution: context-cache hook + storage

name: context-cache
description: Cache and restore frequently-accessed context
triggers:
  - Session start (restore)
  - Context gathered (store)
  - Files changed (invalidate)

Specification:

CACHE STRUCTURE:
.claude/cache/
├── context/
│   ├── [hash].json  # Cached context
│   └── index.json   # Cache metadata

OPERATIONS:
- store(key, context, ttl)
- retrieve(key) → context | null
- invalidate(pattern)
- cleanup(max_age)

INVALIDATION TRIGGERS:
- File modified that context references
- TTL expired
- Manual invalidation

P4: Future Considerations

Gap: Performance Verification

Stage: Verification

Current State: No automated performance testing.

Problem: Changes may degrade performance without detection.

Proposed Solution: Performance benchmarking integration (future)

CONCEPT:
- Define performance baselines
- Run benchmarks after changes
- Compare to baselines
- Flag regressions

SCOPE: Out of scope for current plugin

Implementation Roadmap

gantt
    title Gap Implementation Roadmap
    dateFormat  YYYY-MM-DD
    section P1
    task-classifier     :p1a, 2025-01-22, 3d
    error-recovery      :p1b, after p1a, 5d
    section P2
    pr-workflow         :p2a, after p1b, 3d
    changelog-generator :p2b, after p2a, 2d
    section P3
    complexity-estimator :p3a, after p2b, 3d
    context-cache        :p3b, after p3a, 5d

Verification Checklist

When implementing gaps:

• Asset follows repository conventions
• Integrates with existing workflow stages
• Has clear triggers and outputs
• Includes tests/validation
• Documentation updated
• Workflow diagrams updated

Navigation

• Previous: RAG Retrieval Pattern
• Back to: Index