Imported from jhonnyisaacc/nave (AGENTS.md). Install upstream with npx skills add jhonnyisaacc/nave. Copyright stays with the author.

AGENTS.md — nave trading theory refinement

Branch: feat/theory_refinement

This file guides Claude Code through the iterative theory refinement process for the nave trading project.

Source of truth

Trading timeframes

This system operates on a top-down multi-timeframe structure:

Weekly  → macro bias + COT positioning (direction filter)
Daily   → trend confirmation + key levels (swing structure)
4H      → setup formation + entry zone identification
1H      → precise entry trigger + execution timing

All pattern recognition, entry rules, invalidation levels, and COT application must be documented with explicit timeframe context. A pattern valid on 4H is not automatically valid on 1H — document both.

PHASE 1 — Theory refinement (docs only, no code changes)

Goal

Read docs/elcriptopanavideos.md in full and integrate everything relevant into the three YAML theory files.

Rules

• Do not modify any file outside docs/
• One commit per modified YAML file
• Commit message format: theory: [what improved] - phase1
• If there is a contradiction between the videos and current theory, document it in docs/analysis/contradictions.md before resolving it

What to extract from the transcripts

• Entry and exit patterns not yet documented
• Setup invalidation rules
• Timing and confluence factors missing from technical.yaml
• Liquidity, order block, FVG concepts that expand terms.yaml
• COT logic that complements or corrects cot_integration.yaml
• Explicit Chain of Thought: how the analyst reasons step by step
• Any 4H/1H specific rules, triggers, or execution criteria

Phase 1 expected output

• docs/technical.yaml — updated with refined patterns, 4H/1H rules explicit
• docs/cot_integration.yaml — updated COT logic
• docs/terms.yaml — expanded glossary
• docs/analysis/theory_changelog.md — what changed and why

PHASE 2 — Historical backtesting + trading/ refactor

Prerequisite

Phase 1 completed and committed.

Goal

Apply the refined theory to the BTC and ETH historical record (10 years) using all available nave indicators. At the end, refactor trading/ to reflect the updated theory, with execution logic targeting 4H and 1H.

Iteration loop

REPEAT until convergence:
  1. Read current theory: docs/technical.yaml + docs/cot_integration.yaml
  2. Select the NEXT unanalyzed period (see list below)
  3. Run: python scripts/theory_backtest.py --period  --coins BTC ETH
  4. Read the JSON output
  5. Identify the most frequent failure pattern in that period
  6. Make ONE concrete improvement to the theory (not multiple at once)
  7. Document in docs/analysis/iterations/iter_N.md:
       - Period analyzed
       - Signals generated by the theory
       - Correct calls and misses
       - What changed and why
       - 4H/1H execution notes (where would entry have triggered?)
  8. Commit: "theory: [improvement] - iter N - [period]"
  9. Back to step 1 with the next period

Periods in order

1. 2017-bull+2018-bear      (formation cycle)
2. 2019-recovery            (post-bear accumulation)
3. 2020-covid-crash         (black swan)
4. 2020-recovery+2021-ATH   (full bull with double top)
5. 2022-bear                (Luna + FTX cascade)
6. 2023-recovery            (re-accumulation)
7. 2024-ETF-approval        (macro fundamental event)
8. 2024-2025-bull           (current pre-today cycle)
9. TODAY                    (live setup)

COT note: historical COT data available from ~2022 onward. For earlier periods use price + macro only (TGA, RRP, rates, DXY).

Available nave indicators

• nave cot analyze --coins BTC ETH (from 2022)
• nave data fetch aaii
• scripts/openbb_tools.py (TGA, RRP, VIX, yields)
• trading/signals.py

Per-period multi-timeframe analysis

Weekly  → was the macro bias correct?
Daily   → were key swing levels respected?
4H      → where did setups form? were entries valid by the theory?
1H      → where was the precise trigger? was the entry timing tight?

Convergence criteria

Stop when ONE of these is met:

• 3 consecutive iterations produce no theory improvements
• The TODAY period is analyzed and current setup is documented
• 20 iterations reached (pause and ask the user)

Phase 2 expected output

• docs/analysis/btc_eth_historical_review.md
• docs/analysis/current_setup.md — live BTC and ETH setup as of today with explicit 4H entry zones, 1H trigger conditions, invalidation levels, targets
• docs/analysis/iterations/iter_1.md ... iter_N.md
• trading/ refactored to reflect the final theory

trading/ refactor goals

• trading/strategy.py — strategies implementing refined patterns, 4H/1H execution
• trading/signals.py — timeframe-aware signals (each signal declares which TF it fires on)
• trading/cot/ — updated COT pipeline
• trading/execution.py — entry/exit logic for 4H and 1H
• Tests in tests/ for new theory rules
• Final commit: refactor(trading): align with refined theory v2 - 4H/1H execution

How to resume in any session

ls docs/analysis/iterations/
git log --oneline docs/technical.yaml | head -5
claude  # then: "Resume the theory refinement loop from where it left off"

Constraints

• Never modify trading/ during Phase 1
• Never commit changes to trading/ without completing Phase 2
• Do not change multiple theoretical concepts in a single commit
• If OpenBB data fails for a period, log the gap and continue
• If transcript intent is ambiguous, document in docs/analysis/contradictions.md
• Every entry rule in the final theory must specify: which timeframe, what the 4H trigger is, what the 1H entry signal looks like

Codex execution mode

Codex must operate in continuous loop mode.

Entry point

Run:

python scripts/run_theory_loop.py

After each execution

Codex must:

1. Read latest output from scripts/theory_backtest.py
2. Analyze failures
3. Modify ONE of:
   • docs/technical.yaml
   • docs/cot_integration.yaml
   • docs/terms.yaml
4. Write iteration file:
   • docs/analysis/iterations/iter_N.md
5. Commit changes
6. Re-run the loop

Goal

Continue iterating autonomously until convergence criteria is met.

Do NOT stop after one iteration.