flonat-research 0.1.0

package/skills/multi-perspective/SKILL.md

@@ -0,0 +1,311 @@
+---
+name: multi-perspective
+description: "Use when you need to explore a research question from multiple independent perspectives."
+allowed-tools: Read, Write, Edit, Glob, Grep, Task, AskUserQuestion
+argument-hint: "[research question, hypothesis, or design choice]"
+---
+
+# Multi-Perspective Exploration
+
+Spawn 3-5 parallel agents, each with a distinct disciplinary lens and epistemic prior, to independently investigate a research question. Then synthesise their findings into a structured comparison that surfaces agreements, tensions, and blind spots.
+
+The core insight: a single-perspective analysis inherits the biases of that perspective. Deliberately introducing cognitive diversity — grounded in real disciplinary traditions — produces more robust research designs.
+
+## When to Use
+
+- Early-stage research design: "Is this the right question? Is this the right method?"
+- When choosing between competing identification strategies
+- When a paper needs to convince reviewers from different traditions
+- Before committing to a theoretical framework
+- When you suspect your approach has blind spots
+
+## When NOT to Use
+
+- **Quick feedback** — use `/devils-advocate` (single-perspective adversarial)
+- **Literature search** — use `/literature` (discovery, not deliberation)
+- **Generating new questions** — use `/scout generate` (this skill evaluates, not generates)
+- **Paper proofreading** — use `/proofread` or `paper-critic` agent
+
+## Workflow
+
+### Phase 1: Frame the Question
+
+Read `$ARGUMENTS` and any referenced files. Formulate a clear, debatable research question or design choice. Good inputs:
+
+- "Should I use DiD or synthetic control for this policy evaluation?"
+- "Is bounded rationality or information asymmetry the better theoretical lens for this phenomenon?"
+- "What are the threats to my identification strategy for [paper X]?"
+- "How would different disciplines approach [phenomenon Y]?"
+
+If the input is vague, ask one clarifying question before proceeding.
+
+### Phase 2: Generate Perspectives
+
+Generate 3-5 distinct perspectives. Each perspective is defined by:
+
+| Field | Description |
+|-------|-------------|
+| **Label** | Short name (e.g., "Behavioural Economist", "Organisational Theorist") |
+| **Discipline** | Academic field and tradition |
+| **Epistemic prior** | What this perspective takes as given, and what it questions |
+| **Methodological preference** | Preferred empirical approach and evidence standards |
+| **Likely concern** | What this perspective would worry about most |
+
+**Rules for perspective generation:**
+- At least one perspective must be **methodologically sceptical** (e.g., econometrician focused on identification)
+- At least one must come from a **different discipline** than the paper's primary field
+- At least one must prioritise **practical/policy relevance** over internal validity
+- Perspectives must **genuinely disagree** on at least one substantive point — no hollow diversity
+- Ground perspectives in real traditions, not caricatures
+
+**Perspective templates by domain:**
+
+| If the research is about... | Consider these lenses |
+|----------------------------|----------------------|
+| Human-AI collaboration | Cognitive psychologist, HCI researcher, organisational economist, ethicist, systems engineer |
+| MCDM / preference elicitation | Decision theorist, behavioural economist, operations researcher, UX researcher, philosopher of rationality |
+| Multi-agent systems | Game theorist, mechanism designer, complexity scientist, political economist, social choice theorist |
+| Organisational behaviour | Sociologist, micro-economist, evolutionary psychologist, management scientist, institutional theorist |
+| Environmental/carbon policy | Environmental economist, political scientist, energy engineer, regulatory lawyer, behavioural scientist |
+
+Present the generated perspectives to the user and get approval before proceeding. The user may want to add, remove, or adjust perspectives.
+
+### Phase 3: Parallel Investigation
+
+Spawn one sub-agent per perspective using the Task tool. Each agent receives:
+
+```
+You are a [LABEL] investigating this research question:
+
+[QUESTION]
+
+Your disciplinary background: [DISCIPLINE]
+Your epistemic prior: [EPISTEMIC PRIOR]
+Your methodological preference: [METHODOLOGICAL PREFERENCE]
+Your primary concern: [LIKELY CONCERN]
+
+Context about the project:
+[Relevant project context — CLAUDE.md summary, paper abstract if available]
+
+TASK: Analyse this question from your perspective. Address:
+1. How would you frame this question in your discipline?
+2. What theoretical framework would you apply?
+3. What empirical strategy would you recommend, and why?
+4. What are the main threats to validity from your perspective?
+5. What would you find most/least convincing in the current approach?
+6. What is the one thing the researcher is probably overlooking?
+
+Be specific and grounded. Cite real methodological traditions and papers where relevant.
+Write 300-500 words. Do not hedge — commit to your perspective's position.
+```
+
+**Agent configuration:**
+- Use `subagent_type: general-purpose` for each
+- Run all agents in parallel (up to 5 concurrent, per orchestration convention)
+- Each agent writes to a temp file; collect results after all complete
+
+### Phase 3.25: User Check-In (Interactive Mode)
+
+After collecting all perspective outputs, present them to the user as a structured summary and run an interactive check-in. This is the key differentiator from a passive multi-perspective analysis — the user participates as an active contributor, not a spectator.
+
+**What to present:**
+- Each perspective's key position (2-3 sentences, not the full output)
+- The main disagreements visible so far
+- Any assumptions the perspectives made about the research context
+
+**Then ask (via AskUserQuestion):**
+
+> "Here's where the perspectives stand so far. Before they peer-review each other, I want to check in:
+>
+> 1. **Reveal constraints:** Is there anything these perspectives don't know that would change their analysis? (e.g., data limitations, institutional constraints, supervisor preferences, timeline)
+> 2. **Redirect:** Is any perspective completely off-base or exploring an irrelevant direction?
+> 3. **Challenge:** Do you want to push back on any specific claim before cross-evaluation?"
+
+**How the user's input feeds forward:**
+- Constraints revealed here are injected into the cross-evaluation prompt as "Additional context from the researcher" — each evaluator sees them
+- If a perspective is marked as off-base, it is still included in cross-evaluation (for completeness) but flagged: "The researcher considers this direction less relevant because [reason]"
+- Challenges are posed directly to the relevant perspective in the cross-evaluation round as an additional evaluation criterion
+
+**When to skip:** If the user says "skip check-in", "just run it", or "non-interactive", proceed directly to Phase 3.5. The default is interactive.
+
+### Phase 3.5: Anonymised Cross-Evaluation
+
+Before synthesising, run a peer-review round where each perspective critiques all others — without knowing which lens produced which output. This forces content-based evaluation rather than tribal dismissal.
+
+**Setup:** Anonymise each perspective's output by replacing the label with a neutral identifier (Perspective A, B, C, ...). Strip any self-identifying language (e.g., "as an econometrician, I...").
+
+**Spawn one evaluator agent per perspective** using the Task tool. Each receives:
+
+```
+You are a [LABEL] ([DISCIPLINE]).
+
+Below are [N] anonymous analyses of this research question:
+
+[QUESTION]
+
+---
+[Perspective A output — anonymised]
+---
+[Perspective B output — anonymised]
+---
+[Perspective C output — anonymised]
+---
+
+TASK: Evaluate each perspective on these criteria (1-5 scale):
+1. **Rigour** — Is the reasoning sound? Are claims supported?
+2. **Relevance** — Does it address the core question?
+3. **Novelty** — Does it surface something the others miss?
+4. **Practicality** — Could the researcher act on this advice?
+
+[IF USER PROVIDED INPUT IN PHASE 3.25, ADD:]
+Additional context from the researcher:
+- Constraints: [user-revealed constraints]
+- Challenges: [user's pushback on specific claims]
+- Relevance notes: [any perspectives the user flagged as less relevant, with reason]
+
+Factor this researcher context into your evaluation — perspectives that ignore known constraints should score lower on Practicality.
+
+For each perspective, provide:
+- Scores (4 numbers)
+- One strength (1 sentence)
+- One weakness (1 sentence)
+- Would you change your own analysis based on this? (yes/no + why)
+
+Then rank all perspectives from most to least valuable for the researcher.
+Be honest — evaluate the content, not the style. 200-300 words total.
+```
+
+**Agent configuration:**
+- Use `subagent_type: general-purpose` for each
+- Run all evaluator agents in parallel
+- Each agent must NOT see which label produced which output
+
+**What this produces:**
+- A cross-evaluation matrix (each perspective rated by every other)
+- Self-revision signals (perspectives that update their view after seeing others)
+- Consensus rankings (which perspectives were rated highest across evaluators)
+
+Include the cross-evaluation matrix in the final report (Section "Peer Evaluation") so the user can see where perspectives found each other compelling or weak.
+
+### Phase 4: Synthesise
+
+Read all agent outputs **and their peer evaluations** and produce a structured synthesis. Weight the synthesis by peer evaluation scores — perspectives rated highly across evaluators get more influence than those rated poorly:
+
+#### 4.1 Agreement Map
+
+What do all (or most) perspectives agree on? These are robust findings — if sceptics from different traditions converge, the point is likely sound.
+
+#### 4.2 Tension Map
+
+Where do perspectives disagree? For each tension:
+- What is the disagreement about? (framing, method, assumption, evidence standard)
+- Is it resolvable? (empirically testable vs. fundamentally different values)
+- What would it take to resolve it?
+
+#### 4.3 Blind Spot Detection
+
+What did one perspective flag that no others mentioned? These are the most valuable findings — they reveal assumptions that are invisible within the primary discipline.
+
+#### 4.4 Recommendations
+
+Based on the synthesis:
+1. **Strengthen:** What should the researcher do to address the most serious concerns?
+2. **Acknowledge:** What limitations should be explicitly discussed in the paper?
+3. **Test:** What additional analyses could resolve the key tensions?
+4. **Reframe:** Should the question or approach be reconsidered?
+
+### Phase 5: Output
+
+Write the report to the project directory as `PERSPECTIVES-REPORT.md` (or print to console for quick use).
+
+## Output Format
+
+```markdown
+# Multi-Perspective Analysis
+
+**Question:** [The research question or design choice]
+**Date:** YYYY-MM-DD
+**Perspectives:** [N] ([list of labels])
+
+## Perspectives
+
+### 1. [Label]: [Discipline]
+**Prior:** [One sentence]
+**Analysis:** [Agent's full response]
+
+### 2. [Label]: [Discipline]
+...
+
+## Peer Evaluation
+
+| Perspective | Avg Rigour | Avg Relevance | Avg Novelty | Avg Practicality | Overall Rank |
+|-------------|-----------|--------------|------------|-----------------|--------------|
+| [Label] | X.X | X.X | X.X | X.X | #N |
+
+**Key cross-evaluation findings:**
+- [Which perspectives updated their view after seeing others]
+- [Where evaluators converged on a strength/weakness]
+
+## Synthesis
+
+### Agreements
+- [Point 1 — which perspectives agree, and why this is robust]
+- [Point 2]
+
+### Tensions
+
+| Tension | Perspectives | Nature | Resolvable? |
+|---------|-------------|--------|-------------|
+| [Description] | A vs. B | Methodological | Yes — via [test] |
+| [Description] | C vs. D, E | Conceptual | No — different values |
+
+### Blind Spots
+- [Finding] — flagged by [perspective], missed by all others
+- [Finding]
+
+### Recommendations
+1. **Strengthen:** [Most important action]
+2. **Acknowledge:** [Limitation to discuss]
+3. **Test:** [Additional analysis]
+4. **Reframe:** [If applicable]
+
+## Next Steps
+- [ ] [Actionable item 1]
+- [ ] [Actionable item 2]
+```
+
+## Council Mode Enhancement
+
+In standard mode, Phase 3 spawns Claude sub-agents with different personas — but they all share the same underlying model. Council mode upgrades this to genuine model diversity: different LLM providers (Claude, GPT, Gemini) bring genuinely different reasoning patterns, training biases, and knowledge bases.
+
+**Trigger:** "Council multi-perspective" or "thorough multi-perspective"
+
+**What changes in council mode:**
+- Phase 3 (Parallel Investigation): Each perspective is assigned to a different LLM provider via `cli-council`, not Claude sub-agents
+- Phase 3.5 (Cross-Evaluation): Each model evaluates the others' perspectives without knowing which model produced which — genuine blind review
+- Phase 4 (Synthesis): Chairman model reads all perspectives and cross-evaluations, weighted by peer scores
+
+**Invocation (CLI backend):**
+```bash
+cd packages/cli-council
+uv run python -m cli_council \
+    --prompt-file /tmp/perspective-prompt.txt \
+    --context-file /tmp/research-context.txt \
+    --output-md /tmp/perspectives-council.md \
+    --chairman claude \
+    --timeout 180
+```
+
+See `skills/shared/council-protocol.md` for the full orchestration protocol.
+
+**Value:** High — this skill is the natural fit for council mode. The whole point of multi-perspective analysis is cognitive diversity, and using genuinely different models instead of persona-differentiated instances of the same model is a strict upgrade.
+
+## Cross-References
+
+| Skill | When to use instead/alongside |
+|-------|-------------------------------|
+| `/devils-advocate` | Quick single-perspective adversarial feedback |
+| `/literature` | Find the papers that perspectives reference |
+| `/interview-me` | Develop the research idea through structured conversation |
+| Referee 2 agent | Formal paper audit with code verification |
+| `references/computational-many-analysts.md` | When combining qualitative perspectives with quantitative many-analysts |

package/skills/multi-perspective/references/computational-many-analysts.md

@@ -0,0 +1,77 @@
+# Computational Many-Analysts
+
+> How the many-analysts design relates to multi-perspective analysis, when to combine them, and the verification hierarchy. Read when deciding between qualitative perspective diversity and quantitative specification diversity.
+
+## Multi-Perspective vs Many-Analysts
+
+These are complementary, not competing, approaches to robustness:
+
+| Dimension | Multi-Perspective | Many-Analysts |
+|-----------|------------------|---------------|
+| **Question** | "Should we use DiD at all?" | "Given DiD, how sensitive is the ATT to covariate choice?" |
+| **What varies** | Disciplinary lens, theoretical framework, method preference | Implementation choices within a fixed method |
+| **Nature of diversity** | Qualitative — different ways of seeing | Quantitative — different specifications of the same model |
+| **Output** | Agreement/tension map, blind spots | Forest plot, spread-to-SE ratio |
+| **When in pipeline** | Early — before committing to an approach | Late — after locking the estimator, before submission |
+| **Agent design** | Personas with distinct priors | Identical instructions, independent isolation |
+
+**Key distinction:** Multi-perspective agents are deliberately given different epistemic priors (behavioural economist vs econometrician vs sociologist). Many-analyst agents receive identical instructions and differ only through emergent discretionary choices.
+
+## When to Combine
+
+Use `/multi-perspective` first, then many-analysts:
+
+1. **Stage 1 — Multi-Perspective:** "What identification strategy should we use for this policy evaluation?" Spawn disciplinary perspectives to debate DiD vs synthetic control vs IV.
+2. **Lock the approach** based on the synthesis (agreements, resolved tensions).
+3. **Stage 2 — Many-Analysts:** "Given DiD with Callaway & Sant'Anna, how sensitive is the ATT to covariate choice?" Run N isolated agents on the same dataset with the locked estimator.
+4. **Report both:** The multi-perspective analysis justifies the methodological choice; the many-analysts spread quantifies remaining researcher degrees of freedom.
+
+**When NOT to combine:**
+- If the method choice is uncontested (e.g., randomised experiment → just run many-analysts on specification choices)
+- If you're at the conceptual stage and haven't collected data yet (multi-perspective only)
+- If the only question is "does my code run correctly?" (neither — use `/code-review`)
+
+## The Convex Cost Problem
+
+Cunningham (2026, Post 21) observes that AI productivity gains are superlinear in mess:
+
+> "5x productivity → >5x mess."
+
+**Stock pollutants** grow convex: excess files, duplicate outputs, hard-coded results, branching pipelines. Each additional agent run adds output that must be verified, organised, and synthesised.
+
+**Three binding constraints in human-AI research:**
+
+| Constraint | Description | Implication |
+|------------|-------------|-------------|
+| **Verification** | Human must check that agent output is correct | Scales linearly at best; often sublinearly as fatigue sets in |
+| **Attention** | Resist automating the learning process itself | Running 15 agents is easy; understanding why they diverged is hard |
+| **Congestion** | Finding things in your own output | More agents = more output directories, more figures, more specs to track |
+
+**For many-analysts designs:** The value is in the diagnostic (forest plot, covariate heatmap), not in the individual outputs. Design the pipeline to produce the diagnostic automatically — don't manually inspect each agent's work.
+
+## Verification Hierarchy
+
+Karpathy's claim: "The new skill is verification, not generation." This creates a natural hierarchy of verification tools:
+
+| Level | Tool | What it checks | Cost |
+|-------|------|----------------|------|
+| 1. Code correctness | Multi-language audit (R + Python + Stata) | Same specification → same estimate across languages | Medium |
+| 2. Specification sensitivity | Many-analysts design | Same estimator → estimate spread across specification choices | Medium-high |
+| 3. Method sensitivity | Multi-perspective analysis | Different disciplines → different recommended approaches | High |
+| 4. Adversarial review | `referee2-reviewer` agent | Everything a hostile reviewer could exploit | High |
+
+Each level subsumes the one below: if agents can't reproduce the same estimate across languages (Level 1), there's no point measuring specification sensitivity (Level 2).
+
+**Standard reporting:** Include the forest plot from Level 2 in the robustness appendix. Reference the multi-perspective synthesis in the methodology discussion. Adversarial review (Level 4) is a pre-submission internal tool, not reported.
+
+## Connection to Council Mode
+
+The `/multi-perspective` council mode (using `cli-council` with multiple LLM providers) adds genuine model diversity on top of persona diversity. The many-analysts design adds specification diversity on top of that. They operate on different axes:
+
+| Axis | What varies | Tool |
+|------|-------------|------|
+| Model diversity | LLM provider (Claude, GPT, Gemini) | Council mode |
+| Persona diversity | Disciplinary lens and epistemic prior | `/multi-perspective` standard mode |
+| Specification diversity | Implementation choices within a fixed method | Many-analysts design |
+
+All three can run on the same research question, each contributing a different kind of robustness evidence.

package/skills/pipeline-manifest/SKILL.md

@@ -0,0 +1,226 @@
+---
+name: pipeline-manifest
+description: "Use when you need to map scripts to their inputs, outputs, and paper figures/tables."
+allowed-tools: Read, Write, Edit, Glob, Grep, AskUserQuestion
+argument-hint: [project-path]
+---
+
+# Pipeline Manifest
+
+Build and maintain a `pipeline.md` that maps every script in a research project to its inputs, outputs, and the paper figures/tables it feeds. Optionally add structured headers to scripts that lack them.
+
+## When to Use
+
+- When starting a multi-step empirical project (establish the pipeline early)
+- Before sharing code with coauthors (makes the data flow legible)
+- Before submission (ensures the replication package is traceable)
+- After inheriting or reviving old code (pair with `/code-archaeology`)
+- When you can't remember which script produces Figure 3
+
+## When NOT to Use
+
+- Pure theory projects with no empirical pipeline
+- Single-script projects (no pipeline to map)
+- **Code quality review** — use `/code-review` instead (this skill maps structure, not quality)
+
+## Modes
+
+Ask the user which mode to run:
+
+| Mode | What it does | Writes to |
+|------|-------------|-----------|
+| **Scan** (default) | Read-only. Scans scripts, builds `pipeline.md` | `pipeline.md` only |
+| **Add headers** | Scan + insert structured headers into scripts that lack them | `pipeline.md` + script files |
+
+In **Add headers** mode, show the proposed header for each script and get confirmation before writing. Never overwrite an existing structured header — only add to scripts that lack one.
+
+## Structured Script Header Format
+
+Every research script should begin with a structured header block. The format adapts to the language:
+
+### Python
+
+```python
+# ============================================================================
+# PURPOSE: [One sentence describing what this script does]
+# INPUTS:  [Comma-separated list of input files, relative to project root]
+# OUTPUTS: [Comma-separated list of output files, relative to project root]
+# DEPENDS: [Scripts that must run before this one, or "none"]
+# PAPER:   [Figure/table references this feeds, e.g. "Figure 2, Table 1", or "none"]
+# ============================================================================
+```
+
+### R
+
+```r
+# ============================================================================
+# PURPOSE: [One sentence describing what this script does]
+# INPUTS:  [Comma-separated list of input files, relative to project root]
+# OUTPUTS: [Comma-separated list of output files, relative to project root]
+# DEPENDS: [Scripts that must run before this one, or "none"]
+# PAPER:   [Figure/table references this feeds, e.g. "Figure 2, Table 1", or "none"]
+# ============================================================================
+```
+
+### Stata
+
+```stata
+* ============================================================================
+* PURPOSE: [One sentence describing what this script does]
+* INPUTS:  [Comma-separated list of input files, relative to project root]
+* OUTPUTS: [Comma-separated list of output files, relative to project root]
+* DEPENDS: [Scripts that must run before this one, or "none"]
+* PAPER:   [Figure/table references this feeds, e.g. "Figure 2, Table 1", or "none"]
+* ============================================================================
+```
+
+### Julia
+
+```julia
+# ============================================================================
+# PURPOSE: [One sentence describing what this script does]
+# INPUTS:  [Comma-separated list of input files, relative to project root]
+# OUTPUTS: [Comma-separated list of output files, relative to project root]
+# DEPENDS: [Scripts that must run before this one, or "none"]
+# PAPER:   [Figure/table references this feeds, e.g. "Figure 2, Table 1", or "none"]
+# ============================================================================
+```
+
+## Header Field Definitions
+
+| Field | What it contains | How to populate |
+|-------|-----------------|-----------------|
+| **PURPOSE** | One sentence. What does this script do? | Read the script and summarise |
+| **INPUTS** | Files this script reads. Paths relative to project root. | Grep for `read`, `load`, `import`, `open`, `use` patterns |
+| **OUTPUTS** | Files this script writes. Paths relative to project root. | Grep for `write`, `save`, `export`, `ggsave`, `savefig`, `sink` patterns |
+| **DEPENDS** | Other scripts that must run first (their outputs are this script's inputs). | Trace input files back to the scripts that produce them |
+| **PAPER** | Which figures, tables, or sections in the paper use this script's output. | Match output filenames against `\includegraphics`, `\input`, `\include` in `.tex` files |
+
+## Workflow
+
+### Phase 1: Discover Scripts
+
+Scan the project for research scripts:
+
+```
+code/**/*.{py,R,r,do,jl,m}
+src/**/*.{py,R,r,do,jl,m}
+scripts/**/*.{py,R,r,do,jl,m}
+```
+
+Exclude:
+- `__pycache__/`, `.venv/`, `renv/`, `node_modules/`
+- Test files (`test_*.py`, `*_test.R`)
+- Setup/config scripts (`setup.py`, `conftest.py`)
+
+Sort by filename (numerical prefixes like `01_`, `02_` determine natural order).
+
+### Phase 2: Extract Pipeline Information
+
+For each script:
+
+1. **Check for existing header.** Look for the `PURPOSE:` / `INPUTS:` / `OUTPUTS:` / `DEPENDS:` / `PAPER:` pattern in the first 20 lines.
+
+2. **If header exists:** Parse it directly. Trust the header as ground truth.
+
+3. **If no header:** Read the full script and infer:
+   - **Inputs:** File read operations (`pd.read_csv`, `read.csv`, `readRDS`, `load`, `use`, `open`, `import delimited`, `fread`, `arrow::read_parquet`, `readr::read_*`)
+   - **Outputs:** File write operations (`to_csv`, `write.csv`, `saveRDS`, `save`, `ggsave`, `plt.savefig`, `export`, `sink`, `write_parquet`, `fwrite`, `outsheet`, `estout`)
+   - **Dependencies:** Cross-reference — if script B reads a file that script A writes, then B depends on A
+   - **Paper links:** Match output filenames against `\includegraphics{...}` and `\input{...}` in `.tex` files
+
+### Phase 3: Build Dependency Graph
+
+From the extracted information, construct:
+
+1. **Execution order** — topological sort of the dependency graph. Flag cycles as errors.
+2. **Orphan detection** — scripts whose outputs are never used by another script or the paper. These may be exploratory/deprecated.
+3. **Missing link detection** — inputs that no script produces and that don't exist in `data/raw/`.
+
+### Phase 4: Build Paper Linkage
+
+Scan all `.tex` files in `paper/` for:
+- `\includegraphics{path}` — figures
+- `\input{path}` — tables or sub-documents
+- `\include{path}` — chapters
+
+Match these paths to script outputs. Build a reverse map: for each figure/table in the paper, which script(s) produce it?
+
+### Phase 5: Write pipeline.md
+
+Write `pipeline.md` to the project root using the format below.
+
+### Phase 6 (Add Headers Mode Only): Insert Headers
+
+For scripts missing structured headers:
+1. Generate the header from Phase 2 analysis
+2. Show the proposed header to the user
+3. On confirmation, insert at the top of the file (after any shebang line or encoding declaration)
+
+## pipeline.md Format
+
+```markdown
+# Pipeline Manifest
+
+> Auto-generated by `/pipeline-manifest` on YYYY-MM-DD.
+> Manually edit the PAPER column and any inferred values that are wrong.
+> Re-run `/pipeline-manifest` to refresh after adding or modifying scripts.
+
+## Pipeline Table
+
+| # | Script | Purpose | Inputs | Outputs | Depends | Paper |
+|---|--------|---------|--------|---------|---------|-------|
+| 1 | `code/01_clean.R` | Clean raw survey data | `data/raw/survey.csv` | `data/processed/survey_clean.rds` | none | -- |
+| 2 | `code/02_merge.R` | Merge survey with admin data | `data/processed/survey_clean.rds`, `data/raw/admin.csv` | `data/processed/merged.rds` | `01_clean.R` | -- |
+| 3 | `code/03_analysis.R` | Run main regressions | `data/processed/merged.rds` | `results/main_results.rds`, `paper/figures/fig_coef.pdf` | `02_merge.R` | Figure 2 |
+| 4 | `code/04_robustness.py` | Robustness checks | `data/processed/merged.rds` | `results/robustness.csv`, `paper/figures/fig_robust.pdf` | `02_merge.R` | Figure 3, Table A1 |
+
+## Figure & Table Manifest
+
+| Paper Reference | Producing Script | Output File |
+|----------------|-----------------|-------------|
+| Figure 2 | `code/03_analysis.R` | `paper/figures/fig_coef.pdf` |
+| Figure 3 | `code/04_robustness.py` | `paper/figures/fig_robust.pdf` |
+| Table A1 | `code/04_robustness.py` | `results/robustness.csv` |
+
+## Dependency Graph
+
+```
+data/raw/survey.csv ─┐
+                     ├─> 01_clean.R ─> data/processed/survey_clean.rds ─┐
+data/raw/admin.csv ──┘                                                  ├─> 02_merge.R ─> data/processed/merged.rds ─┬─> 03_analysis.R
+                                                                        │                                            └─> 04_robustness.py
+```
+
+## Diagnostics
+
+### Orphan Scripts
+Scripts whose outputs are not consumed by any other script or the paper.
+
+### Missing Inputs
+Files referenced as inputs but not produced by any script and not found in `data/raw/`.
+
+### Execution Order
+Recommended order based on dependency resolution:
+1. `code/01_clean.R`
+2. `code/02_merge.R`
+3. `code/03_analysis.R`
+4. `code/04_robustness.py` (can run in parallel with step 3)
+```
+
+## Updating an Existing pipeline.md
+
+If `pipeline.md` already exists:
+
+1. Read it and parse the existing table
+2. Re-scan scripts (some may have been added, removed, or modified)
+3. **Preserve manual edits** — if the user has edited the PAPER column or added notes, keep those values. Only update fields that can be re-derived from code (PURPOSE, INPUTS, OUTPUTS, DEPENDS).
+4. Flag changes: "2 scripts added, 1 script removed, 3 entries updated"
+5. Write the updated file
+
+## Cross-References
+
+- **`/code-review`** — Quality review for individual scripts (checks header presence in Category 2: Script Structure)
+- **`/code-archaeology`** — For understanding unfamiliar code before building the manifest
+- **`/pre-submission-report`** — Pipeline manifest helps verify the replication package is complete
+- **`/init-project-research`** — New projects can run `/pipeline-manifest` once scripts exist