codebase-gap-analysis git:20260601.0a08872A

Immutable. This exact content never changes and is served at /api/v1/blob/784e5725ae038056.

---
name: codebase-gap-analysis
description: 'Analyze a user''s codebase against a reference architecture to identify gaps and provide prioritized enhancement recommendations.'
tags: ['research', 'architecture', 'codebase', 'comparison', 'gap-analysis', 'project-review']
---

# Codebase Gap Analysis vs Reference Architecture

Use when the user wants to deeply compare their project or codebase against a reference implementation, framework, or architectural pattern to find gaps and improvement opportunities.

## Workflow

### 1. Define Scope & Dimensions
- Confirm the user's project location (repo URL, local path, or pasted code).
- Confirm the reference target (technology, product, or architectural pattern).
- Select comparison dimensions relevant to the domain (e.g., orchestration, memory, concurrency, skills, backends, observability, agent lifecycle).

### 2. Explore User Codebase
- Fetch repository metadata and directory structure.
- Read root configuration and documentation files.
- Dive into core source directories to map the architecture.
- Identify and read critical modules (planner, orchestrator, supervisor, memory, tools, agents, config).
- Summarize current capabilities, abstractions, and design patterns found.

### 3. Research Reference Architecture
- Search official documentation, repositories, and technical articles for the reference system.
- Extract concrete capabilities, configuration mechanisms, and architectural layers.
- Note any experimental, undocumented, or advanced features relevant to the comparison.

### 4. Execute Structured Comparison
- Build a side-by-side comparison table across the chosen dimensions.
- Flag capabilities present in the reference but missing or incomplete in the user's project.
- Note areas where the user's project may be ahead, equivalent, or intentionally divergent.

### 5. Prioritized Recommendations
- List each gap with: description, impact, and suggested implementation approach aligned with the user's stack.
- Assign priority (Critical / High / Medium / Low).
- Propose a pragmatic roadmap that respects existing dependencies and build patterns.

### 6. Deliver Synthesis
- Provide an overall architectural maturity assessment.
- Highlight quick wins versus long-term investments.
- Offer to elaborate on, design, or implement any specific recommendation.