path: root/docs/proposals/feature-knowledge-accumulation.md

# Feature Proposal: Knowledge Accumulation / Compound Learning System

> **Priority:** High
> **Complexity:** Medium
> **Estimated Effort:** 10-15 days
> **Status:** Proposal
> **Date:** 2026-02-09
> **Dependencies:** Contract Files system (existing)
> **Related:** [Overview Analysis](compound-engineering-analysis.md) · [Plan Deepening](feature-plan-deepening.md) · [Workflow Presets](feature-workflow-presets.md)

---

## Problem Statement

When a makima contract completes, the **knowledge generated during that contract is effectively lost**:

- **Solutions to tricky problems** exist only in task conversation history, which is not searchable or surfaceable
- **Patterns discovered** during one contract cannot inform future contracts
- **Mistakes made** in one contract are likely to be repeated in similar future contracts
- **Best practices** established during execution are not codified anywhere retrievable
- **Contract files** capture deliverables but not the *meta-knowledge* about how those deliverables were produced

This means every new contract starts from zero context, even when the team has solved similar problems before. Engineering effort does not compound.

---

## How Compound Engineering Solves This

The compound engineering plugin implements a `/compound` command that runs **5 parallel sub-agents** immediately after review:

```
┌─────────────────────────────────────────────────────────┐
│                   /compound                              │
│                                                         │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐    │
│  │  Context    │  │  Solution   │  │ Prevention  │    │
│  │  Extractor  │  │ Documenter  │  │ Strategist  │    │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘    │
│         │                │                │            │
│  ┌──────┴──────┐  ┌──────┴──────┐                      │
│  │   Doc       │  │  Category   │                      │
│  │   Linker    │  │  Classifier │                      │
│  └──────┬──────┘  └──────┬──────┘                      │
│         │                │                              │
│         ▼                ▼                              │
│  ┌──────────────────────────────────────┐              │
│  │  docs/solutions/[category]/file.md   │              │
│  │                                      │              │
│  │  ---                                 │              │
│  │  category: build-errors              │              │
│  │  severity: medium                    │              │
│  │  tags: [webpack, esm, cjs]           │              │
│  │  date: 2026-02-09                    │              │
│  │  contract: abc-123                   │              │
│  │  ---                                 │              │
│  │                                      │              │
│  │  # Mixed ESM/CJS Import Resolution  │              │
│  │                                      │              │
│  │  ## Problem                          │              │
│  │  ...                                 │              │
│  │  ## Solution                         │              │
│  │  ...                                 │              │
│  │  ## Prevention                       │              │
│  │  ...                                 │              │
│  └──────────────────────────────────────┘              │
└─────────────────────────────────────────────────────────┘
```

### 9 Auto-Detected Categories

| Category | Description |
|----------|-------------|
| `build-errors` | Compilation, bundling, dependency resolution |
| `test-failures` | Test setup, assertion patterns, mocking |
| `api-patterns` | API design, endpoint structure, versioning |
| `architecture-decisions` | Structural choices, trade-offs, patterns |
| `performance-optimizations` | Speed, memory, caching strategies |
| `security-practices` | Auth, input validation, secrets management |
| `debugging-techniques` | Investigation methods, logging strategies |
| `tooling-configurations` | Tool setup, config patterns, CI/CD |
| `domain-knowledge` | Business logic, domain-specific patterns |

---

## Proposed Makima Implementation

### 1. New "Compound" Phase

Add an optional **compound** phase to the contract lifecycle, positioned after review:

```
Research → Specify → Plan → Execute → Review → Compound
                                                  ▲
                                            (new phase)
```

**Phase behavior:**
- **Auto-triggered** after review phase completes (configurable)
- **Short-lived** — typically completes in 1-3 minutes
- Extracts learnings from the contract's execution and review
- Stores them as searchable, categorized learning documents
- Can be skipped via configuration for trivial contracts

### 2. New Supervisor Command: `makima supervisor compound`

```bash
# Run compound learning for the current contract
makima supervisor compound

# Compound with specific focus areas
makima supervisor compound --focus "security,performance"

# Compound with explicit learnings
makima supervisor compound --learning "The retry logic needed exponential backoff, not fixed delay"
```

**Implementation:**

```bash
# Under the hood, this spawns learning sub-agents
makima supervisor spawn-group "compound" \
  --tasks '[
    {
      "name": "context-extractor",
      "plan": "Extract the problem context, constraints, and environment details from the contract execution history..."
    },
    {
      "name": "solution-documenter",
      "plan": "Document the solutions that were applied, including code patterns and configuration changes..."
    },
    {
      "name": "prevention-strategist",
      "plan": "Identify what could prevent this class of problem in the future..."
    },
    {
      "name": "category-classifier",
      "plan": "Classify these learnings into the appropriate category..."
    },
    {
      "name": "doc-linker",
      "plan": "Link these learnings to existing documentation and related learnings..."
    }
  ]'
```

### 3. Learning Document Schema

Each learning is stored as a **contract file** with structured content and metadata:

```yaml
# Learning document metadata (stored in file description/metadata)
learning:
  category: "build-errors"          # One of 9 categories
  severity: "medium"                # low, medium, high, critical
  tags: ["webpack", "esm", "cjs"]   # Free-form tags
  source_contract_id: "abc-123"     # Contract that produced this learning
  source_contract_name: "Fix webpack bundling"
  repository: "github.com/org/repo"
  date: "2026-02-09"
  quality_score: 0.85               # 0-1, set by quality gate
  access_count: 0                   # Incremented on retrieval
  last_accessed: null
  relevance_decay: 0.95             # Per-month decay factor
```

**Document body structure:**

```markdown
# Mixed ESM/CJS Import Resolution

## Problem
When upgrading to webpack 5, mixed ESM and CommonJS imports caused
"Cannot use import statement outside a module" errors in production
but not development.

## Root Cause
The `type: "module"` field in package.json applied ESM resolution
globally, but several dependencies only provided CJS exports.

## Solution
1. Added `resolve.fullySpecified: false` to webpack config
2. Used `@babel/plugin-transform-modules-commonjs` for CJS deps
3. Created explicit `.cjs` extensions for config files

## Code Pattern
```javascript
// webpack.config.cjs (note: .cjs extension)
module.exports = {
  resolve: {
    fullySpecified: false,
    extensions: ['.js', '.mjs', '.cjs', '.json']
  }
};
```

## Prevention
- Add webpack build check to CI before merging
- Document module system choice in project README
- Use `resolve.fullySpecified: false` by default in webpack 5 projects

## Related
- docs/solutions/tooling-configurations/webpack-5-migration.md
- Contract: "Initial Webpack 5 Migration" (2026-01-15)
```

### 4. Storage Architecture

Learnings are stored in two complementary locations:

#### A. Contract Files (Structured, Persistent)

```rust
// Each learning becomes a contract file
File {
    contract_id: Some(source_contract.id),
    contract_phase: Some("compound"),
    name: "Learning: Mixed ESM/CJS Import Resolution",
    description: Some("category=build-errors; tags=webpack,esm,cjs; severity=medium"),
    body: vec![
        BodyElement::Heading { level: 1, text: "Mixed ESM/CJS Import Resolution" },
        BodyElement::Heading { level: 2, text: "Problem" },
        BodyElement::Paragraph { text: "..." },
        // ... structured content
    ],
    repo_file_path: Some("docs/solutions/build-errors/mixed-esm-cjs-resolution.md"),
    repo_sync_status: Some("synced"),
}
```

#### B. Repository Files (Searchable, Portable)

```
docs/solutions/
├── build-errors/
│   ├── mixed-esm-cjs-resolution.md
│   └── docker-multi-stage-cache.md
├── test-failures/
│   ├── async-test-timeout-patterns.md
│   └── mock-service-worker-setup.md
├── api-patterns/
│   └── pagination-cursor-vs-offset.md
├── architecture-decisions/
│   └── event-sourcing-tradeoffs.md
├── performance-optimizations/
│   └── database-connection-pooling.md
├── security-practices/
│   └── jwt-refresh-token-rotation.md
├── debugging-techniques/
│   └── distributed-tracing-setup.md
├── tooling-configurations/
│   └── github-actions-cache-strategy.md
└── domain-knowledge/
    └── payment-processing-idempotency.md
```

### 5. Auto-Surface Relevant Learnings

When a new contract is created, automatically search for relevant learnings:

```bash
# Supervisor plan template automatically includes:
# "Search existing learnings relevant to this task"

makima supervisor search-learnings --query "webpack bundling errors"
makima supervisor search-learnings --category "build-errors" --tags "webpack"
makima supervisor search-learnings --repository "github.com/org/repo"
```

**Search algorithm:**

```
Relevance Score =
    keyword_match_score * 0.4
  + category_match_score * 0.2
  + tag_overlap_score * 0.2
  + recency_score * 0.1        # Decays over time
  + quality_score * 0.1        # Higher quality = more relevant
```

**Integration with plan phase:**

```
┌──────────────┐       ┌───────────────────┐
│ New Contract │──────▶│ Plan Phase        │
│ Created      │       │                   │
└──────────────┘       │ 1. Create plan    │
                       │ 2. Search for     │◀── Learnings DB
                       │    relevant       │
                       │    learnings      │
                       │ 3. Inject context │
                       │    into plan      │
                       └───────────────────┘
```

### 6. Quality Control

#### Relevance Decay

Learnings lose relevance over time unless accessed:

```
effective_relevance = quality_score * (decay_factor ^ months_since_creation)
                    + access_bonus * recent_access_count
```

- Default decay factor: 0.95/month (learning at 60% relevance after 1 year)
- Access bonus: +0.05 per access (caps at +0.25)
- Learnings below 0.3 effective relevance are archived

#### Deduplication

When a new learning is created, check for existing similar learnings:

```
similarity = cosine_similarity(new_learning_embedding, existing_learning_embedding)
if similarity > 0.85:
    merge_or_update(existing_learning, new_learning)
elif similarity > 0.70:
    link_as_related(new_learning, existing_learning)
```

#### Quality Gate

Before storing a learning, validate:

| Check | Threshold | Action if Failed |
|-------|-----------|------------------|
| Has problem statement | Required | Reject |
| Has solution | Required | Reject |
| Has prevention strategy | Recommended | Warn, store with quality penalty |
| Code examples present | Recommended | Warn, store with quality penalty |
| Category valid | Required | Auto-classify |
| Not duplicate | >0.85 similarity | Merge with existing |
| Minimum length | >200 characters | Reject |

---

## Integration with Existing Makima Features

### Contract Phases

The compound phase integrates into the existing phase system:

```rust
// New phase variant
enum ContractPhase {
    Research,
    Specify,
    Plan,
    Execute,
    Review,
    Compound,  // NEW
}
```

- Contracts with `contract_type: "specification"` get the full 6-phase cycle
- Contracts with `contract_type: "simple"` can opt-in via config
- Phase guard still applies: user must approve transition to compound

### Contract Files

Learnings are first-class contract files, leveraging existing:
- Versioning system
- Structured body format (`BodyElement` types)
- Repository file sync (`repo_file_path`, `repo_sync_status`)
- Phase association (`contract_phase: "compound"`)

### Directive System

For directive-based workflows, learnings can be captured per-step:

```rust
DirectiveStep {
    name: "compound-step-3",
    description: "Capture learnings from database migration step",
    depends_on: [step_3_id, review_step_id],
    task_plan: "Extract and document learnings from the completed migration...",
}
```

### Supervisor CLI

New commands integrate with existing CLI infrastructure:

```bash
# In supervisor context
makima supervisor compound                    # Run compound phase
makima supervisor search-learnings "query"    # Search knowledge base
makima supervisor list-learnings              # List all learnings
makima supervisor learning-stats              # Knowledge base statistics
```

---

## Implementation Plan

### Phase 1: Core Infrastructure (4-5 days)

| Task | Effort | Description |
|------|--------|-------------|
| Add `compound` phase to contract lifecycle | 1 day | New phase enum, transition rules |
| Learning document schema | 1 day | Metadata structure, validation |
| `supervisor compound` command | 1-2 days | Spawn learning sub-agents |
| Repository file sync for learnings | 1 day | Write to `docs/solutions/` |

### Phase 2: Search & Retrieval (3-5 days)

| Task | Effort | Description |
|------|--------|-------------|
| `search-learnings` command | 1-2 days | Keyword + category search |
| Auto-surface in plan phase | 1-2 days | Inject relevant learnings into plans |
| Learning index | 1 day | Category/tag index for fast lookup |

### Phase 3: Quality & Maintenance (3-5 days)

| Task | Effort | Description |
|------|--------|-------------|
| Quality gate validation | 1 day | Pre-storage checks |
| Relevance decay system | 1 day | Scheduled decay + access tracking |
| Deduplication check | 1-2 days | Similarity detection and merging |
| Documentation & defaults | 1 day | User guide, default categories |

---

## Configuration Examples

### Enable Compound Phase (Contract-Level)

```yaml
# Contract configuration
compound:
  enabled: true
  auto_trigger: true        # Auto-run after review completes
  categories:               # Override default categories
    - build-errors
    - test-failures
    - api-patterns
    - architecture-decisions
    - performance-optimizations
    - security-practices
    - debugging-techniques
    - tooling-configurations
    - domain-knowledge
  quality_gate:
    min_length: 200
    require_problem: true
    require_solution: true
    require_prevention: false
  storage:
    contract_files: true     # Store as contract files
    repo_files: true         # Also write to docs/solutions/
    repo_path: "docs/solutions"
```

### Repository-Level Configuration (`.makima/compound.yaml`)

```yaml
# .makima/compound.yaml
version: 1
compound:
  # Default settings for all contracts in this repo
  auto_trigger: true

  # Custom categories for this project
  categories:
    - build-errors
    - test-failures
    - api-patterns
    - payment-processing     # Custom domain category
    - compliance-requirements # Custom domain category

  # Search settings
  search:
    max_results: 10
    min_relevance: 0.3
    include_archived: false

  # Decay settings
  decay:
    factor: 0.95             # Per month
    archive_threshold: 0.3
    access_bonus: 0.05
    max_access_bonus: 0.25
```

### Searching Learnings

```bash
# Full-text search
makima supervisor search-learnings "webpack ESM import error"

# Category filter
makima supervisor search-learnings --category build-errors

# Tag filter
makima supervisor search-learnings --tags webpack,esm

# Repository filter
makima supervisor search-learnings --repo github.com/org/repo

# Combined
makima supervisor search-learnings "import error" \
  --category build-errors \
  --tags webpack \
  --min-relevance 0.5 \
  --limit 5
```

---

## Open Questions

1. **Cross-repository knowledge**: Should learnings be scoped to a single repository or shared across all repositories for an owner?
2. **Learning ownership**: Who owns a learning — the contract creator, the repository, or the organization?
3. **Privacy**: Are learnings visible to all users, or scoped by access control?
4. **Embedding model**: For similarity-based deduplication and search, which embedding model should be used? Trade-off between quality and cost.
5. **Storage limits**: Should there be a cap on the number of learnings per repository/owner?
6. **Manual curation**: Should users be able to manually create, edit, or delete learnings outside the compound phase?
7. **Export/import**: Should learnings be exportable/importable across makima instances?

---

## Alternatives Considered

| Alternative | Pros | Cons | Decision |
|-------------|------|------|----------|
| Store learnings only in contract files | Simple, uses existing infrastructure | Not easily searchable across contracts | Rejected — search is critical |
| Store learnings only in repo files | Portable, version-controlled, greppable | Lost if repo deleted; no cross-repo search | Partial — use as secondary storage |
| Use external knowledge base (e.g., vector DB) | Best search quality | Added infrastructure dependency | Deferred — consider for v2 |
| Manual-only knowledge capture | No noise | Knowledge rarely captured | Rejected — must be automatic |
| Full contract history indexing | Most complete | Massive storage, noise, privacy concerns | Rejected — too much signal-to-noise |

---

## Priority & Complexity Assessment

- **Priority: HIGH** — This is the defining feature of compound engineering. Without knowledge accumulation, every contract starts from scratch. This is the feature that creates compounding returns.
- **Complexity: MEDIUM** — Core capture and storage is straightforward using existing contract files and repo sync. Search quality and relevance decay require iterative refinement.
- **Risk: MEDIUM** — Primary risk is low adoption (users skip compound phase) mitigated by auto-trigger. Secondary risk is knowledge base noise mitigated by quality gates.