---

name: workflows:plan description: Transform research descriptions into well-structured implementation plans following project conventions argument-hint: "<research task, estimation problem, or methodological improvement>" allowed-tools: Read, Glob, Bash

Create an Implementation Plan for a Research Task

Pipeline mode: This command operates fully autonomously. All decisions are made automatically.

Introduction

Transform research descriptions, estimation problems, or methodological improvements into well-structured plan files that follow project conventions and best practices. This command auto-selects the appropriate detail level based on task complexity.

Research Description

<feature_description> #$ARGUMENTS </feature_description>

If the research description above is empty: Infer the task from recent context — open plan files, recent brainstorms in docs/brainstorms/, or the current estimation code. If no context is available, state "No research task provided" and stop.

0. Idea Refinement

Check for brainstorm output first:

Before analysis, look for recent brainstorm documents in docs/brainstorms/ that match this task:

ls -la docs/brainstorms/*.md 2>/dev/null | head -10

If docs/brainstorms/ does not exist, skip brainstorm lookup and proceed with task analysis.

Relevance criteria: A brainstorm is relevant if:

• The topic (from filename or YAML frontmatter) semantically matches the research description
• Created within the last 14 days
• If multiple candidates match, use the most recent one

If a relevant brainstorm exists:

1. Read the brainstorm document thoroughly — every section matters
2. Announce: "Found brainstorm from [date]: [topic]. Using as foundation for planning."
3. Extract and carry forward ALL of the following into the plan:
   • Key decisions and their rationale
   • Chosen approach and why alternatives were rejected
   • Constraints and requirements discovered during brainstorming
   • Open questions (flag these for resolution during implementation)
   • Success criteria and scope boundaries
   • Any specific methodological choices or estimator selections
4. Skip the idea refinement analysis below — the brainstorm already answered WHAT to do
5. Use brainstorm content as the primary input to research and planning phases
6. Throughout the plan, reference specific decisions with (see brainstorm: docs/brainstorms/<filename>) when carrying forward conclusions
7. Do not omit brainstorm content — if the brainstorm discussed it, the plan must address it

If no brainstorm found (or not relevant), analyze the task:

Decompose the research description to understand scope:

• What is being asked? New estimator, bug fix, robustness check, data work, pipeline change?
• What is the identification strategy? If estimation work, what identifies the parameters?
• What dependencies exist? Data availability, computational resources, prior estimation steps?
• What is the risk level? Simple change vs architectural shift vs novel methodology?

Main Tasks

1. Local Research (Always Runs — Parallel)

Run these agents in parallel to gather local context:

• Task methods-explorer(research_description)
• Search docs/solutions/ for documented solutions that might apply (convergence fixes, data issues, specification errors)

What to look for:

• Methods research: existing estimation patterns, methodology used in this project, relevant packages and implementations
• Learnings: documented solutions in docs/solutions/ that might apply (see workflows-compound/references/solution-schema.md for search workflow)

These findings inform the next step.

1.5. Research Decision

Based on task analysis and local findings, decide on extended research.

Novel methodology → always research. New identification strategies, unfamiliar estimators, methods without established implementations. The cost of missing relevant literature is too high.

Strong local context → skip extended research. Project has established patterns for this type of work, prior brainstorm covers the approach, straightforward extension of existing code.

Uncertainty or unfamiliar territory → research. Unfamiliar econometric method, no existing examples in codebase, potential identification concerns.

Announce the decision and proceed. Brief explanation, then continue.

Examples:

• "Project has established DiD patterns for this. Proceeding without extended research."
• "This involves a new identification strategy. Researching current best practices and recent Monte Carlo evidence."

1.5b. Extended Research (Conditional)

Only run if Step 1.5 indicates extended research is valuable.

Run these agents in parallel:

• Task literature-scout(research_description)

1.6. Consolidate Research

After all research steps complete, consolidate findings:

• Document relevant file paths from codebase research (e.g., src/estimation/blp_demand.py:42)
• Include relevant methodological learnings from docs/solutions/ (convergence fixes, specification patterns)
• Note software packages, estimator properties, and Monte Carlo evidence (if extended research was done)
• List related estimation code or prior implementations discovered
• Capture CLAUDE.md conventions and project-specific patterns

2. Plan Structure & Categorization

Title & Categorization:

• Draft clear, searchable title using conventional format (e.g., feat: Add Callaway-Sant'Anna staggered DiD estimator, fix: BLP inner-loop convergence failure)
• Determine type: feat (new estimator/method), fix (bug/convergence issue), refactor (code improvement)
• Convert title to filename: add today's date prefix, strip prefix colon, kebab-case, add -plan suffix
  • Example: feat: Add Staggered DiD Estimator → 2026-02-26-feat-add-staggered-did-estimator-plan.md

3. Specification Flow Analysis

After planning the structure, validate the research specification by checking the chain from model → estimator → code. Verify that model assumptions imply estimator requirements, objective function and moments match the methodology, and diagnostic tests exist for each testable identification assumption. If gaps are found, incorporate them as plan items.

4. Auto-Select Implementation Detail Level

Auto-detect based on task characteristics:

| Signal | Level | Examples | |--------|-------|---------| | Bug fix, simple data cleaning, minor parameter change | MINIMAL | Fix standard error clustering, correct variable coding, update sample restriction | | New estimator, additional robustness check, new data source | MORE | Add Callaway-Sant'Anna estimator, implement placebo tests, merge new dataset | | New identification strategy, structural model change, pipeline overhaul | A LOT | Switch from reduced-form to structural estimation, redesign DGP, build replication package |

If signals are mixed, default to MORE — it covers most research tasks well.

---

MINIMAL (Quick Plan)

Best for: Simple bug fixes, parameter changes, minor data corrections

---
title: [Plan Title]
type: [feat|fix|refactor]
status: active
date: YYYY-MM-DD
origin: docs/brainstorms/YYYY-MM-DD-<topic>-brainstorm.md  # if originated from brainstorm
---

# [Plan Title]

[Brief problem/task description]

## Acceptance Criteria

- [ ] Core requirement 1
- [ ] Core requirement 2

## Context

[Critical information: data source, estimation method, relevant code paths]

## Implementation

### [filename.py]

```python
# Key implementation sketch

Sources

• Origin brainstorm: [path] — include if plan originated from a brainstorm
• Related code: [file_path:line_number]

---

#### MORE (Standard Plan)

**Best for:** Most research tasks — new estimators, robustness checks, data work

```markdown
---
title: [Plan Title]
type: [feat|fix|refactor]
status: active
date: YYYY-MM-DD
origin: docs/brainstorms/YYYY-MM-DD-<topic>-brainstorm.md  # if originated from brainstorm
---

# [Plan Title]

## Overview

[Comprehensive description of the research task]

## Problem Statement / Motivation

[Why this matters — what research question does this advance?]

## Proposed Approach

[High-level methodological approach]

## Technical Considerations

- Estimation method and its properties
- Computational requirements and convergence expectations
- Data structure and variable construction

## Research Impact Assessment

- **Identification Impact**: What assumptions does this change affect? Are exclusion restrictions, rank conditions, or support conditions modified?
- **Estimation Impact**: How does this affect computational cost, convergence properties, or asymptotic efficiency?
- **Robustness Impact**: Which robustness checks need updating? New placebo tests, alternative specifications, or sensitivity analyses?
- **Replication Impact**: What changes to the replication package? New dependencies, data files, or computational steps?

## Acceptance Criteria

- [ ] Estimation converges with sensible parameter values
- [ ] Standard errors computed correctly (appropriate clustering/robustness)
- [ ] Diagnostic tests pass (first-stage F, overidentification, specification tests)
- [ ] Results are robust to reasonable alternative specifications
- [ ] Code is documented and reproducible

## Dependencies & Risks

[What could block or complicate this — data availability, computational cost, identification concerns]

## Sources & References

- **Origin brainstorm:** [path] — include if plan originated from a brainstorm
- Methodological reference: [paper/package]
- Similar code in project: [file_path:line_number]

---

A LOT (Comprehensive Plan)

Best for: Major methodological changes, new identification strategies, structural model development

---
title: [Plan Title]
type: [feat|fix|refactor]
status: active
date: YYYY-MM-DD
origin: docs/brainstorms/YYYY-MM-DD-<topic>-brainstorm.md  # if originated from brainstorm
---

# [Plan Title]

## Overview

[Executive summary of the research task and its significance]

## Problem Statement

[Detailed problem analysis — what gap in the literature or project does this fill?]

## Proposed Approach

[Comprehensive methodological approach with theoretical motivation]

## Technical Approach

### Identification Strategy

[Formal identification argument — target parameter, assumptions, identification result]

### Estimation Method

[Estimator choice, properties, computational approach]

### Implementation Phases

#### Phase 1: [Foundation]

- Tasks and deliverables
- Success criteria (convergence, diagnostics)
- Key files to create/modify

#### Phase 2: [Core Estimation]

- Tasks and deliverables
- Success criteria
- Key files to create/modify

#### Phase 3: [Robustness & Documentation]

- Robustness checks and sensitivity analyses
- Documentation and replication materials
- Success criteria

## Alternative Approaches Considered

[Other methods evaluated and why rejected — reference brainstorm if applicable]

## Research Impact Assessment

### Identification Impact

[Detailed analysis: What assumptions does this change affect? How testable are they? What happens if they fail?]

### Estimation Impact

[Detailed analysis: Computational cost, convergence properties, efficiency gains/losses, finite-sample behavior]

### Robustness Impact

[Detailed analysis: Which specification tests apply? Placebo tests, alternative instruments, subsample analysis, sensitivity to functional form]

### Replication Impact

[Detailed analysis: New dependencies, data requirements, computational environment changes, pipeline modifications]

## Acceptance Criteria

### Estimation Requirements

- [ ] Point estimates are economically sensible (sign, magnitude, significance)
- [ ] Standard errors use appropriate inference (clustering, bootstrap, analytical)
- [ ] Convergence achieved with tolerance < [threshold]
- [ ] Multiple sta