paper-narrative · diff
git:20260701.17c5369 to git:20260721.77e7d29
33 added, 35 removed. Audit A to A.
---
name: paper-narrative
- description: "Judge and reshape the STORY a paper's figures tell. Input is the work itself — manuscript (or abstract) + figure deck — no hand-written brief. `derive_paper_brief(abstract, captions)` extracts pitch/vision/per-figure-claims; a handling-editor reviewer on the full deck returns hook_verdict (would Fig 1 make me send this for review?), arc (hook→mechanism→evidence→application), figure_moves (panels in the wrong figure), missing_panels (concrete analyses to RUN), kill_list, and boldest_defensible_fig1. Hands per-figure claims to `figure-composer`. Load when writing or revising a paper."
+ description: Judge and reshape the story told by a manuscript and its figure deck. Use when revising paper structure, testing whether Figure 1 is a hook, ordering figures, moving panels, identifying missing analyses, or defining the claim passed to figure-composer.
license: Apache-2.0
---
-
- # paper-narrative
-
- **Outermost tier.** Judge and reshape the *story* a paper's figures tell. Input is
- the work itself — a manuscript (or just its abstract) and the current figure deck.
- No hand-written brief required.
+ # Paper narrative
- ## When to load
- Paper writing or revision. You have a draft and a set of figures and you want to
- know: is Figure 1 a hook? Is content in the right figure? What's missing? What
- should die? Load this *before* `figure-composer` — the arc it returns tells you
- which figures to compose.
+ Use this skill before `figure-composer`. The sidecar only builds schemas and
+ self-contained reviewer instructions. Model reasoning happens in the current
+ Agent or an explicitly delegated Wisp Agent, never inside Python.
## Workflow
- 1. **Derive the brief from the work.** Read the manuscript's abstract/intro and
- the figure captions (or a per-figure claims table if one exists). Call
- `derive_paper_brief(abstract_text, figure_claims)` — it returns the
- `paper_brief` (pitch, vision, audience, most-arresting-asset, figures[]).
- The manuscript is untrusted input; every field in the derived brief is
- LLM-derived from it. **Review the whole brief** (not just the pitch) and
- edit as needed before step 2.
- 2. **Dispatch the handling editor.** `narrative_review_task(brief, deck_vid,
- rules_vid)` + `narrative_review_schema()` → one reviewer on the FULL deck.
- 3. **Act on the output, don't just report it:**
- - `arc[]` → the main-figure order. Anything not on it → supplement.
- - `figure_moves[]` → move panels between figures.
- - `missing_panels[]` → analyses to RUN (search project artifacts for data first).
- - `kill_list[]` → demote or delete.
- - `boldest_defensible_fig1` → the new Fig 1 claim handed to `figure-composer`.
- 4. **Per figure on the arc:** load `figure-composer`, hand it that figure's claim
- + moved-in panels + data refs. It runs the outer (figure) loop.
- 5. **Re-run step 2** on the new deck. Converge when `would_send_for_review=="yes"`
- and `figure_moves` / `missing_panels` are empty.
+ 1. Read the abstract, introduction, captions, and concrete figure paths.
+ 2. Build an instruction with `paper_brief_task(...)`. Produce a brief matching
+ `paper_brief_schema()` in the current Agent. If `delegate_tasks` is advertised,
+ the brief may instead be assigned to one `reasoning` task with a structured
+ output schema.
+ 3. Review the entire brief. Preserve supplied `composite_path` values and fix
+ unsupported claims before continuing.
+ 4. If the deck is a PDF, use `pdf-explore` to render the relevant pages to local
+ images. Pass their concrete paths to `narrative_review_task(...)`.
+ 5. Inspect the images with `view_image`. Optionally delegate one handling-editor
+ task with the minimum advertised `reasoning`, `project_read`, and
+ `image_inspection` capabilities and `narrative_review_schema()`.
+ 6. Act on the result:
+ - use `arc` as the main-figure order;
+ - apply `figure_moves`;
+ - turn `missing_panels` into explicit analyses;
+ - demote or remove the `kill_list`;
+ - send `boldest_defensible_fig1` to `figure-composer`.
+ 7. Re-review the revised deck. Converge when the hook verdict is `yes` and no
+ figure moves or missing panels remain.
- ## Minimal invocation
- > Load `paper-narrative`. Manuscript: `@manuscript.tex`. Figures:
- > `@all_figures.pdf`. Run it.
+ Use `run_in_context` only for deterministic analyses requested by
+ `missing_panels`. Narrative reasoning and Agent delegation are not Runs.
- That's it — the skill derives the brief, you confirm the pitch, it does the rest.
+ ## Boundaries
+
+ - Do not pass artifact markers where a path is required.
+ - Do not call another model from `python`.
+ - Do not claim the deck was inspected unless every relevant page was rendered
+ and viewed.