Scientific Writing — Stage 1: Find the Story
Overview
A research repo accumulates parallel and abandoned experiments. Before any outline or prose, establish ONE linear story: the thesis, the experiments that support it, and an explicit record of what was dropped. Output: docs/writing/<story-slug>/story.md in the consuming repo.
Do not write the story from your own assumptions. Map the repo, then converge with the user.
Method backbone — Steps 1–2
This stage is Steps 1–2 of the fifteen steps (detail: scientific-writing/fifteen-steps.md):
- Step 1 — main point. The thesis is one short declarative sentence (subject + verb) that scopes the phenomenon and gives focus. Every later paragraph must illuminate it. It need not become the final title.
- Step 2 — narrative arc. The arc answers what did we want to learn, why, what did we do, what do we know now, and follows the key transitions (question→answer, theory→evidence, data→interpretation). Prefer a two-part structure — the most memorable and publishable shape. Confirm which two-part scheme fits when you converge with the user (e.g. experiment 1 + experiment 2; simple model + complicated model; experiment + model to explain it; model + experiment to test it; observed pattern + model to explain it).
Process
- Map the research cloud. Dispatch
Explore subagents (read-only) to inventory:
experiments/scripts, results/, figures/, notebooks, git log, and CLAUDE.md.
Use superpowers:dispatching-parallel-agents if there are independent areas.
Goal: a list of every experiment/result thread, each tagged candidate-main vs possibly-dropped.
- Converge with the user, ONE question at a time. Confirm: the working title, the single thesis, which threads are IN, which are DROPPED. Prefer multiple-choice. Do not proceed to writing until the user confirms the thesis and the in/out split.
- Write
story.md (template below).
story.md template
# <Working title>
slug: <kebab-case-slug>
## Thesis
<one or two sentences — the single claim the paper makes>
## Narrative arc (linear)
Two-part scheme: <which Step-2 scheme, e.g. "experiment + model to explain it">
1. <beat> 2. <beat> 3. <beat> … (the logical order the paper will argue in)
## Beat → artifacts
| Beat | Supporting artifacts (scripts / results / plots / notebooks) |
|------|------|
| <beat> | `path/to/script.py`, `results/x.csv`, `figures/y.svg` |
## Dropped / out of scope
- <thread> — why dropped (user-confirmed)
Red flags — STOP
- Writing
story.md before mapping the repo → map first.
- Asserting a thesis the user hasn't confirmed → ask.
- A beat with no backing artifact → either find it or it's not a beat.
- An abandoned experiment silently included → it goes in Dropped.
Next stage
Once the user approves story.md, invoke scientific-writing-outline.
1---2name: scientific-writing-story3description: Use when starting a scientific manuscript from a code+results repo and you need to separate the real paper from the "research cloud" of parallel/abandoned experiments. Stage 1 of scientific-writing — produces story.md.4---56# Scientific Writing — Stage 1: Find the Story78## Overview9A research repo accumulates parallel and abandoned experiments. Before any outline or prose, establish ONE linear story: the thesis, the experiments that support it, and an explicit record of what was dropped. Output: `docs/writing/<story-slug>/story.md` in the consuming repo.1011**Do not write the story from your own assumptions. Map the repo, then converge with the user.**1213## Method backbone — Steps 1–214This stage is Steps 1–2 of the fifteen steps (detail: `scientific-writing/fifteen-steps.md`):15- **Step 1 — main point.** The thesis is *one short declarative sentence* (subject + verb) that scopes the phenomenon and gives focus. Every later paragraph must illuminate it. It need not become the final title.16- **Step 2 — narrative arc.** The arc answers *what did we want to learn, why, what did we do, what do we know now*, and follows the key transitions (question→answer, theory→evidence, data→interpretation). **Prefer a two-part structure** — the most memorable and publishable shape. Confirm which two-part scheme fits when you converge with the user (e.g. experiment 1 + experiment 2; simple model + complicated model; experiment + model to explain it; model + experiment to test it; observed pattern + model to explain it).1718## Process19201. **Map the research cloud.** Dispatch `Explore` subagents (read-only) to inventory:21 experiments/scripts, `results/`, `figures/`, notebooks, git log, and CLAUDE.md.22 Use `superpowers:dispatching-parallel-agents` if there are independent areas.23 Goal: a list of every experiment/result thread, each tagged *candidate-main* vs *possibly-dropped*.242. **Converge with the user, ONE question at a time.** Confirm: the working title, the single thesis, which threads are IN, which are DROPPED. Prefer multiple-choice. Do not proceed to writing until the user confirms the thesis and the in/out split.253. **Write `story.md`** (template below).2627## story.md template28```markdown29# <Working title>30slug: <kebab-case-slug>3132## Thesis33<one or two sentences — the single claim the paper makes>3435## Narrative arc (linear)36Two-part scheme: <which Step-2 scheme, e.g. "experiment + model to explain it">371. <beat> 2. <beat> 3. <beat> … (the logical order the paper will argue in)3839## Beat → artifacts40| Beat | Supporting artifacts (scripts / results / plots / notebooks) |41|------|------|42| <beat> | `path/to/script.py`, `results/x.csv`, `figures/y.svg` |4344## Dropped / out of scope45- <thread> — why dropped (user-confirmed)46```4748## Red flags — STOP49- Writing `story.md` before mapping the repo → map first.50- Asserting a thesis the user hasn't confirmed → ask.51- A beat with no backing artifact → either find it or it's not a beat.52- An abandoned experiment silently included → it goes in Dropped.5354## Next stage55Once the user approves `story.md`, invoke `scientific-writing-outline`.
d-laub