# Skills Mapping: Digital Brain

This document maps how [Agent Skills for Context Engineering](https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering) principles are applied in the Digital Brain implementation.

---

## Context Engineering Principles Applied

### 1. Context Fundamentals

| Concept | Source Skill | Digital Brain Application |
|---------|--------------|---------------------------|
| **Attention Budget** | context-fundamentals | Module separation ensures only relevant content loads. Voice file (~200 lines) loads for content tasks; contacts file loads for network tasks. Never load everything. |
| **Progressive Disclosure** | context-fundamentals | Three-level architecture: L1 (SKILL.md metadata), L2 (module instructions), L3 (data files). Each level loads only when needed. |
| **High-Signal Tokens** | context-fundamentals | JSONL schemas include only essential fields. Voice profiles focus on patterns, not exhaustive rules. |

**Design Decision**:
> "Find the smallest possible set of high-signal tokens that maximize the likelihood of some desired outcome."

Applied by keeping `voice.md` focused on distinctive patterns (signature phrases, anti-patterns) rather than generic writing advice Claude already knows.

---

### 2. Memory Systems

| Concept | Source Skill | Digital Brain Application |
|---------|--------------|---------------------------|
| **Append-Only Logs** | memory-systems | All `.jsonl` files are append-only. Status changes via `"status": "archived"`, never deletion. Preserves full history. |
| **Structured Recall** | memory-systems | Consistent schemas across files enable pattern matching. `contact_id` links `contacts.jsonl` to `interactions.jsonl`. |
| **Episodic Memory** | memory-systems | `interactions.jsonl` captures discrete events. `posts.jsonl` logs content with performance metrics for retrospective analysis. |
| **Semantic Memory** | memory-systems | `knowledge/bookmarks.jsonl` with categories and tags enables topic-based retrieval. |

**Design Decision**:
> "Agents maintain persistent memory files to track progress across complex sequences."

Applied in `operations/metrics.jsonl` where weekly snapshots accumulate, enabling trend analysis without recomputing from raw data.

---

### 3. Tool Design

| Concept | Source Skill | Digital Brain Application |
|---------|--------------|---------------------------|
| **Self-Contained Tools** | tool-design | Scripts in `agents/scripts/` are standalone Python files. Each does one thing: `weekly_review.py` generates reviews, `stale_contacts.py` finds neglected relationships. |
| **Clear Input/Output** | tool-design | Scripts read from known paths, output structured text to stdout. No side effects unless explicitly documented. |
| **Token Efficiency** | tool-design | Scripts process data and return summaries. Agent receives results, not raw data processing logic. |

**Design Decision**:
> "Tools should be self-contained, unambiguous, and promote token efficiency."

Applied by having `content_ideas.py` analyze bookmarks and past posts internally, returning only actionable suggestions rather than raw analysis.

---

### 4. Context Optimization

| Concept | Source Skill | Digital Brain Application |
|---------|--------------|---------------------------|
| **Module Separation** | context-optimization | Six distinct modules (`identity/`, `content/`, `knowledge/`, `network/`, `operations/`, `agents/`) prevent cross-contamination. Content creation never needs to load network data. |
| **Just-In-Time Loading** | context-optimization | Module instruction files (`IDENTITY.md`, `CONTENT.md`, etc.) load only when that module is relevant. |
| **Reference Depth** | context-optimization | Main SKILL.md links to module docs which link to data files. Maximum two hops to any information. |

**Design Decision**:
> "Rather than pre-loading all data, maintain lightweight identifiers and dynamically load data at runtime."

Applied in network module: agent first scans `contacts.jsonl` for matching name, then loads specific `interactions.jsonl` entries only for that contact.

---

### 5. Context Degradation (Mitigation)

| Risk | Source Skill | Digital Brain Mitigation |
|------|--------------|--------------------------|
| **Context Rot** | context-degradation | Module separation caps any single load. Voice file stays under 300 lines. Data files stream via JSONL (read line by line). |
| **Stale Context** | context-degradation | `last_contact` timestamps in contacts. `stale_contacts.py` proactively surfaces relationships needing attention. |
| **Conflicting Instructions** | context-degradation | Single source of truth per domain. Voice only in `voice.md`. Goals only in `goals.yaml`. No duplication. |

**Design Decision**:
> "As context length increases, models experience diminishing returns in accuracy and recall."

Applied by keeping SKILL.md under 200 lines, each module instruction file under 100 lines, and using external files for data rather than inline content.

---

## Architecture Decisions

### Why JSONL for Logs?

```
✓ Append-only by design
✓ Stream-friendly (no full file parse)
✓ Schema per line (first line documents structure)
✓ Agent-friendly (standard JSON parsing)
✓ Grep-compatible for quick searches

✗ Not human-editable (use YAML/MD for configs)
✗ No transactions (acceptable for personal data)
```

### Why Markdown for Narrative?

```
✓ Human-readable and editable
✓ Rich formatting (tables, lists, code)
✓ Git-friendly diffs
✓ Universal rendering

Use for: voice, brand, calendar, todos, templates
```

### Why YAML for Config?

```
✓ Hierarchical structure
✓ Human-readable
✓ Comments supported
✓ Clean syntax for nested data

Use for: goals, values, circles, learning
```

### Why XML for Prompts?

```
✓ Clear structure for agents
✓ Named sections (instructions, context, output)
✓ Variable placeholders
✓ Validation-friendly

Use for: content-generation templates, complex prompts
```

---

## Workflow Mappings

### Content Creation → Skills Applied

```
User: "Write a post about building in public"

Skills Chain:
1. context-fundamentals → Load only identity module
2. memory-systems → Retrieve voice patterns from voice.md
3. context-optimization → Don't load network/operations
4. tool-design → Use content templates as structured scaffolds

Files Loaded:
- SKILL.md (50 tokens) - Routing
- identity/IDENTITY.md (80 tokens) - Module instructions
- identity/voice.md (200 tokens) - Voice patterns
- identity/brand.md (scan for pillars) - Topic validation

Total: ~400 tokens vs loading entire brain (~5000 tokens)
```

### Relationship Management → Skills Applied

```
User: "Prepare me for my call with Alex"

Skills Chain:
1. context-fundamentals → Load only network module
2. memory-systems → Query contacts, then interactions
3. context-optimization → Just-in-time loading of specific contact
4. tool-design → Structured output (brief format)

Files Loaded:
- SKILL.md (50 tokens) - Routing
- network/NETWORK.md (60 tokens) - Module instructions
- network/contacts.jsonl (scan for Alex) - Contact data
- network/interactions.jsonl (filter by contact_id) - History

Total: ~300 tokens for relevant context only
```

---

## Trade-offs and Rationale

| Decision | Trade-off | Rationale |
|----------|-----------|-----------|
| Separate modules | More files to navigate | Prevents context bloat; enables targeted loading |
| JSONL for data | Less human-friendly | Optimized for agent parsing and append operations |
| No database | No query language | Simplicity; works offline; no dependencies |
| Python scripts | Requires Python runtime | Universal; readable; easy to extend |
| Placeholders not examples | User must fill in | Avoids "AI slop"; forces personalization |

---

## Verification Checklist

When extending Digital Brain, verify:

- [ ] New files follow format conventions (JSONL/YAML/MD/XML)
- [ ] Module instruction files stay under 100 lines
- [ ] JSONL files include schema line as first entry
- [ ] Cross-module references are minimal
- [ ] Scripts are self-contained with clear I/O
- [ ] No duplicate sources of truth

---

## Related Skills

This implementation draws from these skills in the collection:

| Skill | Primary Application |
|-------|---------------------|
| `context-fundamentals` | Overall architecture, progressive disclosure |
| `context-degradation` | Mitigation strategies, file size limits |
| `context-optimization` | Module separation, just-in-time loading |
| `memory-systems` | JSONL design, append-only patterns |
| `tool-design` | Agent scripts, I/O patterns |
| `multi-agent-patterns` | Future: delegation to specialized sub-agents |

---

*This mapping demonstrates how theoretical context engineering principles translate to practical system design.*