# Phase 3: CLAUDE.md Hub-and-Spoke Network Audit - Research

**Researched:** 2026-03-23
**Domain:** Documentation infrastructure (CLAUDE.md network)
**Confidence:** HIGH

## Summary

This phase is a documentation infrastructure audit and creation task. The project has an established CLAUDE.md hub-and-spoke pattern: a root hub file links to 12 spoke CLAUDE.md files, each providing directory-level context for AI agents working in that area. The audit reveals **13 existing CLAUDE.md files** (1 hub + 12 spokes) and identifies **up to 15 directories** that contain substantial source code but lack their own CLAUDE.md spoke.

The existing pattern is well-established and consistent: each spoke has a `**Parent**:` header linking back to its parent CLAUDE.md, a brief description, a file-to-responsibility table, key domain knowledge, and a `## Related` section linking to sibling spokes. The root hub has a `## CLAUDE.md Network (Hub-and-Spoke)` table mapping every spoke.

**Primary recommendation:** Create CLAUDE.md files for the ~10 highest-impact missing directories (those with >500 LOC or critical domain knowledge), update the root hub table to include all new spokes, and verify bidirectional linking.

<user_constraints>

## User Constraints (from CONTEXT.md)

### Locked Decisions

None -- all implementation choices at Claude's discretion.

### Claude's Discretion

All implementation choices are at Claude's discretion -- pure infrastructure phase. Use ROADMAP phase goal, success criteria, and codebase conventions to guide decisions. Follow the existing CLAUDE.md pattern established in the hub-and-spoke network table in the root CLAUDE.md.

### Deferred Ideas (OUT OF SCOPE)

None.
</user_constraints>

## Audit Results

### Existing CLAUDE.md Files (13 total)

| #   | Path                                                     | SSoT For                                                | LOC Coverage   |
| --- | -------------------------------------------------------- | ------------------------------------------------------- | -------------- |
| 1   | `/CLAUDE.md` (hub)                                       | Project overview, API, architecture, principles         | Entire project |
| 2   | `/crates/CLAUDE.md`                                      | Rust crates workspace, microstructure formulas          | 10 crates      |
| 3   | `/crates/opendeviationbar-providers/CLAUDE.md`           | Binance Vision CSV, data source policy, WS              | ~3K LOC        |
| 4   | `/python/opendeviationbar/CLAUDE.md`                     | Python API, caching, validation, symbol registry        | ~20K LOC       |
| 5   | `/python/opendeviationbar/clickhouse/CLAUDE.md`          | ClickHouse schema, dedup hardening, cache population    | ~2K LOC        |
| 6   | `/python/opendeviationbar/config/CLAUDE.md`              | Configuration via pydantic-settings, env var priority   | ~1K LOC        |
| 7   | `/python/opendeviationbar/orchestration/CLAUDE.md`       | Rust-Python-CH pipeline, circuit breaker, count-bounded | ~3K LOC        |
| 8   | `/python/opendeviationbar/plugins/CLAUDE.md`             | FeatureProvider protocol, plugin schema migration       | ~1K LOC        |
| 9   | `/python/opendeviationbar/storage/CLAUDE.md`             | Tier-1 Parquet ticks cache, TickStorage, MEM guards     | ~2K LOC        |
| 10  | `/python/opendeviationbar/validation/day_mode/CLAUDE.md` | Day-mode invariant enforcement, pre-write gate          | ~1K LOC        |
| 11  | `/deploy/CLAUDE.md`                                      | Env files SSoT, monit watchdog, defense-in-depth        | Deploy config  |
| 12  | `/scripts/CLAUDE.md`                                     | Kintsugi, writer ownership, parallelism, Stathera       | ~10K LOC       |
| 13  | `/scripts/systemd/CLAUDE.md`                             | Services, timers, TZ=UTC, OOM protection                | Service units  |

### Missing CLAUDE.md Files -- Prioritized by Impact

#### Tier 1: High Impact (>1000 LOC, critical domain knowledge)

| #   | Directory                              | LOC                   | Domain Knowledge                                             | Priority Justification                                             |
| --- | -------------------------------------- | --------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------ |
| 1   | `/src/`                                | 4,882                 | PyO3 bindings, module registration                           | Bridge between Rust and Python -- critical for any binding changes |
| 2   | `/python/opendeviationbar/sidecar/`    | 3,510                 | Streaming sidecar package (midnight, HTTP, recovery)         | Recently modularized (Phase 1), complex multi-file package         |
| 3   | `/python/opendeviationbar/kintsugi/`   | 2,734                 | Gap reconciliation (discovery, repair, orchestrator, daemon) | Recently modularized (Phase 1), 9 files, complex domain            |
| 4   | `/python/opendeviationbar/checkpoint/` | 2,252                 | Resumable population (engine, models, storage)               | Recently modularized (Phase 1), 4 files                            |
| 5   | `/python/opendeviationbar/validation/` | 2,163                 | Tier1/Tier2 validation, continuity, gap classification       | Parent of day_mode/ which already has CLAUDE.md                    |
| 6   | `/scripts/heartbeat/`                  | 938 + 2,280 (checks/) | Health monitoring, Stathera checks, Telegram alerts          | 2-level deep: heartbeat/ and heartbeat/checks/                     |
| 7   | `/python/opendeviationbar/processors/` | 1,387                 | Trade processing API, core processing pipeline               | api.py and core.py handle all trade processing                     |

#### Tier 2: Medium Impact (200-1000 LOC, useful context)

| #   | Directory                             | LOC | Domain Knowledge                                             |
| --- | ------------------------------------- | --- | ------------------------------------------------------------ |
| 8   | `/python/opendeviationbar/compat/`    | 565 | Backward compatibility layer (availability, manifest, panel) |
| 9   | `/python/opendeviationbar/notify/`    | 406 | Telegram notification module                                 |
| 10  | `/python/opendeviationbar/ratelimit/` | 176 | File-based rate limiting coordinator                         |

#### Tier 3: Low Impact (data-only or too small)

| #   | Directory                             | LOC                | Recommendation                                                                                   |
| --- | ------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------ |
| 11  | `/python/opendeviationbar/data/`      | 1 (+ symbols.toml) | Skip -- just `__init__.py` marker + `symbols.toml`. Covered by parent's Symbol Registry section. |
| 12  | `/tests/`                             | ~74 files          | Skip -- test files are self-documenting. Covered by root CLAUDE.md development commands.         |
| 13  | `/docs/`                              | Various            | Skip -- documentation directory doesn't need meta-documentation.                                 |
| 14  | `/deploy/monit/`                      | 5 files            | Skip -- covered by parent `deploy/CLAUDE.md` monit section.                                      |
| 15  | `/crates/opendeviationbar-streaming/` | ~2K LOC            | Could benefit from spoke, but parent `crates/CLAUDE.md` covers streaming crate already.          |

### Directories NOT Needing CLAUDE.md

These are excluded for clear reasons:

- `.cargo/`, `.github/`, `.mise/`, `.claude/` -- tooling config, not project code
- `benches/`, `examples/` -- self-explanatory
- `rules/` -- third-party lint rules
- `tools/chart/` -- standalone utility
- `supply-chain/` -- cargo-vet
- `test_data/`, `data/`, `store/`, `format_schemas/` -- data directories
- Individual Rust crate directories (`opendeviationbar-core/`, `opendeviationbar-hurst/`, etc.) -- covered by parent `crates/CLAUDE.md` which has a comprehensive table

## Architecture Patterns

### Existing CLAUDE.md Spoke Pattern

Every spoke follows this structure (verified across all 12 existing spokes):

```markdown
# [Directory Title]

**Parent**: [/path/to/parent/CLAUDE.md](/path/to/parent/CLAUDE.md) | **Hub**: [/CLAUDE.md](/CLAUDE.md)

[1-2 sentence description of what this directory contains.]

---

## Files

| File      | Purpose     |
| --------- | ----------- |
| `file.py` | Description |

---

## [Domain-Specific Section 1]

[Key knowledge for this domain]

## [Domain-Specific Section 2]

[More domain knowledge]

---

## Related

- [/CLAUDE.md](/CLAUDE.md) - Hub
- [/sibling/CLAUDE.md](/sibling/CLAUDE.md) - Sibling description
```

### Pattern Variations

1. **`**Parent**:` header** -- ALWAYS present. Links to the immediate parent CLAUDE.md.
2. **`**Hub**:` header** -- Present when the spoke is 2+ levels deep (e.g., `clickhouse/` links to both parent `python/opendeviationbar/CLAUDE.md` and hub `/CLAUDE.md`).
3. **`**Related**:` in header** -- Sometimes used instead of a full Related section (e.g., `deploy/CLAUDE.md` uses `**Related**: [/scripts/systemd/CLAUDE.md]`).
4. **`## Files` table** -- Present in all spokes with multiple source files.
5. **`## Related` section** -- Present at the bottom of most spokes, linking to sibling and parent CLAUDE.md files.

### Hub Table Pattern

The root CLAUDE.md has a `## CLAUDE.md Network (Hub-and-Spoke)` section with a 3-column table:

```markdown
| Directory | CLAUDE.md | SSoT For |
```

This table must be updated to include all new spokes.

### Hierarchical Parent Chains

Current hierarchy:

```
/CLAUDE.md (hub)
  ├── /crates/CLAUDE.md
  │   └── /crates/opendeviationbar-providers/CLAUDE.md
  ├── /python/opendeviationbar/CLAUDE.md
  │   ├── /python/opendeviationbar/clickhouse/CLAUDE.md
  │   ├── /python/opendeviationbar/config/CLAUDE.md
  │   ├── /python/opendeviationbar/orchestration/CLAUDE.md
  │   ├── /python/opendeviationbar/plugins/CLAUDE.md
  │   ├── /python/opendeviationbar/storage/CLAUDE.md
  │   └── /python/opendeviationbar/validation/day_mode/CLAUDE.md
  ├── /deploy/CLAUDE.md
  └── /scripts/CLAUDE.md
      └── /scripts/systemd/CLAUDE.md
```

New spokes should follow this hierarchy:

```
/CLAUDE.md (hub)
  ├── /src/CLAUDE.md  (Parent: /CLAUDE.md)
  ├── /crates/CLAUDE.md
  │   └── /crates/opendeviationbar-providers/CLAUDE.md
  ├── /python/opendeviationbar/CLAUDE.md
  │   ├── /python/opendeviationbar/checkpoint/CLAUDE.md
  │   ├── /python/opendeviationbar/clickhouse/CLAUDE.md
  │   ├── /python/opendeviationbar/compat/CLAUDE.md
  │   ├── /python/opendeviationbar/config/CLAUDE.md
  │   ├── /python/opendeviationbar/kintsugi/CLAUDE.md
  │   ├── /python/opendeviationbar/notify/CLAUDE.md
  │   ├── /python/opendeviationbar/orchestration/CLAUDE.md
  │   ├── /python/opendeviationbar/plugins/CLAUDE.md
  │   ├── /python/opendeviationbar/processors/CLAUDE.md
  │   ├── /python/opendeviationbar/ratelimit/CLAUDE.md
  │   ├── /python/opendeviationbar/sidecar/CLAUDE.md
  │   ├── /python/opendeviationbar/storage/CLAUDE.md
  │   └── /python/opendeviationbar/validation/CLAUDE.md
  │       └── /python/opendeviationbar/validation/day_mode/CLAUDE.md
  ├── /deploy/CLAUDE.md
  └── /scripts/CLAUDE.md
      ├── /scripts/systemd/CLAUDE.md
      └── /scripts/heartbeat/CLAUDE.md
          └── /scripts/heartbeat/checks/CLAUDE.md
```

## Don't Hand-Roll

| Problem                   | Don't Build         | Use Instead                               | Why                                                                      |
| ------------------------- | ------------------- | ----------------------------------------- | ------------------------------------------------------------------------ |
| Content for new CLAUDE.md | Generic boilerplate | Read actual source files in the directory | Each spoke must document the real domain knowledge, not placeholder text |
| Parent links              | Manual tracking     | Follow the hierarchy tree above           | Consistent parent chain is critical for Claude Code's auto-loading       |
| Hub table updates         | Manual editing      | Use the existing table format             | Consistency with 12 existing entries                                     |

## Common Pitfalls

### Pitfall 1: Creating Spokes Without Reading Source

**What goes wrong:** CLAUDE.md contains generic descriptions that don't help AI agents
**Why it happens:** Temptation to generate boilerplate without understanding what each file does
**How to avoid:** Read `__init__.py` and key files in each directory before writing the spoke
**Warning signs:** Spoke says "utility functions" or "helper module" without specifics

### Pitfall 2: Inconsistent Parent Links

**What goes wrong:** `**Parent**:` link points to wrong CLAUDE.md or uses relative path
**Why it happens:** Copy-paste from another spoke without updating
**How to avoid:** Always use absolute paths from repo root (e.g., `/python/opendeviationbar/CLAUDE.md`)
**Warning signs:** `**Parent**:` links to hub when there's an intermediate parent

### Pitfall 3: Orphan Spokes Not in Hub Table

**What goes wrong:** New CLAUDE.md exists but hub table doesn't list it
**Why it happens:** Creating spoke files but forgetting to update root CLAUDE.md
**How to avoid:** Always update hub table in same commit/plan as spoke creation
**Warning signs:** `grep -c CLAUDE.md` count in root doesn't match actual file count

### Pitfall 4: Duplicating Information Already in Parent

**What goes wrong:** Spoke repeats everything already in parent CLAUDE.md
**Why it happens:** Being too thorough
**How to avoid:** Spoke should document directory-specific knowledge; link to parent for broader context
**Warning signs:** Spoke is longer than parent's section about this topic

### Pitfall 5: Missing validation/ Intermediate Spoke

**What goes wrong:** `validation/day_mode/CLAUDE.md` has Parent pointing to `python/opendeviationbar/CLAUDE.md` but a `validation/CLAUDE.md` is created without updating day_mode's parent
**How to avoid:** When creating an intermediate spoke (validation/), update existing child spokes (day_mode/) to point to the new intermediate parent
**Warning signs:** day_mode/CLAUDE.md still points to grandparent

## Content Guidelines Per Missing Spoke

### `/src/CLAUDE.md` -- PyO3 Bindings

- File-to-module mapping (11 .rs files)
- Module registration pattern (`lib.rs`)
- Binding naming convention (e.g., `*_bindings.rs`)
- Link to `crates/CLAUDE.md` for Rust types being bound
- Rebuild command: `maturin develop`

### `/python/opendeviationbar/sidecar/CLAUDE.md` -- Streaming Sidecar Package

- File-to-responsibility table (10 files)
- Startup sequence (`__init__.py` is the orchestrator)
- midnight.py: crossover TID, preflight, yesterday signal
- http_server.py: health endpoint, SSE, API
- Reference existing root CLAUDE.md sections (Startup Sequence Invariant #294/#295)

### `/python/opendeviationbar/kintsugi/CLAUDE.md` -- Gap Reconciliation Package

- File-to-responsibility table (9 files)
- Discovery -> Repair -> Verify flow
- Orchestrator loop, daemon mode
- Dead-letter handling
- Reference writer ownership model (#280)

### `/python/opendeviationbar/checkpoint/CLAUDE.md` -- Resumable Population

- File-to-responsibility table (4 files)
- engine.py: main populate loop
- models.py: checkpoint data structures
- storage.py: checkpoint persistence
- Reference memory guards (MEM-013)

### `/python/opendeviationbar/validation/CLAUDE.md` -- Validation Framework

- File-to-responsibility table (7+ files)
- tier1.py / tier2.py distinction
- continuity.py: Stathera validation
- gap_classification.py: gap type taxonomy
- Link to child: validation/day_mode/CLAUDE.md

### `/scripts/heartbeat/CLAUDE.md` -- Health Heartbeat Package

- **main**.py entry point
- checks/ subdirectory (12 check modules)
- formatter.py: Telegram message formatting
- alert_dedup.py: alert deduplication
- config.py: check configuration

### `/scripts/heartbeat/checks/CLAUDE.md` -- Heartbeat Check Modules

- All 12+ check modules listed
- stathera.py is the primary gap detection check
- Each check's output format
- Link to heartbeat system in scripts/CLAUDE.md

### `/python/opendeviationbar/processors/CLAUDE.md` -- Trade Processors

- api.py: high-level processing API
- core.py: core processing pipeline
- Relationship to Rust `OpenDeviationBarProcessor`

### `/python/opendeviationbar/compat/CLAUDE.md` -- Backward Compatibility

- availability.py, manifest.py, panel.py
- What backward compatibility is maintained

### `/python/opendeviationbar/notify/CLAUDE.md` -- Notifications

- telegram.py: bot integration
- Env vars: TELEGRAM_TOKEN, TELEGRAM_CHAT_ID
- Usage patterns (enable_telegram_notifications, send_telegram)

### `/python/opendeviationbar/ratelimit/CLAUDE.md` -- Rate Limiting

- file_coordinator.py: file-based coordination
- Cross-process rate limiting mechanism

## Hub Table Update Plan

The root CLAUDE.md hub table (lines 288-302) needs expansion from 12 to ~22 entries. New entries should be inserted in the table maintaining the existing ordering pattern:

1. Root
2. `/crates/` group
3. `/python/opendeviationbar/` group (alphabetical by subdir)
4. `/deploy/` group
5. `/scripts/` group
6. `/src/` (new, after scripts or before crates)

## Validation Architecture

### Test Framework

| Property           | Value                                                                                        |
| ------------------ | -------------------------------------------------------------------------------------------- |
| Framework          | Manual verification (documentation phase)                                                    |
| Quick run command  | `grep -r 'Parent.*CLAUDE.md' --include='CLAUDE.md' . \| grep -v worktrees \| grep -v target` |
| Full suite command | See verification checklist below                                                             |

### Verification Checklist

1. Every CLAUDE.md has a `**Parent**:` header
2. Every parent link resolves to an existing file
3. Root hub table lists every CLAUDE.md in the project
4. No orphan CLAUDE.md files (in project, not in hub table)
5. Bidirectional: hub table links to spoke, spoke links back to parent
6. `validation/day_mode/CLAUDE.md` parent updated if `validation/CLAUDE.md` is created

### Wave 0 Gaps

- None -- no test infrastructure needed for documentation phase

## Project Constraints (from CLAUDE.md)

- All CLAUDE.md files must use absolute paths from repo root (e.g., `/python/opendeviationbar/CLAUDE.md`)
- Hub-and-spoke pattern is the established convention -- do not deviate
- Each spoke must be SSoT for its directory's domain knowledge
- Spoke content should be specific and actionable, not generic boilerplate
- `.claude/*` is in `.gitignore` with `!.claude/skills/` exception -- CLAUDE.md files outside `.claude/` are tracked normally

## Sources

### Primary (HIGH confidence)

- Direct filesystem audit of all project directories
- Reading all 13 existing CLAUDE.md files for pattern extraction
- Line counts from `wc -l` on all source files in candidate directories

## Metadata

**Confidence breakdown:**

- Audit completeness: HIGH - exhaustive filesystem scan
- Pattern extraction: HIGH - read all 13 existing spokes
- Missing spoke prioritization: HIGH - based on LOC and domain complexity
- Content guidelines: MEDIUM - based on file names and brief inspection, detailed reading needed during implementation

**Research date:** 2026-03-23
**Valid until:** 2026-04-23 (stable -- documentation patterns don't change frequently)
