gap-analysis-workflow

name: gap-analysis-workflow
description: Identify capability gaps and propose new skills with prioritization. Use when analyzing missing capabilities, planning skill development, performing ontology expansion, or assessing coverage.
argument-hint: "[goal] [scope] [constraints]"
disable-model-invocation: false
user-invocable: true
allowed-tools: Read, Grep, Bash, Edit, Git, Web
context: fork
agent: general-purpose

Intent

Run the composed workflow gap-analysis-workflow using atomic capability skills to systematically identify what capabilities are missing and prioritize their development.

Success criteria:
- Current capability coverage mapped with evidence
- Gaps identified with clear justification
- Relationships between existing and missing capabilities documented
- Prioritized roadmap for new skill development
- Audit trail of analysis process

Compatible schemas:
- docs/schemas/capability_ontology.yaml
- docs/schemas/workflow_catalog.yaml

Inputs

Procedure

0) Create checkpoint marker if mutation might occur:
- Create .claude/checkpoint.ok after confirming rollback strategy

1) Invoke /inspect and store output as inspect_out
- Examine current capability landscape and documentation

2) Invoke /map-relationships and store output as map-relationships_out
- Map dependencies and connections between existing capabilities

3) Invoke /discover-relationship and store output as discover-relationship_out
- Identify implicit relationships and missing links

4) Invoke /compare-plans and store output as compare-plans_out
- Compare current state against ideal or reference ontology

5) Invoke /prioritize and store output as prioritize_out
- Rank gaps by impact, effort, and strategic value

6) Invoke /generate-plan and store output as generate-plan_out
- Create development roadmap for new capabilities

7) Invoke /audit and store output as audit_out
- Record analysis process and evidence

Output Contract

Return a structured object:

workflow_id: string  # Unique analysis execution ID
goal: string  # Analysis objective
status: completed | partial | failed
current_state:
  capabilities_analyzed: integer
  coverage_percentage: number  # 0.0-1.0
  layers_covered: array[string]
  evidence_anchors: array[string]
gaps_identified:
  total: integer
  by_layer:
    perception: array[string]
    modeling: array[string]
    reasoning: array[string]
    action: array[string]
    safety: array[string]
    meta: array[string]
  by_priority:
    critical: array[string]
    high: array[string]
    medium: array[string]
    low: array[string]
  evidence_anchors: array[string]
relationships:
  existing_dependencies: array[object]
  missing_connections: array[object]
  orphan_capabilities: array[string]
  evidence_anchors: array[string]
comparison:
  reference_ontology: string
  alignment_score: number  # 0.0-1.0
  divergences: array[string]
  evidence_anchors: array[string]
roadmap:
  phases: array[object]
  total_new_skills: integer
  estimated_effort: string
  dependencies: array[object]
  evidence_anchors: array[string]
audit:
  log_path: string
  methodology: string
  evidence_anchors: array[string]
confidence: number  # 0.0-1.0
evidence_anchors: array[string]
assumptions: array[string]

Field Definitions

Examples

Example 1: Gap Analysis for Autonomous Code Review

Input:

goal: "Identify gaps for fully autonomous code review capability"
scope:
  - "reasoning"
  - "safety"
  - "action"
constraints:
  max_new_skills: 10
  priority_criteria:
    - "security_impact"
    - "automation_potential"
reference_ontology: "schemas/capability_ontology.yaml"

Output:

workflow_id: "gap_20240115_120000_codereview"
goal: "Identify gaps for fully autonomous code review capability"
status: completed
current_state:
  capabilities_analyzed: 45
  coverage_percentage: 0.72
  layers_covered:
    - "reasoning"
    - "safety"
    - "action"
  evidence_anchors:
    - "file:schemas/capability_ontology.yaml"
    - "file:skills/critique/SKILL.md"
gaps_identified:
  total: 8
  by_layer:
    perception: []
    modeling:
      - "detect-code-smell"
      - "identify-security-pattern"
    reasoning:
      - "compare-implementations"
      - "evaluate-test-coverage"
    action:
      - "generate-review-comment"
      - "apply-suggested-fix"
    safety:
      - "verify-no-regression"
      - "constrain-auto-merge"
    meta: []
  by_priority:
    critical:
      - "verify-no-regression"
      - "identify-security-pattern"
    high:
      - "detect-code-smell"
      - "constrain-auto-merge"
    medium:
      - "compare-implementations"
      - "generate-review-comment"
    low:
      - "evaluate-test-coverage"
      - "apply-suggested-fix"
  evidence_anchors:
    - "file:schemas/capability_ontology.yaml:nodes"
    - "tool:compare-plans:coverage_analysis"
relationships:
  existing_dependencies:
    - from: "critique"
      to: "evaluate"
      type: "requires"
    - from: "plan"
      to: "critique"
      type: "soft_requires"
  missing_connections:
    - from: "detect-code-smell"
      to: "critique"
      type: "should_precede"
      reason: "Code smells inform critique priorities"
    - from: "verify-no-regression"
      to: "act-plan"
      type: "must_follow"
      reason: "Regression check required after any code change"
  orphan_capabilities: []
  evidence_anchors:
    - "tool:map-relationships:dependency_graph"
    - "tool:discover-relationship:implicit_links"
comparison:
  reference_ontology: "schemas/capability_ontology.yaml"
  alignment_score: 0.72
  divergences:
    - "Missing specialized detection capabilities for code patterns"
    - "No automated fix application in action layer"
    - "Regression verification not formalized"
  evidence_anchors:
    - "tool:compare-plans:ontology_diff"
roadmap:
  phases:
    - phase: 1
      name: "Security Foundation"
      skills:
        - "identify-security-pattern"
        - "verify-no-regression"
      rationale: "Critical for safe autonomous operation"
    - phase: 2
      name: "Detection Enhancement"
      skills:
        - "detect-code-smell"
        - "constrain-auto-merge"
      rationale: "Improves review quality and safety"
    - phase: 3
      name: "Automation Expansion"
      skills:
        - "compare-implementations"
        - "generate-review-comment"
        - "evaluate-test-coverage"
        - "apply-suggested-fix"
      rationale: "Full autonomous review capability"
  total_new_skills: 8
  estimated_effort: "2-3 sprints"
  dependencies:
    - skill: "apply-suggested-fix"
      requires: ["verify-no-regression", "constrain-auto-merge"]
  evidence_anchors:
    - "tool:prioritize:impact_matrix"
    - "tool:generate-plan:roadmap"
audit:
  log_path: ".claude/audit/gap_20240115_120000_codereview.log"
  methodology: "Systematic comparison against reference ontology with layer-by-layer analysis"
  evidence_anchors:
    - "file:.claude/audit/gap_20240115_120000_codereview.log"
confidence: 0.85
evidence_anchors:
  - "file:schemas/capability_ontology.yaml"
  - "tool:map-relationships:dependency_graph"
  - "tool:compare-plans:ontology_diff"
  - "tool:prioritize:impact_matrix"
assumptions:
  - "Reference ontology is current and complete"
  - "Existing skills are correctly implemented"
  - "Priority criteria reflect actual business needs"

Evidence pattern: Ontology comparison, dependency graph analysis, impact-based prioritization.

Verification

• [ ] Coverage Analyzed: All capabilities in scope examined
• [ ] Gaps Documented: Each gap has layer classification and priority
• [ ] Relationships Mapped: Dependencies and missing connections identified
• [ ] Comparison Complete: Alignment score computed against reference
• [ ] Roadmap Generated: Phased plan with dependencies
• [ ] Audit Trail: Analysis methodology documented

Verification tools: Read (for ontology files), Grep (for capability search), Bash (for validation)

Safety Constraints

• mutation: false
• requires_checkpoint: false
• requires_approval: false
• risk: low

Capability-specific rules:
- Do not create new skills during analysis (discovery only)
- Validate all capability references against ontology
- Document assumptions about missing capabilities
- Flag potential security implications of gaps
- Preserve existing ontology structure

Composition Patterns

Commonly follows:
- inspect - After initial codebase exploration
- retrieve - After fetching reference documentation

Commonly precedes:
- generate-plan - To create detailed skill specifications
- prioritize - To refine gap prioritization
- summarize - To create executive summary

Anti-patterns:
- Never skip relationship mapping before prioritization
- Never propose skills without checking ontology for existing alternatives
- Never prioritize without defined criteria
- Never generate roadmap without dependency analysis

Workflow references:
- See workflow_catalog.yaml#gap-analysis-workflow for step definitions
- See capability_ontology.yaml for reference structure