alive-analysis

Structured analysis workflow for AI coding agents — every analysis traceable, repeatable, and team-shareable.

Why this exists

You ask Claude to investigate a metric drop. It gives you an answer. You act on it.

Three months later: "Why did we change that?" — gone. No reasoning, no data checks, no audit trail.

Or you open a new chat and explain the whole context again from scratch, repeating work that already happened.

alive-analysis solves this by turning every analysis into a structured, version-controlled workflow. Claude guides you through a five-stage loop. Each stage produces a markdown file. Everything stays in your repo, searchable by you and by Claude.

The result: a growing knowledge base of how your team thinks, not just what it decided.

How it works

You describe a question  →  /analysis-new
                                 ↓
         Claude walks you through 5 stages:
         ASK → LOOK → INVESTIGATE → VOICE → EVOLVE
                                 ↓
              Each stage = one markdown file in analyses/
                                 ↓
         Files are Git-tracked, full-text searchable,
         readable by Claude in future conversations
                                 ↓
         Six months later: /analysis-search "checkout drop"
         → Claude surfaces context, findings, and follow-ups

Installation

# Clone the repo
git clone https://github.com/with-geun/alive-analysis.git /tmp/alive-analysis

# Install — pick your platform
bash /tmp/alive-analysis/install.sh              # Claude Code
bash /tmp/alive-analysis/install.sh --cursor     # Cursor
bash /tmp/alive-analysis/install.sh --both       # Both

# One-time setup — run in your AI agent chat (not the terminal)
/analysis-init    # Configure language, team, data stack, key metrics
/analysis-new     # Start your first analysis

That's it. Claude handles the rest.

The ALIVE Loop

Every analysis follows the same five-stage structure. Each stage has a clear purpose, a checklist, and a quality gate before moving forward.

You never skip a stage without a deliberate choice. The loop enforces analytical discipline — even when you're in a hurry.

Three Modes

Full Mode — for decisions that matter

Five separate files, one per stage. ~40-item checklists. All specialist agents available. Use this when the decision is high-stakes, when you'll need to explain your reasoning, or when you want the full audit trail.

analyses/active/F-2026-0303-001_checkout-drop/
├── 01_ask.md
├── 02_look.md
├── 03_investigate.md
├── 04_voice.md
└── 05_evolve.md

Quick Mode — for fast turnaround

Everything in one file. Compressed checklist. Same ALIVE structure, just lighter. Use this for exploratory questions, morning standups, or anything you need in under an hour. If it grows in scope, /analysis-promote converts it to Full automatically.

analyses/active/quick_Q-2026-0308-001_dau-check.md

Learn Mode — for building the skill

Guided scenarios with rubric-based scoring, progressive hints, and common-mistake detection. Seven real-world scenarios across two levels. Use this onboard new analysts, practice unfamiliar analysis types, or train interns.

analyses/active/L-2026-0220-002_signup-drop-scenario/

All Commands

Core workflow

Finding and reviewing past work

Specialist agents

Experiments and monitoring

Education mode

31 Specialist Agents

At each ALIVE stage, a routing engine reads your analysis context and recommends the right specialists from a pool of 31 agents. You choose which ones to run.

Required gates (auto-run, no confirmation needed)

These four run automatically when their trigger condition is met:

Optional specialists by stage

ASK — problem-framer, hypothesis-gen, metric-translator, sampling-designer

LOOK — data-scout, tracking-auditor, lineage-mapper, sql-writer

INVESTIGATE — eda-agent, stats-agent, experiment-designer, causal-agent, root-cause-analyst, ml-agent, forecast-agent, anomaly-detector, chart-recommender, dashboard-designer, peer-reviewer

VOICE — narrative-agent, exec-summarizer, decision-memo-writer

EVOLVE — metric-definer, semantic-layer-engineer, governance-steward

The routing engine scores each agent against your current context (analysis type, domain, data signals) and presents the top 3 with a plain-language explanation: "This analysis involves a before/after metric change with no randomization — the causal-agent can assess whether DID or RDD is appropriate here."

Agents can be disabled per-project in .analysis/agents.yml.

Experiment Support (A/B Testing)

When you run /analysis-new and choose Experiment type, the ALIVE loop adapts:

DESIGN → VALIDATE → ANALYZE → DECIDE → LEARN

Key enforcements:

• Pre-registration lock: Analysis plan is written and locked before results are revealed — prevents post-hoc rationalization
• SRM detection: Sample Ratio Mismatch flagged automatically during VALIDATE
• Guardrail metrics: Counter-metrics defined alongside primary metric to catch unintended side effects
• Multiple comparison correction: Alerts when running many variants without adjustment
• Statistical validity: The stats-agent verifies power, sample size, and test selection before you call significance

Metric Monitoring

/monitor-setup

Configure thresholds for your key metrics. When an alert fires, escalate it directly into an analysis:

/analysis-new --from-alert {alert-id}

The ALIVE context pre-fills with the alert data — metric name, value, time window, relevant segments. You start at ASK with context already loaded.

Analysis Search and Retrospective

Search across all past analyses

/analysis-search "checkout funnel"

Full-text search across titles, hypotheses, findings, and follow-ups. Returns matching analyses with surrounding context, cross-references to related analyses, and suggestions for follow-up work.

Automatic retrospective

/analysis-retro --last-quarter

Aggregates all analyses in a period into a structured report:

• Activity summary (analyses by type, analyst, stage completion)
• Impact tracking (recommendations → decisions → outcomes)
• Recurring patterns and unresolved follow-ups
• Team-level metrics (acceptance rate, decision speed, analysis accuracy over time)

Output: analyses/.retro/retro_{period}.md

Analysis Memory System (v1.4)

Two features that give your team persistent analytical memory — so knowledge compounds instead of disappearing into chat history.

Decision Records — /analysis-dr

An append-only log of methodology decisions, adapted from the software engineering concept of Architecture Decision Records (ADR).

The problem it solves: Claude keeps suggesting "what if we try Bayesian A/B testing?" even though your team decided that two months ago. Or a new analyst uses a different DAU definition than everyone else. Decision Records prevent this by giving AI a permanent record of what's already been decided — and why.

Five decision types:

Append-only: Decisions are never edited or deleted. If reversed, the old DR is marked Superseded by DR-NNN — so future analysts understand why the team thought differently at that time.

/analysis-dr new        # Write a new decision record
/analysis-dr scan       # Find DR candidates from existing analyses
/analysis-dr list       # Show all recorded decisions
/analysis-dr show 003   # Show DR-003 in detail

DRs integrate with the agent system — 6 methodology-suggesting agents (hypothesis-gen, stats-agent, metric-definer, metric-translator, experiment-designer, causal-agent) check decision records before suggesting alternatives. No more debating the same methodology question twice.

Analysis Wiki — /analysis-wiki

A structured, AI-maintained knowledge base compiled from your team's analyses. Based on Andrej Karpathy's LLM Wiki concept: instead of searching raw files every time, AI pre-compiles knowledge into structured pages that grow as analyses accumulate.

How it works: After archiving analyses, run /analysis-wiki update. AI reads every archived analysis and builds structured pages:

• analyses/wiki/metrics/dau.md — everything learned about DAU across all analyses: key findings, validated/rejected hypotheses, watch points
• analyses/wiki/patterns/simpson-paradox.md — recurring patterns with context on when and how they appeared
• analyses/wiki/hypotheses/INDEX.md — cross-analysis hypothesis results (prevents re-testing what's already answered)

Health checking: /analysis-wiki check finds contradictions (same hypothesis validated in one analysis, rejected in another), stale pages, and orphan claims without source links.

/analysis-wiki update       # Scan archives → build/update all wiki pages
/analysis-wiki check        # Find contradictions, stale content, gaps
/analysis-wiki show dau     # Display the DAU knowledge page

How it's different from other features:

DR + Wiki together: DR answers "How did we decide to measure this?" Wiki answers "What have we learned from measuring it?"

Getting started:

1. Run /analysis-init — creates analyses/decisions/ and analyses/wiki/ with seeded INDEX files
2. Run a few analyses and archive them
3. Run /analysis-dr scan — AI scans archived analyses and proposes methodology decisions to record
4. Run /analysis-wiki update after 3+ archives — AI compiles metric/pattern/hypothesis pages
5. Run /analysis-wiki check periodically to catch contradictions and stale knowledge

Note on Quick analyses: Wiki pages are primarily built from Full analyses (5-stage files). Quick analyses (single-file) contribute less to the wiki since they don't have separate stage files.

Team Dashboard

Visualize your entire analysis history as an interactive node graph.

What the graph shows:

• Each node = one analysis
• Node size = ALIVE stage progress (small = just started, large = complete)
• Node color = analysis type (Investigation / Experiment / Simulation / Learn)
• Arc ring = which stages are done
• Dashed edges = follow-up connections between analyses
• Solid edges = analyses sharing the same tags
• Click a node → connected analyses stay highlighted, everything else fades

Filters: analyst, tags, type, status, date range. ⌘K to search.

Setup:

# Export your analyses to JSON
bash dashboard/export.sh > export.json

# Open in any browser — no server needed
open dashboard/alive-dashboard.html
# Click Load → paste the JSON

Add metadata per analysis to enrich the graph:

# analyses/active/F-2026-0303-001_checkout-drop/meta.yml
analyst: geun
tags: [checkout, conversion]
followups: [F-2026-0305-001]
keyFinding: "2.4pp drop confirmed. Mobile UX root cause."

MCP Server — Let Claude Query Your Analyses

Install the MCP server and Claude can access your full analysis history directly — in any MCP-compatible client.

npm install -g alive-analysis-mcp

Claude Desktop (~/Library/Application\ Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "alive-analysis": {
      "command": "alive-analysis-mcp",
      "args": ["--analyses-dir", "/path/to/your/analyses"]
    }
  }
}

Claude Code (.claude/mcp.json in your project):

{
  "alive-analysis": {
    "command": "alive-analysis-mcp",
    "env": { "ALIVE_ANALYSES_DIR": "./analyses" }
  }
}

What Claude can do with MCP connected

With MCP active, Claude remembers your team's analysis history across sessions. New team members can ask "What did we learn about checkout drop?" and get a full briefing — without anyone digging through files.

MCP Registry: io.github.with-geun/alive-analysis Works with Claude Desktop, Claude Code, Cursor, Zed, Windsurf, and any other MCP-compatible client.

Education Mode — Learn Product Analysis

Seven real-world scenarios with guided feedback. Designed to build analytical thinking, not just teach tool mechanics.

Beginner scenarios (20–30 min, Quick format)

Intermediate scenarios (45–60 min, Full format)

How feedback works

At each stage, Claude evaluates your work against a rubric and gives you specific feedback — not generic praise. Stuck? Three progressive hint levels: direction → specific → near-answer. Made a common mistake? It gets flagged with an explanation of why it matters.

Graduation path: two Beginner scenarios at 70%+ → unlock Intermediate → 75%+ on Intermediate → production-ready.

/analysis-learn              # Pick a scenario
/analysis-learn-hint         # Get a hint without giving away the answer
/analysis-learn-review       # See your score and skill radar

Situational Protocols

Built into the workflow for situations that derail most analyses:

Scope creep guard — When a second question appears inside an analysis, the agent detects it and offers three options: park it as a follow-up, swap the primary question, or explicitly expand scope with documented trade-offs.

Rabbit hole guard — After three rounds on a sub-question, checks whether it's still actionable. If not, surfaces a decision point.

Data quality emergency — Five response options: patch with available data, scope down, pause until data is ready, report with explicit caveats, or reframe the question entirely.

Analysis independence — Built-in safeguards against pressure to reach predetermined conclusions. If the prompt pattern looks like conclusion-first reasoning, it gets flagged.

Obsidian Integration

Your analyses/ folder works as an Obsidian vault out of the box.

Use [[F-2026-0305-001]] wiki-links in your markdown — Obsidian's graph view picks them up and draws the same connections the team dashboard shows. Useful for teams that prefer Obsidian for knowledge management alongside the code workflow.

File Structure

your-project/
├── analyses/
│   ├── active/
│   │   ├── F-2026-0303-001_checkout-drop/    # Full analysis
│   │   │   ├── 01_ask.md
│   │   │   ├── 02_look.md
│   │   │   ├── 03_investigate.md
│   │   │   ├── 04_voice.md
│   │   │   ├── 05_evolve.md
│   │   │   ├── meta.yml
│   │   │   └── assets/
│   │   │       └── queries/
│   │   └── quick_Q-2026-0308-001_dau-check.md  # Quick analysis
│   ├── archive/                               # Completed analyses
│   ├── decisions/                             # Analysis Decision Records
│   │   ├── INDEX.md                           # DR index (auto-updated)
│   │   └── DR-NNN.md                          # Individual decision files
│   └── wiki/                                  # AI-maintained knowledge base
│       ├── INDEX.md
│       ├── metrics/                           # One page per metric
│       ├── patterns/                          # Recurring analytical patterns
│       └── hypotheses/                        # Cross-analysis hypothesis results
├── .analysis/
│   ├── config.md          # Team settings (language, data stack, metrics)
│   ├── agents.yml         # Enable/disable individual agents
│   ├── checklists/        # Stage checklists — edit to customize
│   ├── status.md          # Current analysis state
│   ├── agent-state.md     # Agent suppression history
│   ├── models/            # ML model registry
│   ├── metrics/           # Metric definitions and monitors
│   └── decisions/         # Per-analysis business decision memos (VOICE stage output, not DR records)

Analysis IDs by type:

• F-YYYY-MMDD-NNN — Investigation or Modeling (Full)
• Q-YYYY-MMDD-NNN — Quick check
• E-YYYY-MMDD-NNN — Experiment / A/B test
• S-YYYY-MMDD-NNN — Simulation
• L-YYYY-MMDD-NNN — Learn scenario

Platform Support

Cursor uses a batch interaction model — all required inputs presented at once rather than sequentially, optimized for Cursor's agent loop behavior.

What it's not

Not a BI tool. The team dashboard visualizes your analysis history, not your business metrics. alive-analysis structures your thinking, not your reporting.

Not a data pipeline. It doesn't connect to databases or run queries automatically. It helps you think through what queries to run and why.

Not opinionated about your data stack. Works with any combination of SQL, Python, R, notebooks, or spreadsheets. The methodology is tool-agnostic.

Changelog highlights

Full changelog: CHANGELOG.md

Contributing

Issues and PRs welcome. See CONTRIBUTING.md.

License

MIT — with-geun