TradingAgents/docs/superpowers/specs/2026-04-07-iteration-system-design.md

Iteration System Design

Date: 2026-04-07
Status: Approved
Scope: Generic iteration system — skills + folder structure for learn-improve-repeat cycles. Demonstrated with trading agent discovery mode but applicable to any iterative system.

---

Problem

Improving the discovery pipeline requires three distinct feedback loops running at different cadences:

1. Fast loop — output quality: does the latest run produce specific, well-reasoned candidates?
2. Slow loop — P&L outcomes: did the picks actually work after 5–10+ trading days?
3. Research loop — strategy sourcing: are there techniques we haven't tried yet that could improve signal quality?

Currently there is no structured way to capture learnings across runs, trace code changes back to evidence, or proactively search for improvements. Knowledge lives in one-off plan docs and in memory.

---

Solution

Two Claude Code skills + a versioned knowledge base in docs/iterations/ + two GitHub Actions workflows that run the skills on a schedule and open PRs for review.

---

Folder Structure

docs/iterations/
├── LEARNINGS.md                        ← master index, one-line per domain entry
├── scanners/
│   ├── options_flow.md
│   ├── insider_buying.md
│   ├── volume_accumulation.md
│   ├── reddit_dd.md
│   ├── reddit_trending.md
│   ├── semantic_news.md
│   ├── market_movers.md
│   ├── earnings_calendar.md
│   ├── analyst_upgrades.md
│   ├── technical_breakout.md
│   ├── sector_rotation.md
│   ├── ml_signal.md
│   ├── minervini.md
│   └── ... (one file per scanner)
├── pipeline/
│   └── scoring.md                      ← LLM scoring, confidence calibration, ranking
└── research/
    └── YYYY-MM-DD-<topic>.md           ← web research findings (append-only, dated)

Each scanner file captures both the implementation learnings and the underlying market thesis — no separate strategies folder since scanners and strategies are currently 1:1.

Domain File Schema

Each file in scanners/, strategies/, and pipeline/ follows this structure:

# <Domain Name>

## Current Understanding
<!-- Best-current-knowledge summary. Updated in place when evidence is strong. -->

## Evidence Log
<!-- Append-only. Each entry dated. -->

### YYYY-MM-DD — <run or event>
- What was observed
- What it implies
- Confidence: low / medium / high

## Pending Hypotheses
<!-- Things to test in the next iteration. -->
- [ ] Hypothesis description

LEARNINGS.md Schema

# Learnings Index

| Domain | File | Last Updated | One-line Summary |
|--------|------|--------------|-----------------|
| options_flow | scanners/options_flow.md | 2026-04-07 | Call/put ratio <0.1 is reliable; premium filter working |
| ... | | | |

---

Skill 1: /iterate

Location: project-local .claude/skills/iterate.md

Trigger

• Automated: GitHub Actions cron, daily at 06:00 UTC (after overnight discovery runs settle)
• Manual: invoke /iterate at any time for an on-demand iteration cycle

Steps

1. Detect mode

   • Scans results/discovery/ for runs not yet reflected in learning files
   • Checks data/positions/ for positions ≥5 days old with outcome data
   • Sets mode: fast (output quality only), pl (P&L outcomes), or both

2. Load domain context

   • Identifies which scanners produced candidates in the target runs
   • Reads the corresponding docs/iterations/scanners/*.md files
   • Reads docs/iterations/LEARNINGS.md for full index awareness

3. Analyze

   • Fast mode: scores signal quality — specificity of thesis, scanner noise rate, LLM confidence calibration, duplicate/redundant candidates
   • P&L mode: compares predicted outcome vs actual per scanner; flags scanners over/underperforming their stated confidence; computes hit rate per scanner

4. Write learnings

   • Appends to the evidence log in each relevant domain file
   • Updates "Current Understanding" section if confidence in the new evidence is medium or higher
   • Updates LEARNINGS.md index with new last-updated date and revised one-liner

5. Implement changes

   • Translates learnings into concrete code changes: scanner thresholds, priority logic, LLM prompt wording, scanner enable/disable
   • In automated mode: implements without confirmation gate
   • In manual mode: presents diff for approval before writing

6. Commit + rolling PR

   • Checks for an existing open PR with branch prefix iterate/current
   • If one exists: pushes new commits onto that branch, updates PR description with the latest findings appended
   • If none exists: creates branch iterate/current, opens a new PR against main
   • Commit message format: learn(iterate): <date> — <one-line summary of key finding>
   • In manual mode: commits directly to current branch (no PR unless on main)
   • On merge: next run automatically opens a fresh PR

Output

At most one open iterate/current PR at any time. It accumulates daily learnings until merged. Merging resets the cycle.

Human reviews PR, merges or closes. No code reaches main unreviewed.

---

Skill 2: /research-strategy

Location: project-local .claude/skills/research-strategy.md

Trigger

• Automated: GitHub Actions cron, weekly on Monday at 07:00 UTC
• Manual: /research-strategy (autonomous) or /research-strategy "<topic>" (directed)

Two Modes

Directed mode: /research-strategy "<topic>"

User names the topic. Skill goes deep on that specific strategy.

Autonomous mode: /research-strategy

No topic given. Skill drives its own research agenda based on current weak spots.

Steps

1. Set agenda

   • Directed: topic is given
   • Autonomous: reads LEARNINGS.md + domain files to identify: low-confidence scanners, pending hypotheses marked for research, gaps in pipeline coverage. Generates 3–5 research topics ranked by potential impact.

2. Search Searches across the default source list:

   • Reddit: r/algotrading, r/quant, r/investing
   • Blogs: QuantifiedStrategies, Hacker News (hn.algolia.com), CSS Analytics, Alpha Architect
   • GitHub: search for quant/scanner/screener repos with recent activity
   • Academic: SSRN quantitative finance, arXiv q-fin
   • Archives: Quantopian community notebooks (via GitHub mirrors)

   For each source: looks for signal definition, entry/exit criteria, known edge, known failure modes, data requirements.

3. Cross-reference

   • Checks existing docs/iterations/ files for overlap with already-implemented or already-discarded approaches
   • Flags redundancy explicitly ("this is a variant of our existing volume_accumulation scanner")

4. Evaluate fit Scores each finding on four dimensions:

   • Data availability — do we already have the required data source?
   • Implementation complexity — hours estimate: trivial / moderate / large
   • Signal uniqueness — how much does it overlap with existing scanners?
   • Evidence quality — backtested with stats / qualitative analysis / anecdotal

5. Write research files

   • Saves findings to docs/iterations/research/YYYY-MM-DD-<topic>.md for all findings
   • Adds entries to LEARNINGS.md

6. Implement and rolling PR

   • In automated mode: implements the top-ranked finding automatically (score threshold: data availability = present, evidence quality ≥ qualitative, complexity ≤ moderate)
   • In manual directed mode: presents ranked findings, implements user-selected one
   • Checks for an existing open PR with branch prefix research/current
   • If one exists: pushes new commits onto that branch, updates PR description with new findings appended
   • If none exists: creates branch research/current, opens a new PR against main
   • Commits: research(<topic>): add <scanner-name> scanner — <one-line rationale>
   • On merge: next run automatically opens a fresh PR

Safety threshold for autonomous implementation

Only auto-implement if ALL of:

• Required data source already integrated (no new API keys needed)
• Complexity estimate: trivial or moderate
• Signal uniqueness score: low overlap with existing scanners Otherwise: commits research files only, opens PR flagged needs-review with explanation of why auto-implementation was skipped.

---

Generic Applicability

The skill logic is domain-agnostic. To apply this system to a non-trading iterative project:

1. Replace results/discovery/ with the project's run output directory
2. Replace data/positions/ with whatever measures outcome quality
3. Replace the scanner domain files with the project's equivalent components
4. Replace the research source list with domain-appropriate sources

The folder structure and skill steps are unchanged.

---

GitHub Actions Workflows

.github/workflows/iterate.yml

schedule: cron '0 6 * * *'   # daily at 06:00 UTC

• Checks out repo
• Runs Claude Code with /iterate skill non-interactively
• Uses ANTHROPIC_API_KEY secret
• Creates branch iterate/YYYY-MM-DD, commits, opens PR

.github/workflows/research-strategy.yml

schedule: cron '0 7 * * 1'   # weekly, Monday at 07:00 UTC

• Same setup as above, runs /research-strategy (autonomous mode)
• Creates branch research/YYYY-MM-DD, commits, opens PR
• If safety threshold not met: opens PR with needs-review label, no code changes

Required secrets

• ANTHROPIC_API_KEY — Claude API access
• GH_TOKEN — PAT with repo scope for branch creation and PR opening

---

Non-Goals

• No auto-merge — all PRs require human review before reaching main
• No dashboard or UI — all output is markdown + git commits
• No cross-project knowledge sharing — each project's docs/iterations/ is independent