insight-blueprint

insight-blueprint

A Claude Code skills plugin for hypothesis-driven EDA. Analysis designs, journals, reviews, and the data catalog live as YAML under .insight/; skills read and write them directly. Integrity is enforced by an embedded validation library (validate.py) plus a pre-write hook — no server, no daemon, no SQLite. See docs/ARCHITECTURE.md and docs/PRD.md.

Quickstart

Prerequisites: Claude Code, uv, and Python 3.11+. The skills shell out to uv run …, which resolves the Python dependencies automatically — there is nothing to pip install.

1. Install the plugin. In Claude Code, register this repo as a marketplace and install:

   /plugin marketplace add etoyama/insight-blueprint-skills
   /plugin install insight-blueprint@insight-blueprint-marketplace
   

2. Open your analysis project in Claude Code and take the first step:

   /analysis-framing        # explore your data & frame a direction
   /analysis-design         # turn it into a hypothesis design document
   /analysis-journal        # record reasoning as you investigate
   /analysis-reflection     # conclude (or branch) the hypothesis
   /analysis-report         # write up a distributable APA-style report
   /knowledge-extract       # save reusable, source-scoped knowledge
   

There is nothing to launch — skills read and write YAML under .insight/ in your project (created on first use). Writes to design documents are validated automatically by a pre-write hook.

Installation

Claude Code plugin (recommended)

In Claude Code, add this repository as a plugin marketplace and install from it:

/plugin marketplace add etoyama/insight-blueprint-skills
/plugin install insight-blueprint@insight-blueprint-marketplace

Here insight-blueprint is the plugin name and insight-blueprint-marketplace is the marketplace defined in .claude-plugin/marketplace.json.

Local clone (for development)

git clone https://github.com/etoyama/insight-blueprint-skills.git
claude --plugin-dir ./insight-blueprint-skills

--plugin-dir loads the plugin for the current session only. Add a shell alias to make it stick:

alias claude-ib='claude --plugin-dir /path/to/insight-blueprint-skills'

Optional: Python package (only for hand-written lineage)

You do not need to install anything for the skills to work. The plugin is self-contained: its bundled uv environment provides insight_blueprint (models, validation, lineage) and /analysis-notebook runs marimo/pandas through that same environment (--extra notebook). See ADR-0006.

Install the insight-blueprint-lineage package only if you want to import tracked_pipe directly in your own notebooks/scripts (i.e. lineage tracking outside /analysis-notebook). The import name stays insight_blueprint:

uv add insight-blueprint-lineage

See CHANGELOG.md for release notes.

How it works

• Skills (skills/) drive the workflow and read/write .insight/ YAML via small server-free helpers (skills/_shared/design_io.py, catalog_io.py).
• Validation is centralized in src/insight_blueprint/validate.py (Pydantic schema + state-transition guard). A pre-write hook (hooks/validate-design.py, shipped with the plugin via hooks/hooks.json) calls the same library to block invalid writes to *_hypothesis.yaml.
• Lineage (src/insight_blueprint/lineage/) records DataFrame transformations and exports Mermaid diagrams.

Skills