/workflows-plan

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 researc