The meta tutorial

Reproduce this from scratch

This page is a report about itself. It walks the exact steps used to build this project with AI (starting from an empty folder, no repo, nothing) so anyone can replicate the method on their own research question. It's a living document: it grows as the project advances.

The pipeline we ran

Before the from-scratch rebuild below, here's the actual run in one table: what each stage took in, what it produced out, and where to see the evidence.

flowchart TD
  A["The brief — RO investor, ~EUR 30-70k, 2026 backdrop"] --> B["Ask the AI: list every factor that could matter"]
  B --> C["Factor map — ~55 factors, 6 layers"]
  C --> D["Research the decision-drivers, one deep dive each"]
  D --> R1["Lei or euro?"]
  D --> R2["RO stocks — cheap or dear?"]
  D --> R3["AI/tech from Europe?"]
  D --> R4["Defense — trend or spike?"]
  D --> R5["Oil & energy security?"]
  D --> R6["Where's the real bond yield?"]
  D --> R7["Gold or crypto to diversify?"]
  R1 --> E["Aggregate into 25 cited insights"]
  R2 --> E
  R3 --> E
  R4 --> E
  R5 --> E
  R6 --> E
  R7 --> E
  E --> F{"Central finding: inflation 10.9% > every safe yield"}
  F --> P1["Narrow bonds: tax-free Fidelis anchor"]
  F --> P2["European equity = the engine"]
  F --> P3["Gold/crypto researched, excluded by mandate"]
  F --> P4["Sleeve, defense-led; all-in-AI <= ~15%"]
  P1 --> G["Persona debate: worrier, go-getter, steady hand, macro"]
  P2 --> G
  P3 --> G
  P4 --> G
  G --> H["Five strategies: Defensive/Moderate/Aggressive x small/large (Moderate the base case)"]
  H --> I["This report"]

Part 1: Start from nothing

1. Install Claude Code

   Install the CLI and authenticate it with your Anthropic account.

   npm install -g @anthropic-ai/claude-code
   claude   # first run walks you through login

2. Create an empty project

   mkdir investment-research && cd investment-research

3. Write a README that states the goal

   Before any tooling, write down, in plain language, the scenario, the constraints, and the shape of the deliverable. This README is what you'll brainstorm against. Ours described a fictional Romanian investor, a ~20–100k EUR portfolio, a low-risk core + ≤20% risk-on sleeve, the 2026 geopolitical context, and a final interactive report.

4. Open Claude Code and brainstorm the scope

   Ask it to read the README and interview you about scope before touching code. The decisions we locked here shaped everything downstream:

   Question	Our answer
   Report tech	Vanilla HTML/CSS/JS, no build step
   Language	English
   Research result format	Markdown, committed to the repo
   Live web access	Yes: pull real BT/instrument/context data
   Who runs research	Claude runs the deep-research avenues
   Strategy archetypes	Conservative / Balanced / Growth

Part 2: Scaffold the repository

With scope agreed, have the agent lay down the folder structure and initialize git. The shape mirrors the pipeline (inputs → research → analysis → strategies → report):

investment-research/
├── README.md                 the brief
├── CLAUDE.md                 the project "overseer" (read every session)
├── docs/specs/               the approved design spec
├── process/                  the working pipeline, in order
│   ├── 1-inputs/             input factors (profile, geopolitics, trends, BT)
│   ├── 2-research/
│   │   ├── avenues/          research briefs + backlog (the exact prompts)
│   │   └── results/          cited Markdown results
│   ├── 3-analysis/
│   │   ├── aggregated-insights.md
│   │   └── decisions/        one evidence dossier per key decision
│   ├── 4-debate/             the skeptic/opportunist/conservator debate
│   └── 5-strategies/         conservative / balanced / growth
├── report/                   the shareable vanilla-HTML deliverable
└── .claude/                  agents + skills (below)

git init

Part 3: Build the Claude Code setup

This is what makes the process repeatable rather than ad-hoc. Three pieces:

① CLAUDE.md: the overseer

A project-root file Claude reads at the start of every session. It states the mission, the pipeline, the operating rules (evidence over assertion, reproducibility, the ≤20% cap, BT-only universe, "not advice"), and how to pick up work. It's the brain that keeps every session consistent.

② Agents: roles with a fixed brief

Markdown files in .claude/agents/, each a specialist the orchestrator can dispatch:

• 📊 bt-instruments-analyst: verifies every ticker is actually buyable on BT Trade and maps abstract sleeves to real instruments.
• 🛑 persona-skeptic: argues every decision from "what goes wrong".
• 🚀 persona-opportunist: argues for return and using the risk cap.
• ⚖️ persona-conservator: defends the steady, diversified default.

---
name: bt-instruments-analyst
description: When to use this agent…
tools: Read, Grep, Glob, WebSearch, WebFetch, Write, Edit
---

System prompt: the agent's job, rules, and output format.

③ Skills: repeatable procedures

Folders in .claude/skills/<name>/SKILL.md, each a playbook the agent follows the same way every time:

• 🔎 run-research-avenue: brief → deep research → cited result doc (keeps the verbatim prompt).
• 🧩 aggregate-insights: results → traceable insight ledger + decision dossiers.
• 🛠️ build-report: source Markdown → regenerate these HTML pages.

Part 4: Prepare for the research

1. Map the whole field first

   Before deep-diving anything, set the AI a wide goal: list every factor that could matter (local, European, global, macro, structural, personal). Ours returned ~55 factors across six tiers (docs/factors.md), about 35 of them ones we hadn't thought of. This map decides which questions are worth researching deeply next.

2. Fill the input factors

   Profile (confirmed with you), then geopolitics, market trends, constraints, and the BT Trade universe. The last four were pulled from live, dated sources.

3. Author the research avenues

   Turn each unknown into a brief with a goal, key questions, required outputs, and the exact prompt. Queue them in a backlog with a status.

4. Run deep research, one avenue at a time

   Fan-out search → fetch sources → adversarially verify → cited synthesis → a Markdown result committed next to its brief. New questions become new avenues.

Inspect the research

Each unknown became a self-contained brief with the exact prompt, run via a deep-research pass, and answered by a cited Markdown result in process/2-research/results/. Open any result below to read what we asked, its key findings, and its sources. Download the full result as Markdown from there.

01/06/08 were satisfied by the input factors (now under Factors); 02 moved straight to the decision stage. The 14 deep-research results that produced standalone, citable docs are below. Live backlog: process/2-research/avenues/README.md.

Part 5: Aggregate into insights & decisions

Run the aggregate-insights skill once two or more results exist. It collapses many cited results into one ledger where each insight links back to its source, a confidence tag, and the decision it informs; then turns those into one evidence dossier per decision. Disagreements between sources are kept, not smoothed over: they become the raw material for the debate.

Part 6: Debate, verify, and converge

This is where the method earns its trust. Three things, two of them adversarial:

1. Run the persona debate (parallel)

   Dispatch the persona agents in one batch: a skeptic, an opportunist, a conservator, and a macro-and-thematic strategist. They argue every decision from the committed evidence only, then you reconcile their clash into a synthesis. Ours collapsed into a set of dials that map onto the five strategies (a 3×2 grid).

2. Clear the BT reality-check gate

   Before any strategy names a ticker, the bt-instruments-analyst agent verifies each instrument is actually orderable on BT Trade, grading every ISIN confirmed / likely / unconfirmed into a durable shortlist.

3. Build the five strategies & converge

   Turn the dials + the verified shortlist into concrete %-of-capital portfolios (Defensive / Moderate / Aggressive × small/large capital, a 3×2 grid, one cell empty), then write the convergence: same skeleton, only the dials move; pick by risk appetite, capital size, and the disinflation fork.

Part 7: Generate the report

Run the build-report skill. It regenerates these vanilla-HTML pages from the settled Markdown. No build step, no CDN, no fetch() of local JSON (shared data lives in assets/data/data.js as a global), charts are inline SVG. The report is always downstream of the evidence and never gets ahead of it.

Progress log

Updated as the project moves, so this tutorial always reflects reality.

• done Brainstormed scope; locked the six scope decisions.
• done Scaffolded the repo + git; committed the design spec.
• done Built the Claude Code setup: CLAUDE.md, 4 agents, 3 skills.
• done Built this report shell (8 pages, shared nav, inline-SVG charts).
• done Reorganized the repo into an ordered process/ pipeline (1-inputs … 5-strategies).
• done Confirmed the investor profile (€30–70k band, dual horizon, no emergency reserve, research-don't-exclude).
• done Populated all input factors via live web research: three parallel subagents (geopolitics, market trends, BT universe), each writing dated, sourced Markdown (snapshot 2026-06-29).
• done Authored the decision-deep avenue briefs (with verbatim prompts) and ran the first batch: four parallel subagents (RON/EUR, RO equities, EU/US UCITS ETFs, the risk-on sleeve) → cited result docs.
• done Aggregated the results into a traceable 14-insight ledger + four evidenced decision dossiers, and proposed a three-tier portfolio architecture.
• done Ran the persona debate: three parallel agents (skeptic / opportunist / conservator) argued the four decisions from committed evidence; reconciled into a synthesis with five dials.
• done Cleared the BT reality-check gate: verified every candidate instrument by ISIN into a graded shortlist (confirmed / likely / unconfirmed).
• done Built the three strategies (Conservative / Balanced / Growth) with concrete %-of-capital allocations, and converged on Balanced as the base case.
• done Regenerated the report and wired real allocations into the charts.
• done Pivoted to a more-aggressive, Romanian + European-only posture. Ran a second research batch (7 parallel avenues 09–15: tech/AI, defense, oil&gas, energy/nuclear, the macro risk-map, bonds, gold/crypto) + a RO+EU instrument-universe pass, grounded in a 55-factor map. Refreshed the macro inputs with the three 2026 regime-shifts.
• done Re-aggregated to an 18-insight ledger; ran an extended four-voice debate (added a Macro & Thematic Strategist; each gives pros and cons), resolving the all-in-AI ceiling to ~15%.
• done Rebuilt three clearly-distinct strategies (Defensive / Moderate / Aggressive) and recommended Moderate.
• done Built the Factor → Investment Reaction Map (now 23 factors × 11 directions, persona-wired) via four parallel sub-agents, and reframed the report as a classical portfolio report.
• done Stress-tested the "AI-bubble pops" scenario. Ran a third research batch (3 parallel avenues 16–18: the steel-manned bear thesis, datacenter overbuild vs demand, and portfolio contagion + hedges) and aggregated it into a dedicated scenario report (ai-bubble-scenario.md) + insights I19–I21. Finding: the pop is a margin re-rating (not a datacenter glut), it hits core + sleeve together, and the free first-line hedge is total-AI sizing — reinforcing the architecture.
• done v3 reshape. Capital reframed as a mid-size €20–90k band (dropped the €50k anchor; % of capital is the canonical unit). Gold, cash and crypto excluded from the universe by mandate — RO+EU ETFs/equity, RO state bonds, and EU bond UCITS only. The reaction map grew to 23 factors × 11 directions, the insight ledger to 25, and the strategies to five, across a 3×2 grid (Defensive / Moderate / Aggressive × small/large capital, Moderate the base case).