/workflows-compound

name: workflows:compound
description: Document a recently solved research problem to compound methodological knowledge
argument-hint: "[optional: brief context about the fix or problem solved]"
allowed-tools: Read, Write, Edit, Glob

/compound

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

Coordinate multiple subagents working in parallel to document a recently solved research problem. Creates structured documentation in `docs/solutions/` with YAML frontmatter for searchability and future reference.

Purpose

Captures problem solutions while context is fresh. Uses parallel subagents for maximum efficiency — Phase 1 gathers information, Phase 2 assembles the final document.

**Why "compound"?** Each documented solution compounds your methodological knowledge. The first time you solve a convergence problem takes hours of research. Document it, and the next occurrence takes minutes. Knowledge compounds.

Usage

/workflows:compound                          # Document the most recent fix
/workflows:compound convergence failure in BLP inner loop  # Provide context
/workflows:compound fixed cluster-robust SEs  # Brief description

Execution Strategy: Two-Phase Orchestration

<critical_requirement> **Only ONE file gets written — the final documentation.**

Phase 1 subagents return TEXT DATA to the orchestrator. They must NOT use Write, Edit, or create any files. Only the orchestrator (Phase 2) writes the final documentation file. </critical_requirement>

Phase 1: Parallel Research

<parallel_tasks>

Launch these subagents IN PARALLEL. Each returns text data to the orchestrator.

1. **Context Analyzer**

• Extracts conversation history for the problem-solving session
• Identifies problem type, estimation method, symptoms, error messages
• Auto-categorizes the problem (see Category Classification below)
• Returns: YAML frontmatter skeleton with problem metadata

2. **Solution Extractor**

• Analyzes all investigation steps taken during the session
• Identifies root cause (e.g., "ill-conditioned Hessian due to poor starting values")
• Extracts working solution with code examples
• Documents what didn't work and why (important for future reference)
• Returns: Solution content block with code snippets

3. **Related Docs Finder**

• Searches `docs/solutions/` for related documentation
• Identifies cross-references and links to similar problems
• Checks if this problem is a variant of a previously documented issue
• Returns: Links, relationships, and duplicate-avoidance notes

4. **Prevention Strategist**

• Develops prevention strategies specific to the problem type
• Creates diagnostic checklist ("check these things first next time")
• Suggests robustness checks or tests that would catch this early
• Returns: Prevention/diagnostic content

5. **Category Classifier**

• Auto-detects the appropriate `docs/solutions/` category from problem description and session content
• Validates category against the schema below
• Generates filename slug from problem description
• Returns: Final path and filename

</parallel_tasks>

Category Classification

Problems are auto-classified into one or more categories using keyword matching on the problem description and session content:

| Category | Directory | Keywords / Signals | |----------|-----------|-------------------| | **Estimation Issues** | `estimation-issues/` | convergence, bias, efficiency, standard errors, MLE, GMM, likelihood, optimizer, starting values, boundary, gradient, Hessian | | **Data Issues** | `data-issues/` | missing data, measurement error, sample selection, merge, duplicates, outliers, panel structure, encoding, cleaning | | **Numerical Issues** | `numerical-issues/` | floating-point, overflow, underflow, condition number, tolerance, ill-conditioning, precision, NaN, Inf, singular matrix | | **Methodology Issues** | `methodology-issues/` | identification, model specification, assumption violations, endogeneity, exclusion restriction, functional form, overidentification | | **Derivation Issues** | `derivation-issues/` | proof, theorem, lemma, asymptotic, regularity conditions, existence, uniqueness, fixed point, convergence rate | | **Replication Issues** | `replication-issues/` | reproducibility, package versions, seeds, environment, Docker, conda, renv, pipeline, Makefile, DVC |

**Multi-category problems:** A problem can belong to multiple categories (e.g., "BLP convergence failure" is both `estimation-issues/` and `numerical-issues/`). Use the primary category for the file location and cross-reference the secondary category in the frontmatter `tags` field.

**Ambiguous problems:** If keyword matching is inconclusive, default to `methodology-issues/` (the broadest category).

Phase 2: Assembly & Write

<sequential_tasks>

**WAIT for all Phase 1 subagents to complete before proceeding.**

The orchestrating agent performs these steps:

1. **Collect** all text results from Phase 1 subagents 2. **Assemble** complete markdown file using the template below 3. **Validate** YAML frontmatter fields are complete 4. **Create** directory if needed: `mkdir -p docs/solutions/[category]/` 5. **Write** the SINGLE final file: `docs/solutions/[category]/[filename].md`

Documentation Template

---
title: "[Problem title — concise, searchable]"
date: YYYY-MM-DD
category: [primary category]
tags: [estimation, convergence, BLP, ...]
estimation_method: [if applicable: MLE, GMM, IV, DiD, ...]
language: [Python, R, Julia, Stata]
severity: [critical, moderate, minor]
time_to_resolve: [approximate time spent]
---

# [Problem Title]

## Problem

**Symptom:** [What was observed — error messages, wrong results, failure to converge]

**Context:** [What estimation/analysis was being performed, what data, what method]

**Reproduction:** [Minimal steps to reproduce the problem]