# PRD.md - Align All CLAUDE.md Documentation to Code

## PROSTAT

**align all docs and root and nested CLAUDE.md to the codes**

---

## Background

This project (`opendeviationbar-py`) is a Rust/Python hybrid for generating open deviation bars — a novel financial data type. The repository contains 7 CLAUDE.md files (1 root + 6 nested) that serve as AI agent memory. These docs must accurately reflect the current code state.

**Current CLAUDE.md files:**
- `/CLAUDE.md` (root, 21KB)
- `/crates/CLAUDE.md` (15KB)
- `/python/opendeviationbar/CLAUDE.md` (18KB)
- `/python/opendeviationbar/clickhouse/CLAUDE.md` (14KB)
- `/python/opendeviationbar/config/CLAUDE.md` (2.6KB)
- `/python/opendeviationbar/plugins/CLAUDE.md` (4.4KB)
- `/scripts/CLAUDE.md` (15KB)

---

## Objectives

1. Audit each CLAUDE.md for accuracy against current code
2. Fix discrepancies between documentation and implementation
3. Ensure cross-reference consistency between CLAUDE.md files
4. Verify public API documentation matches actual exports
5. Validate that code examples in docs are runnable

---

## 9 Investigative Perspectives (Tasks)

### Task 1: Root CLAUDE.md Alignment
**Perspective**: Verify root `/CLAUDE.md` accurately reflects project structure, architecture, and entry points.

**Investigation angles:**
- Check if crate list in "Architecture" section matches actual `crates/` directory
- Verify PyO3 bindings in `src/` match documented exports
- Validate API entry points in "Python API" section exist in actual code
- Confirm mise commands in "Development Commands" are valid

**Use Dynamic Task Creation**: After initial audit, if you find specific discrepancies (e.g., missing functions, wrong paths), create sub-tasks to fix each category of issues.

**After completing your investigation, broadcast your key findings to all peers.**

---

### Task 2: Rust Crates CLAUDE.md Alignment  
**Perspective**: Verify `/crates/CLAUDE.md` accurately documents Rust crate structure, types, and algorithms.

**Investigation angles:**
- Verify 8-crate workspace matches actual `Cargo.toml` and directory structure
- Check microstructure feature formulas match implementation in `processor.rs`
- Validate inter-bar feature list in `interbar.rs` 
- Confirm key types (`OpenDeviationBarProcessor`, `FixedPoint`, etc.) exist in actual code

**Use Dynamic Task Creation**: After finding specific mismatches, spawn sub-tasks to update formulas, add missing features, or correct type references.

**After completing your investigation, broadcast your key findings to all peers.**

---

### Task 3: Python Core API CLAUDE.md Alignment
**Perspective**: Verify `/python/opendeviationbar/CLAUDE.md` matches Python API exports.

**Investigation angles:**
- Check all functions in "Key Files > __init__.py" exist in actual `__init__.py`
- Validate `TIER1_SYMBOLS`, `THRESHOLD_PRESETS` constants match code
- Verify validation modules exist (`validation/tier1.py`, `tier2.py`)
- Confirm storage classes (`TickStorage`) exist

**Use Dynamic Task Creation**: For each missing function or incorrect reference, create a sub-task to either add to code or update docs.

**After completing your investigation, broadcast your key findings to all peers.**

---

### Task 4: ClickHouse CLAUDE.md Alignment
**Perspective**: Verify `/python/opendeviationbar/clickhouse/CLAUDE.md` matches actual cache implementation.

**Investigation angles:**
- Check `schema.sql` matches documented columns
- Verify `populate_cache_resumable()` signature and behavior
- Validate ClickHouse connection code matches documented approach
- Confirm dedup hardening procedures are documented

**Use Dynamic Task Creation**: If schema or API mismatches found, create sub-task to reconcile.

**After completing your investigation, broadcast your key findings to all peers.**

---

### Task 5: Configuration CLAUDE.md Alignment
**Perspective**: Verify `/python/opendeviationbar/config/CLAUDE.md` matches actual config modules.

**Investigation angles:**
- List all files in `config/` directory and compare to "File Map" table
- Verify Settings singleton pattern works as documented
- Check environment variable prefixes match
- Validate pydantic models exist with documented fields

**Use Dynamic Task Creation**: For missing config files or wrong env var names, create sub-tasks.

**After completing your investigation, broadcast your key findings to all peers.**

---

### Task 6: Plugin System CLAUDE.md Alignment
**Perspective**: Verify `/python/opendeviationbar/plugins/CLAUDE.md` matches actual plugin implementation.

**Investigation angles:**
- Check `protocol.py` defines `FeatureProvider` Protocol as documented
- Verify entry-point discovery works in `loader.py`
- Validate plugin example code is runnable
- Confirm migration helpers exist

**Use Dynamic Task Creation**: If protocol or loader mismatches, create sub-tasks to fix.

**After completing your investigation, broadcast your key findings to all peers.**

---

### Task 7: Scripts CLAUDE.md Alignment
**Perspective**: Verify `/scripts/CLAUDE.md` matches actual scripts in `scripts/` directory.

**Investigation angles:**
- List all `.py` and `.sh` scripts and compare to documented ones
- Verify mise commands exist in `.mise.toml`
- Check pueue orchestration scripts are documented
- Validate cache population scripts exist

**Use Dynamic Task Creation**: For missing scripts or wrong commands, create sub-tasks.

**After completing your investigation, broadcast your key findings to all peers.**

---

### Task 8: Cross-Reference Consistency Audit
**Perspective**: Verify consistency of cross-references between all CLAUDE.md files.

**Investigation angles:**
- Check links from root CLAUDE.md to nested files are valid
- Verify parent/child relationships documented correctly
- Validate "Related" sections reference existing files
- Confirm hub-and-spoke CLAUDE.md network is accurate

**Use Dynamic Task Creation**: Create sub-tasks to fix broken links or inconsistent references.

**After completing your investigation, broadcast your key findings to all peers.**

---

### Task 9: Public API vs Documentation Parity
**Perspective**: Final comprehensive check comparing documented API to actual code exports.

**Investigation angles:**
- Compare Python `__all__` exports to documented functions
- Check Rust types exported via PyO3 match CLAUDE.md listings
- Verify CLI commands in docs match actual entry points
- Run documented code examples to confirm they work

**Use Dynamic Task Creation**: For each parity gap, create sub-task to update code or docs.

**After completing your investigation, broadcast your key findings to all peers.**

---

## Task Dependencies

### Sequential Dependencies (required)
- **Task 8** depends on all other tasks completing (must have fixed individual files first)
- **Task 9** depends on Tasks 1-7 (needs accurate individual file docs to compare)

### Parallel (independent - can run simultaneously)
- **Tasks 1-7** are independent — each focuses on a different CLAUDE.md file
- Workers can audit their assigned CLAUDE.md in parallel

---

## Execution Instructions

### For Planner
1. Create exactly 9 tasks with the titles above
2. Assign Tasks 1-7 to run in parallel (independent perspectives)
3. Set Task 8 dependsOn: [1,2,3,4,5,6,7]
4. Set Task 9 dependsOn: [1,2,3,4,5,6,7,8]
5. Include Dynamic Task Creation instructions in each task spec

### For Workers (Each Task)
1. Join mesh first
2. Start your assigned task
3. Create scaffolding directory: `mkdir -p /tmp/crew-<perspective>/`
4. Investigate your assigned CLAUDE.md file systematically
5. Use `bash` + `uvx`/`uv` for empirical validation when needed
6. Use `pi_messenger({ action: "task.create", ... })` to spawn follow-up sub-tasks for specific fixes
7. Broadcast findings to peers via `pi_messenger({ action: "send", ... })`
8. Complete your investigation task

---

## Success Criteria

- [ ] All 9 tasks complete their investigation
- [ ] Each task spawns sub-tasks for discovered issues (DCTG pattern)
- [ ] Cross-task findings shared via messaging
- [ ] Final report documents all discrepancies found and actions taken
- [ ] All CLAUDE.md files accurately reflect current code state
