# PRD.md - Wire All Touchpoints to Symbol Registry (SSoT)

## PROSTAT

Look for opportunity where something is not doing. Look for opportunity while any of the touchpoints or boundaries that are or any internal logics are not wired to the symbol registry or central, single source of truth for parameter values. If they do, we have to identify them. And then propose ways that we can resolve them and remark them so that we have everything ready for later implementation with these guides.

---

## Background

This project (opendeviationbar-py) has a Symbol Registry at symbols.toml — the Single Source of Truth (SSoT) for all symbol metadata including:
- min_threshold — minimum threshold in decimal basis points (dbps)
- thresholds — list of valid thresholds per symbol
- listing_date — when symbol started trading
- effective_start — first date with clean/usable data
- asset_class, exchange, market — symbol classification
- enabled — whether symbol is active

The Problem: Many parts of the codebase have hardcoded threshold values (250, 500, 750, 1000 dbps), listing dates, or other symbol-specific parameters instead of querying the symbol registry. This creates:
1. Data drift — changes to symbols.toml dont propagate
2. Inconsistency — different parts use different defaults
3. Maintenance burden — updates must be made in multiple places
4. Bugs — invalid symbol/threshold combinations may be processed

---

## Objectives

1. Audit each code touchpoint for hardcoded symbol parameters
2. Identify boundaries where symbol registry should be queried but isnt
3. Propose resolution strategies (wire to registry, remove hardcoding, add validation)
4. Document findings for later implementation

---

## 9 Investigative Perspectives (Tasks)

### Task 1: Python Constants Module Audit
Perspective: Audit python/opendeviationbar/constants.py for hardcoded threshold values.

Investigation angles:
- Check DEFAULT_THRESHOLD and THRESHOLD_PRESETS against symbols.toml defaults
- Verify OPENDEVIATIONBAR_CRYPTO_MIN_THRESHOLD matches registry defaults
- Identify any hardcoded symbol names (e.g., BTCUSDT)
- Compare TIER1_SYMBOLS constants to enabled symbols in registry

Use Dynamic Task Creation: After initial audit, if you find specific hardcoded values that should come from registry, create sub-tasks to identify the fix approach and document current vs expected behavior.

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

---

### Task 2: CLI/Tool Entry Points Audit
Perspective: Audit Rust tools and Python CLI entry points for hardcoded thresholds.

Investigation angles:
- Check tools/chart/src/main.rs default threshold (line 59: default_value_t = 250)
- Audit any other CLI tools in tools/ for hardcoded thresholds
- Verify Python CLI entry points in python/opendeviationbar/ use registry
- Check .mise.toml commands for hardcoded threshold values

Use Dynamic Task Creation: After finding hardcoded defaults, create sub-tasks to document each tools threshold source and propose how to wire to registry.

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

---

### Task 3: ClickHouse Cache Layer Audit
Perspective: Audit ClickHouse cache queries for hardcoded thresholds and symbols.

Investigation angles:
- Check python/opendeviationbar/clickhouse/cache.py for hardcoded BTCUSDT and threshold values
- Review bulk_operations.py for hardcoded symbol/threshold combinations
- Audit maintenance.py for hardcoded values in deduplication queries
- Verify schema uses registry for threshold validation

Use Dynamic Task Creation: Create sub-tasks to document each hardcoded query and propose parameterized alternatives.

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

---

### Task 4: Configuration Modules Audit
Perspective: Audit config modules for hardcoded defaults that should come from registry.

Investigation angles:
- Check config/algorithm.py for OPENDEVIATIONBAR_ALGORITHM_DEFAULT_THRESHOLD_DECIMAL_BPS
- Audit config/sidecar.py for threshold handling vs registry
- Review config/population.py for OPENDEVIATIONBAR_CRYPTO_MIN_THRESHOLD usage
- Check config/backfill.py for hardcoded failure thresholds

Use Dynamic Task Creation: Create sub-tasks to compare config defaults vs registry and propose wiring strategy.

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

---

### Task 5: Scripts Directory Audit
Perspective: Audit scripts/ for hardcoded symbols and thresholds.

Investigation angles:
- Search all .py scripts for hardcoded threshold values (250, 500, 750, 1000)
- Check for hardcoded BTCUSDT or other symbol names in scripts
- Audit populate_full_cache.py, backfill_watcher.py, kintsugi.py
- Review validation scripts (validate_*.py) for hardcoded test values

Use Dynamic Task Creation: Create sub-tasks for each script category to document hardcoded values.

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

---

### Task 6: Backfill and Population Pipeline Audit
Perspective: Audit data pipeline code for hardcoded thresholds and symbol lists.

Investigation angles:
- Check python/opendeviationbar/backfill/ for hardcoded thresholds
- Audit population logic in python/opendeviationbar/population.py if exists
- Review checkpoint logic (checkpoint.py) for threshold handling
- Check sidecar streaming (sidecar.py) for threshold validation vs registry

Use Dynamic Task Creation: Create sub-tasks to document pipeline touchpoints that need registry integration.

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

---

### Task 7: Rust Crates Audit
Perspective: Audit Rust crates for hardcoded threshold values.

Investigation angles:
- Check crates/opendeviationbar-core/ for hardcoded threshold values in tests
- Review processor.rs for default threshold handling
- Audit any Rust CLI tools for hardcoded defaults
- Check PyO3 bindings for threshold parameter passing

Use Dynamic Task Creation: Create sub-tasks to document Rust-side hardcoding and propose solutions.

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

---

### Task 8: Symbol Registry Integration Points Audit
Perspective: Audit existing symbol registry usage patterns.

Investigation angles:
- Review symbol_registry.py for what fields are currently exposed
- Check which parts of codebase already use the registry correctly
- Identify missing registry fields that would help eliminate hardcoding
- Audit compat/availability.py for registry integration

Use Dynamic Task Creation: Create sub-tasks to propose registry enhancements needed to support all touchpoints.

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

---

### Task 9: Cross-Cutting Synthesis and Resolution Strategy
Perspective: Synthesize all findings and propose resolution strategy.

Investigation angles:
- Aggregate all hardcoded values found across tasks 1-8
- Categorize by type: threshold defaults, symbol lists, listing dates, etc.
- Identify dependencies: what can be wired immediately, what needs registry enhancement
- Propose implementation phases: quick wins vs architectural changes
- Document migration strategy for each category

Use Dynamic Task Creation: Create sub-tasks for create comprehensive findings matrix, draft implementation plan, identify quick-win fixes.

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

---

## Task Dependencies

Sequential Dependencies (required):
- Task 9 depends on Tasks 1-8 (needs all audit findings to synthesize)
- Tasks 1-8 can run in parallel — each investigates a different code area

Parallel (independent - can run simultaneously):
- Tasks 1-8 are independent — each focuses on a different code module/section

---

## Execution Instructions

For Planner:
1. Create exactly 9 tasks with the titles above
2. Assign Tasks 1-8 to run in parallel (independent perspectives)
3. Set Task 9 dependsOn: 1,2,3,4,5,6,7,8
4. Include Dynamic Task Creation instructions in each task spec
5. Workers should create scaffolding directories under /tmp/crew-perspective/

For Workers (Each Task):
1. Join mesh first: pi_messenger({ action: join })
2. Start your assigned task
3. Create scaffolding directory: mkdir -p /tmp/crew-perspective/
4. Investigate your assigned code area systematically using bash + grep/ripgrep
5. Use uvx or uv run for empirical validation when needed
6. Use pi_messenger({ action: task.create, ... }) to spawn follow-up sub-tasks for specific findings
7. Use pi_messenger({ action: send, ... }) to share cross-cutting discoveries
8. Complete your investigation task with clear findings

---

## Success Criteria

- All 9 tasks complete their investigation
- Each task spawns sub-tasks for specific hardcoded values found (DCTG pattern)
- Cross-task findings shared via messaging
- Final synthesis (Task 9) documents all hardcoded values by category
- Resolution strategy proposed with implementation phases
- Clear roadmap for wiring all touchpoints to symbol registry
