analysis-design

/analysis-design — Analysis Design Builder

Guides Claude through creating a lightweight analysis design document using insight-blueprint MCP tools. Follows the hypothesis-driven EDA workflow.

When to Use

• Starting a new exploratory analysis (user wants to formalize a hypothesis)
• Deriving a sub-hypothesis after a parent hypothesis is rejected
• Reviewing or listing existing analysis designs

When NOT to Use

• Browsing the data catalog (future: /data-explorer skill)
• General EDA discussion without intent to persist a design document

Workflow

Step 0: User Confirmation Gate

Before proceeding, confirm with the user:

• Ask: "分析設計を新規作成しますか？"
• If the user declines, exit gracefully with a brief message and do not proceed
• If the user confirms, continue to Step 1

Step 1: Check Current State

Call list_analysis_designs() to understand existing designs:

• Note existing theme IDs (e.g., "FP", "TX")
• Check if a parent_id should be referenced

Step 1.5: Check for Framing Brief

Check the conversation context for a ## Framing Brief from analysis-framing.

Detection rules (all must be satisfied):

1. ## Framing Brief heading exists in conversation
2. ### テーマ subsection exists under Framing Brief
3. ### 推奨方向 subsection exists under Framing Brief
4. theme_id: field exists within the 推奨方向 section
5. If multiple Framing Briefs exist, use the last (most recent) one

If valid Framing Brief found:

Map Brief sections to analysis-design fields as draft values:

Framing Brief セクション	analysis-design フィールド	マッピング
テーマ	title	テーマの1行要約を title の候補として提示
利用可能データ	explanatory, metrics	データソース・カラムから explanatory/metrics の候補を生成
既存分析	parent_id	関連デザイン ID を parent_id の候補として提示
ギャップ	hypothesis_background	ギャップ情報を仮説の背景・動機の下書きに活用
推奨方向.仮説の方向性	title, hypothesis_background	方向性から title 候補を生成し、背景の下書きに活用
推奨方向.theme_id	theme_id	デフォルト値として設定
推奨方向.parent_id	parent_id	デフォルト値として設定
推奨方向.analysis_intent	analysis_intent	デフォルト値として設定
推奨方向.推奨手法	methodology	{method: "推奨手法の値", reason: "Framing Brief の推奨"} としてデフォルト設定

Present draft values to user: "Framing Brief の内容でよいか、修正したい点があるか"

Step 2 ではゼロからインタビューせず、draft 値を提示して確認しながら進める。

If Framing Brief missing or incomplete: Framing Brief がない、または検出条件を満たさない場合は何もしない。Step 2 の通常インタビューフローに進む（後方互換）。不完全な場合はユーザーに通知: "Framing Brief が不完全なため通常フローで進めます"

Step 2: Gather Hypothesis Details

Interview the user for required fields:

Field	Required	Description	Example
title	Yes	Short descriptive title	"Foreign population vs crime rate"
hypothesis_statement	Yes	Testable statement	"No positive correlation exists between..."
hypothesis_background	Yes	Context and motivation (free-form, multi-line)	Background reasoning
theme_id	No	Uppercase identifier — defaults to "DEFAULT"	"FP", "TX", "ECON"
parent_id	No	Parent design ID if this is derived	"FP-H01"
analysis_intent	No	"exploratory", "confirmatory" (default), or "mixed"	"exploratory"
metrics	No	List of verification metric dicts (tier: "primary" / "secondary" / "guardrail")	[{target: "crime_rate_per_100k", tier: "primary", data_source: {crime: "0000010111"}, grouping: [...], filter: "...", aggregation: "mean", comparison: "..."}]
explanatory	No	List of explanatory variable dicts (role: "treatment" / "confounder" / "covariate" / "instrumental" / "mediator")	[{name: "foreign_ratio", description: "外国人比率", role: "treatment", data_source: "0000010101", time_points: "2012-2022"}]
chart	No	List of visualization definition dicts (intent: "distribution" / "correlation" / "trend" / "comparison")	[{intent: "correlation", type: "scatter", description: "FP ratio vs crime rate", x: "foreign_ratio", y: "crime_rate"}]
methodology	Yes	Analysis method and package (must include method key)	{method: "OLS", package: "statsmodels", reason: "線形回帰で相関を検証"}
next_action	No	Branch definition after hypothesis test	{if_supported: "...", if_rejected: {reason: "...", pivot: "..."}}

If the user passed $ARGUMENTS, use it as theme_id (validate format first).

Step 2.5: Pre-creation Check

Before calling create_analysis_design, verify that methodology is NOT null. If the interview did not cover methodology, ask now:

• "What analysis method will you use? (e.g., OLS, t-test, chi-square, DID)"
• Set methodology = {method: "<answer>", reason: "<why this method>"} at minimum.

Step 2.6: Enrich Methodology with Code Patterns

The batch-analysis LLM (sonnet) generates notebooks from methodology content. Concrete code patterns dramatically improve generation fidelity.

When data_source references a registered catalog source, auto-generate a code pattern from the catalog schema and include it in methodology.steps:

methodology = {
    "method": "OLS",
    "package": "statsmodels",
    "reason": "線形回帰で相関を検証",
    "steps": [
        {
            "description": "from lib.accessor.bigquery import BigQueryAccessor\nacc = BigQueryAccessor(project_id='lmi-datau-prod')\nraw_df = acc.query_to_dataframe('''\n  SELECT col1, col2, ...\n  FROM `project.dataset.table`\n  WHERE ...\n''')"
        }
    ]
}

Rules:

• If data_source is a BQ table: generate BigQueryAccessor pattern with actual table name, key columns from schema, and filter conditions
• If methodology uses a specific library (e.g., lingam, shap, dowhy): include the exact API call with parameter names in a subsequent step
• If the user provides their own code pattern, use it as-is — do not overwrite

Step 3: Create the Design

create_analysis_design(
    title="<title>",
    hypothesis_statement="<statement>",
    hypothesis_background="<background>",
    methodology=<dict>,                  # REQUIRED: {method, package?, reason?}
    theme_id="<theme_id or DEFAULT>",
    parent_id=<"FP-H01" or None>,
    metrics=<list[dict] or None>,        # each dict: {target, tier?, data_source?, grouping?, filter?, aggregation?, comparison?}
    explanatory=<list[dict] or None>,    # each dict: {name, description?, role?, data_source?, time_points?}
    chart=<list[dict] or None>,          # each dict: {intent, type?, description?, x?, y?}
    next_action=<dict or None>,
)

Expected success response:

{"id": "FP-H01", "title": "...", "status": "in_review", "message": "Analysis design 'FP-H01' created successfully."}

Step 3b: Update an Existing Design (optional)

To add or modify fields on an already-created design, use update_analysis_design():

update_analysis_design(
    design_id="FP-H01",
    next_action={"if_supported": "パネルFEへ進む", "if_rejected": {"reason": "相関なし", "pivot": "時系列分析"}},
)

Only provided fields are updated; all others remain unchanged.

Step 4: Confirm and Suggest Next Steps

• Show the returned id (e.g., "FP-H01") to the user
• Confirm the YAML file location: .insight/designs/FP-H01_hypothesis.yaml
• Suggest next steps:
  • Refine the hypothesis: add chart / next_action via update_analysis_design()
  • Start recording reasoning: /analysis-journal FP-H01
  • Review and conclude: /analysis-reflection FP-H01

MCP Tool Reference

Tool	Purpose	Key Parameters
list_analysis_designs(status?)	List existing designs	status: in_review | revision_requested | analyzing | supported | rejected | inconclusive
create_analysis_design(...)	Create new design	title, hypothesis_statement, hypothesis_background, methodology, theme_id?, parent_id?, metrics?, explanatory?, chart?, next_action?, analysis_intent?
update_analysis_design(...)	Partially update existing design	design_id, title?, hypothesis_statement?, hypothesis_background?, metrics?, explanatory?, chart?, methodology?, next_action?, analysis_intent?
get_analysis_design(design_id)	Retrieve a specific design	design_id: str (e.g., "FP-H01")

Typed Field Values Reference

Field	Type	Valid Values	Default
explanatory[].role	VariableRole	"treatment", "confounder", "covariate", "instrumental", "mediator"	"covariate"
metrics[].tier	MetricTier	"primary", "secondary", "guardrail"	"primary"
chart[].intent	ChartIntent	"distribution", "correlation", "trend", "comparison"	inferred from type
methodology.method	str	free text (required, non-empty)	—
methodology.package	str	free text (optional)	""
methodology.reason	str	free text (optional)	""
methodology.steps	list[dict]	Each dict has description (str). Include concrete code patterns for batch LLM fidelity.	[]

Backward compatibility: role, tier, intent fields are optional in input. If omitted, defaults are applied automatically.

theme_id Rules

• Must match [A-Z][A-Z0-9]* (uppercase letter first, then uppercase letters or digits)
• Valid: "FP", "TX", "ECON", "DEFAULT", "FP2"
• Invalid: "fp" (lowercase), "FP/X" (slash), "1FP" (starts with digit)
• On invalid input, the MCP tool returns an error dict — ask the user to correct it

Error Handling

Error Response	Cause	Action
{"error": "Invalid theme_id 'fp': must match [A-Z][A-Z0-9]*"}	Invalid theme_id format	Ask user for a valid uppercase theme_id
{"error": "Design 'FP-H99' not found"}	Non-existent design_id	Confirm ID via list_analysis_designs()

Chaining

From	To	When
/analysis-framing	→ /analysis-design	Framing Brief 付きでフォワーディング
/analysis-design	→ /analysis-journal	デザイン作成後: "推論過程を記録するなら /analysis-journal {id}"
/analysis-design	→ /analysis-framing	データ不足で仮説の方向を再検討: "データを探し直すなら /analysis-framing"
/catalog-register	→ /analysis-design	データ登録完了後にデザイン作成を続行
/analysis-reflection	→ /analysis-design	派生仮説が明確な場合
/analysis-revision	→ /analysis-design	レビュー修正で大きな方針変更が必要な場合

Language Rules

• Follow project CLAUDE.md language settings. Default to Japanese if no setting.
• Code, IDs, tool names, and YAML fields always stay in English.
• Hypothesis text follows the user's language (usually Japanese)

Workflow Rules

Hypothesis Design Workflow

Status Flow

Designs follow a strict status progression:

draft → active → pending_review → supported | rejected | inconclusive

• draft: Initial creation. Editable freely.
• active: Hypothesis is being tested. Data collection in progress.
• pending_review: Analysis complete, awaiting peer review.
• supported / rejected / inconclusive: Final disposition after review.

Status transitions MUST use design_update MCP tool with valid status field. Skipping states (e.g., draft → supported) is not allowed.

Theme ID Rules

• Every design MUST have a theme_id linking it to a research theme.
• Theme IDs must match [A-Z][A-Z0-9]* (e.g., CHURN, PRICING).
• Use /analysis-design skill to create designs with proper theme association.

Derived Hypotheses

• A design may reference parent_id to indicate it derives from another hypothesis.
• Parent must exist and be in supported or active status.
• This creates a hypothesis tree for tracking research lineage.

YAML Format Reference

.insight/ YAML File Operation Rules

MCP-Only Editing

All catalog and design YAML files under .insight/ MUST be edited through insight-blueprint MCP tools. Direct file writes are prohibited to maintain schema integrity and event consistency.

Allowed MCP tools for editing:

• catalog_add_source / catalog_update_source — catalog/sources/*.yaml
• design_create / design_update — designs/*.yaml
• knowledge_store / knowledge_update — catalog/knowledge/*.yaml
• review_add_comment / review_submit_batch — designs/*.yaml (review data)

Direct read is always OK — use Read tool or cat freely for analysis.

Exceptions (Direct Edit Allowed)

These files may be edited directly because they contain user-managed configuration, not MCP-managed data:

• .insight/config.yaml — project configuration
• .insight/rules/review_rules.yaml — review rule definitions
• .insight/rules/analysis_rules.yaml — analysis rule definitions
• .insight/rules/extracted_knowledge.yaml — knowledge seed data
• .insight/designs/*_journal.yaml — Insight Journal (managed by analysis-journal skill)
• .insight/designs/*_revision.yaml — Revision Tracking (managed by analysis-revision skill)