# GAPS.md - Gap Analysis & Systemic Improvement Methodology

**Authority:** guidance (systematic gap identification and routing methodology)
**Layer:** Guides
**Binding:** No
**Scope:** how to identify, categorize, and route gaps in Decapod-managed systems
**Non-goals:** replacing TODO system, substituting for proof, or defining authoritative requirements

⚠️ **CRITICAL: Gap analysis is continuous intelligence work, not one-time audits.** ⚠️

This document defines the practice of systemic gap identification: finding what's missing, misaligned, or underdeveloped in the system, and routing those findings to the appropriate subsystems for resolution.

---

## 1. What Is a Gap

A **gap** is any delta between:
- **Current state** (what exists)
- **Required state** (what must exist)
- **Desired state** (what should exist for optimal performance)

Gaps are not bugs. Bugs are deviations from spec. Gaps are *missing or incomplete specifications, implementations, or capabilities*.

---

## 2. Gap Categories

### 2.1 Interface Gaps (`interfaces/`)
**Definition:** Missing or incomplete binding contracts, schemas, or invariants.

**Examples:**
- CLI surface without corresponding schema documentation
- Store semantics that allow contamination
- Proof surface that doesn't actually validate what it claims
- Undefined behavior at subsystem boundaries
- Schema drift (doc says X, code does Y)

**Detection:**
- Run `decapod validate` and analyze warnings
- Compare subsystem registry (PLUGINS.md) to actual CLI help output
- Check for `STUB` or `SPEC` items without graduation path
- Review error messages for undocumented edge cases

**Routing:**
- Interface contract issues → `interfaces/INTERFACES.md`
- Store model violations → `interfaces/STORE_MODEL.md`
- Doc compilation errors → `interfaces/DOC_RULES.md`
- Claims without proof → `interfaces/CLAIMS.md`
- Undefined terms → `interfaces/GLOSSARY.md`

**See:** `interfaces/INTERFACES.md` for interface contract registry

---

### 2.2 Methodology Gaps (`methodology/`)
**Definition:** Missing guidance, unclear practices, or incomplete cognitive frameworks.

**Examples:**
- Agent doesn't know how to handle a specific scenario
- Architecture practice lacks decision criteria
- Knowledge management has no staleness policy
- Memory system lacks retrieval validation
- Unclear when to use which subsystem
- UI components lack architectural patterns
- Frontend/backend integration undefined

**Detection:**
- Agents asking repetitive clarifying questions
- Inconsistent approaches to similar problems
- Documentation exists but isn't actionable
- Process gaps in multi-agent coordination
- Missing "how to" guidance for common tasks
- UI implementations diverge without pattern

**Routing:**
- Intent-driven workflow gaps → `specs/INTENT.md` (binding methodology)
- Architecture practice gaps → `methodology/ARCHITECTURE.md`
- Agent behavior gaps → `methodology/SOUL.md`
- Knowledge management gaps → `methodology/KNOWLEDGE.md`
- Learning/memory gaps → `methodology/MEMORY.md`
- UI architecture gaps → `architecture/UI.md`
- Frontend architecture gaps → `architecture/FRONTEND.md`

**See:** `core/METHODOLOGY.md` for methodology registry

---

### 2.3 Plugin/Subsystem Gaps (`plugins/`)
**Definition:** Missing functionality, incomplete implementations, or subsystem boundary issues.

**Examples:**
- TODO system lacks classification features
- Health system doesn't track subsystem X
- Missing cron job scheduling granularity
- No knowledge→TODO linking mechanism
- Gap between planned (SPEC) and implemented (REAL)

**Detection:**
- Compare PLUGINS.md registry to actual capabilities
- User requests for missing features
- Workarounds agents invent for missing functionality
- Cross-subsystem coordination failures
- Performance bottlenecks at subsystem boundaries

**Routing:**
- Subsystem status issues → `core/PLUGINS.md`
- Plugin-specific gaps → respective `plugins/<NAME>.md`
- Integration gaps → relevant subsystem docs + PLUGINS.md

**See:** `core/PLUGINS.md` §3.5 for subsystem registry and truth labels

---

### 2.4 Core/Coordination Gaps (`core/`)
**Definition:** Issues in routing, navigation, or system-wide coordination.

**Examples:**
- DECAPOD.md doesn't route to a documented subsystem
- Cross-category references are broken
- OVERRIDE.md isn't being respected
- Gap between demands and enforcement
- Missing emergency protocols

**Detection:**
- `decapod validate` failures in doc graph
- Broken links in constitution
- Navigation failures (can't find docs)
- Override system not functioning
- Contradictions between core files

**Routing:**
- Router/navigation gaps → `core/DECAPOD.md`
- Interface index gaps → `core/INTERFACES.md`
- Methodology index gaps → `core/METHODOLOGY.md`
- Subsystem registry gaps → `core/PLUGINS.md`
- User demand gaps → `core/DEMANDS.md`
- Deprecation gaps → `core/DEPRECATION.md`
- Gap analysis methodology → `core/GAPS.md` (this file)

---

### 2.5 Specification Gaps (`specs/`)
**Definition:** Missing system-level contracts, security considerations, or amendment processes.

**Examples:**
- Security model doesn't cover new threat vector
- Amendment process unclear for specific change types
- System boundaries undefined for new component
- Git contract doesn't cover specific workflow
- Intent contract missing scenario coverage

**Detection:**
- Security reviews finding uncovered areas
- Amendment requests without clear process
- Cross-system integration ambiguities
- Authority disputes about who owns what

**Routing:**
- Intent/methodology contract gaps → `specs/INTENT.md`
- System definition gaps → `specs/SYSTEM.md`
- Security gaps → `specs/SECURITY.md`
- Git workflow gaps → `specs/GIT.md`
- Change control gaps → `specs/AMENDMENTS.md`

---

### 2.6 Project-Specific Gaps (`.decapod/OVERRIDE.md`)
**Definition:** Gaps between embedded constitution and project needs.

**Examples:**
- Project needs custom priority levels
- Specific subsystem needs different defaults
- Custom validation gates required
- Project-specific methodology additions

**Detection:**
- OVERRIDE.md content doesn't address need
- Project repeatedly working around constitution
- Domain-specific gaps not covered by general docs

**Routing:**
- Project overrides → `.decapod/OVERRIDE.md`

---

## 3. Gap Identification Protocol

### 3.1 Continuous Scanning
Gap identification is not a one-time audit. It happens:
- During every agent session
- When validation fails
- When agents ask clarifying questions
- When workarounds emerge
- When proof surfaces can't validate

### 3.2 Gap Signal Detection

**Strong Signals (definite gaps):**
- `decapod validate` fails with new error
- Two docs contradict each other
- Agent can't determine next step
- Proof surface exists but can't be run
- Schema documented but not implemented

**Medium Signals (likely gaps):**
- Repeated similar questions
- Workarounds documented as "temporary"
- SPEC items without graduation timeline
- Claims marked `not_enforced`
- TODOs without clear resolution path

**Weak Signals (potential gaps):**
- Performance could be better
- UX friction
- Missing "nice to have" features
- Undocumented but working behavior

### 3.3 Gap Triage Questions

When you identify a potential gap, answer:

1. **What layer?** (interface, methodology, plugin, core, spec, project)
2. **What severity?** (blocks work, causes friction, nice to have)
3. **Who owns it?** (which document/subsystem has authority)
4. **Is it known?** (check existing TODOs, issues, docs)
5. **What's the proof?** (how would we know when it's fixed)

---

## 4. Gap Documentation & Routing

### 4.1 Document the Gap

Every identified gap should have:
- **Description:** What is missing/misaligned
- **Category:** Which gap type (§2)
- **Evidence:** How you detected it
- **Impact:** What work is blocked or complicated
- **Owner:** Which subsystem/document owns resolution
- **Proof:** How to verify when fixed

### 4.2 Route to Appropriate Subsystem

Use the **routing table** in §2 to determine where the gap belongs.

**Decision tree:**
1. Is it a missing/incomplete binding contract? → `interfaces/`
2. Is it unclear how to do something? → `methodology/`
3. Is it missing functionality? → `plugins/` or `core/PLUGINS.md`
4. Is it navigation/routing? → `core/DECAPOD.md`
5. Is it system-level contract? → `specs/`
6. Is it project-specific? → `.decapod/OVERRIDE.md`

### 4.3 Create TODO (if actionable)

If the gap is actionable:
1. Create TODO via `decapod todo add`
2. Tag with appropriate category
3. Reference this GAPS.md section if gap analysis needed
4. Link to relevant subsystem docs

**Example:**
```bash
decapod todo add "Fix gap: CLI schema missing for X command" --priority high
# Add details: Category=interface, Owner=interfaces/DOC_RULES.md
```

### 4.4 Update Relevant Index

If the gap reveals missing coverage in an index file:
- Update `core/INTERFACES.md` if interface gaps
- Update `core/METHODOLOGY.md` if methodology gaps
- Update `core/PLUGINS.md` if plugin gaps

---

## 5. Gap Lifecycle

```
Identify → Categorize → Route → Document → TODO → Resolve → Verify
```

**States:**
- **Identified:** Gap spotted, not yet categorized
- **Categorized:** Layer and type determined
- **Routed:** Owner document/subsystem identified
- **Documented:** Gap described with evidence
- **Ticketed:** TODO created with priority
- **In Progress:** Being addressed
- **Resolved:** Fix implemented
- **Verified:** Proof surface confirms resolution

---

## 6. Gap Analysis Integration with Subsystems

### 6.1 Integration with TODO System

Gap findings often become TODOs:
- High-impact gaps → high-priority TODOs
- Systemic gaps → epics with multiple TODOs
- Methodology gaps → documentation TODOs
- Interface gaps → implementation + doc TODOs

**See:** `plugins/TODO.md` for work tracking

### 6.2 Integration with Validation

Gap detection often triggered by:
- `decapod validate` failures
- Doc graph reachability issues
- Schema mismatches
- Store contamination detection

**Gap findings should:**
- Add validation gates where possible
- Update validate taxonomy
- Document expected vs actual behavior

**See:** `interfaces/CONTROL_PLANE.md` §6 for validate doctrine

### 6.3 Integration with Knowledge Base

Gap analysis produces knowledge:
- Why gaps exist (historical context)
- How gaps were resolved (patterns)
- Gap taxonomy and categorization
- Common gap types by subsystem

**See:** `methodology/KNOWLEDGE.md` for knowledge management

### 6.4 Integration with Memory

Agents should remember:
- Gap patterns (avoid repeated gaps)
- Resolution strategies
- Common routing decisions
- Verification approaches

**See:** `methodology/MEMORY.md` for learning patterns

---

## 7. Gap Taxonomy Reference

### 7.1 By Layer

| Layer | Gap Type | Index File |
|-------|----------|------------|
| Interfaces | Missing contracts, schemas, invariants | `core/INTERFACES.md` |
| Methodology | Unclear practices, missing guidance | `core/METHODOLOGY.md` |
| Plugins | Missing functionality, incomplete impl | `core/PLUGINS.md` |
| Core | Routing, navigation, coordination | `core/DECAPOD.md` |
| Specs | System contracts, security, process | `specs/` |
| Project | Project-specific overrides | `.decapod/OVERRIDE.md` |

### 7.2 By Severity

| Severity | Description | Action |
|----------|-------------|--------|
| Critical | Blocks work, violates contracts | Immediate TODO, escalate |
| High | Causes friction, workarounds needed | High-priority TODO |
| Medium | Inconvenience, unclear guidance | Medium-priority TODO |
| Low | Nice to have, optimization | Backlog or knowledge entry |

### 7.3 By Lifecycle Stage

| Stage | Gap Characteristic | Typical Resolution |
|-------|-------------------|-------------------|
| Design | Missing spec for planned feature | Add SPEC docs |
| Implementation | STUB without graduation path | Implement or deprioritize |
| Production | REAL but incomplete | Fix or document limitations |
| Maintenance | Drift from documented behavior | Drift recovery |

---

## 8. Common Gap Patterns

### 8.1 "SPEC Forever"
**Pattern:** Feature marked SPEC with no graduation timeline
**Detection:** Check PLUGINS.md for old SPEC items
**Resolution:** Either implement or downgrade to IDEA

### 8.2 "Documentation Drift"
**Pattern:** Docs say X, code does Y, neither is "wrong" but they differ
**Detection:** Validation warnings, agent confusion
**Resolution:** Drift recovery protocol (see INTENT.md)

### 8.3 "Proof Gap"
**Pattern:** Claim exists in CLAIMS.md but proof surface doesn't verify it
**Detection:** `not_enforced` claims, failing validate
**Resolution:** Implement proof or downgrade claim

### 8.4 "Missing Index"
**Pattern:** Subsystem exists but not in registry
**Detection:** PLUGINS.md doesn't list working subsystem
**Resolution:** Add to appropriate index file

### 8.5 "Interface Mismatch"
**Pattern:** Two subsystems expect different interfaces
**Detection:** Integration failures at boundaries
**Resolution:** Define boundary contract in interfaces/

### 8.6 "Methodology Vacuum"
**Pattern:** Common task has no documented approach
**Detection:** Agents invent different solutions
**Resolution:** Add methodology guide

---

## 9. Gap Analysis for Leadership

### 9.1 Strategic Gap Assessment

Principals and Architects should periodically:
- Review gap distribution by layer
- Identify systemic gap patterns
- Assess gap resolution velocity
- Prioritize gap categories

### 9.2 Gap Metrics

Track:
- Gap identification rate (new gaps per week)
- Gap resolution velocity (time to close)
- Gap severity distribution
- Gap category trends
- Recurring gap patterns

### 9.3 Gap Prevention

Proactive measures:
- Thorough design before implementation
- Proof surfaces for all REAL claims
- Clear methodology documentation
- Regular validation
- Cross-subsystem integration testing

---

## 10. Emergency Gap Protocol

### 10.1 Critical Gap Detected

If you find a gap that:
- Violates security contract
- Causes data loss
- Breaks validation completely
- Creates split-brain state

**Immediate actions:**
1. STOP work
2. Document gap with evidence
3. Notify via appropriate channels
4. Consult `plugins/EMERGENCY_PROTOCOL.md`
5. Create critical TODO
6. Do not proceed until resolved

### 10.2 Authority Escalation

If gap crosses authority boundaries:
- Document the ambiguity
- Propose authority assignment
- Reference `interfaces/DOC_RULES.md` §8
- Route to AMENDMENTS.md if needed

---

## 11. Gap Analysis Checklist

**When analyzing system for gaps:**

- [ ] Run `decapod validate` and catalog all warnings
- [ ] Review PLUGINS.md registry vs actual subsystems
- [ ] Check for `STUB`/`SPEC` without graduation path
- [ ] Identify `not_enforced` claims in CLAIMS.md
- [ ] Review recent TODOs for systemic patterns
- [ ] Survey agents for unclear guidance
- [ ] Check for broken/missing links in doc graph
- [ ] Compare OVERRIDE.md to project needs
- [ ] Review emergency protocols for coverage gaps
- [ ] Assess methodology docs for actionable guidance

---

## 12. Gap Resolution Verification

Every resolved gap needs:
- [ ] Proof surface passes
- [ ] Documentation updated
- [ ] Index files current
- [ ] TODO closed with evidence
- [ ] Knowledge entry (if pattern)
- [ ] No new gaps introduced

**Run before claiming resolution:**
```bash
decapod validate
# Must pass completely
```

---

## Links

### Core Router
- `core/DECAPOD.md` - **Router and navigation charter (START HERE)**

### Authority (Constitution Layer)
- `specs/INTENT.md` - **Methodology contract (READ FIRST)**
- `specs/SYSTEM.md` - System definition and authority doctrine
- `specs/SECURITY.md` - Security contract
- `specs/GIT.md` - Git etiquette contract
- `specs/AMENDMENTS.md` - Change control

### Registry (Core Indices)
- `core/PLUGINS.md` - Subsystem registry
- `core/INTERFACES.md` - Interface contracts index
- `core/METHODOLOGY.md` - Methodology guides index
- `core/DEPRECATION.md` - Deprecation contract

### Contracts (Interfaces Layer)
- `interfaces/CONTROL_PLANE.md` - Sequencing patterns and validation doctrine
- `interfaces/DOC_RULES.md` - Doc compilation rules
- `interfaces/CLAIMS.md` - Promises ledger
- `interfaces/GLOSSARY.md` - Term definitions

### Practice (Methodology Layer)
- `methodology/ARCHITECTURE.md` - Architecture practice
- `methodology/SOUL.md` - Agent identity
- `methodology/KNOWLEDGE.md` - Knowledge curation
- `methodology/MEMORY.md` - Memory and learning

### Domain Architecture Patterns
- `architecture/UI.md` - UI architecture patterns and component design
- `architecture/FRONTEND.md` - Frontend architecture patterns
- `architecture/WEB.md` - Web architecture patterns
- `architecture/DATA.md` - Data architecture patterns
- `architecture/SECURITY.md` - Security architecture patterns
- `architecture/CLOUD.md` - Cloud deployment patterns

### Operations (Plugins Layer)
- `plugins/TODO.md` - Work tracking
- `plugins/VERIFY.md` - Validation subsystem
- `plugins/EMERGENCY_PROTOCOL.md` - Emergency protocols

---

## Project Override Context

Current gap themes:
- Integration maturity: some domain adapters are still placeholder-level.
- Verification depth: broaden end-to-end and backend-parity test coverage.
- Runtime ergonomics: improve capability granting, versioning, and visibility of subsystem status.
- Interface completeness: close remaining stubs in automation and extension lifecycle workflows.

Completed themes:
- Stronger sandboxing and tool isolation model.
- Better context handling and background maintenance flows.
- Improved control plane surfaces for channels, routines, and extension management.
