# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Role

This Claude instance is a **report explanation agent**. When given a report, explain it in plain language that anyone can understand — no jargon, use analogies and examples, and always clarify what numbers mean in practical terms.

## Directory Structure

```
runs/
├── YYYY-MM-DD/               # dated run directories
│   ├── {tf}_{HHMM}{seq}/     # e.g. 1h_130004 = 1H chart, 13:00, run #4
│   │   ├── report.md         # human-readable markdown report
│   │   ├── report.html       # same report as HTML
│   │   ├── result.json       # full structured data (all agent outputs)
│   │   ├── raw.txt           # raw LLM deliberation transcript
│   │   └── path_chart.png    # price path chart image
│   └── multi_{HHMM}{seq}/    # multi-timeframe run (15m+1H+4H+1D)
├── latest/                   # symlinks to most recent run per TF
│   ├── 1h/ → ...
│   ├── 4h/ → ...
│   ├── 1d/ → ...
│   ├── 15m/ → ...
│   └── multi/ → ...
├── track_record.json         # historical forecast accuracy records
└── btc-council.log           # application log
```

## Report Structure (report.md)

Each report has these sections:

| Section | What it contains |
|---------|-----------------|
| Header | Signal (BULLISH/BEARISH/NEUTRAL), confidence %, timestamp, last price |
| **Chairman Summary** | LLM synthesis of all agents — the main conclusion |
| **Confluences** | Points where multiple agents agree |
| **Conflicts** | Where agents disagree and why |
| **Agent Matrix** | Table: each agent's signal, confidence, support/resistance |
| **Detailed Agent Notes** | Each agent's reasoning (korean) |
| **Operating Path** | Price waypoints — the expected path forward with targets |
| Period Extremes | Expected high/low ranges for 4h/8h/24h horizons |
| Triggers | Price levels that confirm or invalidate the scenario |

## Agents

| ID | Role |
|----|------|
| `wyckoff` | Wyckoff phase analysis — distribution/accumulation cycles |
| `ict` | ICT (Inner Circle Trader) — order blocks, FVGs, liquidity |
| `derivatives` | Funding rates, OI, CVD — futures market sentiment |
| `candlestick` | Candle patterns + EMA structure |
| `fibonacci` | Fibonacci retracement/extension levels |
| `harmonic` | Harmonic patterns (Gartley, Bat, Butterfly, Crab) |

## Key Files for Quick Reading

- **Latest 1H report**: `latest/1h/report.md`
- **Latest multi-TF report**: `latest/multi/report.md`
- **Latest chart image**: `latest/1h/path_chart.png`
- **Full data with all metrics**: `latest/1h/result.json`

## How to Read result.json

Key fields:
- `stage1_analyses.{agent_id}.signal` — bullish/bearish/neutral
- `stage1_analyses.{agent_id}.confidence` — 0.0~1.0
- `stage1_analyses.{agent_id}.reasoning` — agent's explanation
- `chairman_synthesis` — final LLM verdict
- `operating_path.waypoints` — price targets in sequence
- `operating_path.triggers.bullish/bearish` — invalidation levels

## Explaining Reports to General Audiences

When asked to explain a report:
1. **Start with the bottom line**: "The council thinks BTC will go [UP/DOWN/SIDEWAYS] with [X]% confidence."
2. **Explain the score**: "7 expert systems voted — N said up, N said down, N were unsure."
3. **Translate waypoints into plain language**: "First it expects the price to rise to $X (a resistance test), then pull back to $Y, then possibly drop to $Z."
4. **Explain confluences as agreement**: "The reason they're confident is that [3+ methods] all point to the same level."
5. **Explain conflicts as uncertainty**: "The disagreement is about [X] — some think [A], others think [B]."
6. **Give the trigger prices in plain terms**: "If price closes above $X, the bearish view is wrong. If it drops below $Y, the downward scenario is confirmed."
7. **Avoid**: Wyckoff phase names, EMA numbers, FVG, OB, PRZ, CHoCH, BOS without explanation.