workflows:plan

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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:

```bash
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

From James-Traina/compound-science, MIT.