---
type: skill
domain: architecture
links: [Corpus_Callosum/CONSTITUTION.md, PULSE_OS.md]
---

# DATABASE_WHISPERER
> **ROLE:** DATA ARCHITECT
> **TRIGGER:** "PERSISTENCE"

## Core Mandate
The disk is the ultimate source of truth. Every read is fast, every write is atomic, every schema is intentional.

## Step-by-Step Protocol
1. **Brain check**: `python pulse/brain/brain_query.py --query "data patterns for <module>"`
2. **Audit schema**: No duplicate data across files. Normalize JSON structures -- one source of truth per entity.
3. **Optimize queries**: Never `SELECT *`. Use `EXPLAIN ANALYZE` on any query >50ms. Add indexes on hot columns.
4. **Wrap multi-step writes** in transactions or atomic file operations (filelock for JSON files in PULSE).
5. **Monitor and save**: Log query latency. If >100ms, investigate. Save findings via `pulse_save.py`.

## SQL Examples (for DB-backed components)
```sql
-- ALWAYS check query plans before shipping
EXPLAIN ANALYZE SELECT task_id, status FROM tasks WHERE status = 'open';

-- GOOD: Index on frequently filtered columns
CREATE INDEX idx_tasks_status ON tasks(status);
CREATE INDEX idx_tasks_claimed_by ON tasks(claimed_by);

-- BAD vs GOOD query patterns
-- BAD:  SELECT * FROM tasks;
-- GOOD: SELECT task_id, title, status FROM tasks WHERE status = 'open' LIMIT 50;

-- GOOD: Use transactions for multi-step operations
BEGIN;
UPDATE tasks SET status = 'claimed', claimed_by = 'agent-1' WHERE task_id = 'T-001' AND status = 'open';
COMMIT;
```

## PULSE JSON File Patterns (primary data store)
```python
# CORRECT: Atomic JSON update with filelock
from filelock import FileLock
import json

def atomic_update_json(path: str, updater_fn):
    lock = FileLock(f"{path}.lock", timeout=2)
    with lock:
        data = json.loads(Path(path).read_text())
        updater_fn(data)
        Path(path).write_text(json.dumps(data, indent=2))
```

## Metrics & Thresholds
| Metric | Threshold |
|---|---|
| Query latency | <100ms (optimize if exceeded) |
| JSON file read/write | <50ms with filelock |
| Duplicate data across files | 0 (single source of truth) |
| Unindexed hot columns | 0 |
| `SELECT *` usage | 0 (fetch only needed fields) |

## Anti-Patterns
- **Reading entire JSON to find one field**: Parse once, cache the result, or restructure the file.
- **Writing without filelock**: Race conditions corrupt `task_board.json`. Always use `atomic_update_json`.
- **Nested JSON >3 levels deep**: Flatten the structure. PULSE brain refactor proved flat > nested.

## Tools to Use
- `brain_query.py --query "data persistence for <module>"` -- check prior patterns
- `pulse_save.py --learnings "optimized <query>"` -- record improvements
- `pulse_relay.py --tasks "Optimize JSON reads:architecture:fast"` -- delegate work

## Verification Checklist
- [ ] No `SELECT *` in any query (or equivalent full-file reads without filtering)
- [ ] All multi-step JSON writes use `atomic_update_json` with filelock
- [ ] Hot columns (status, task_id, claimed_by) are indexed
- [ ] Query latency <100ms for all critical paths
- [ ] JSON nesting depth <4 levels in all data files
- [ ] No duplicate data across brain files (single source of truth)
