import json


def _paper_figure_claims_json(figures):
    """Keep each claim bound to its supplied path, including Windows paths."""
    return json.dumps([
        {
            "key": figure.get("key", "?"),
            "claim": figure.get("claim") or figure.get("caption", ""),
            **({"composite_path": figure["composite_path"]}
               if "composite_path" in figure else {}),
        }
        for figure in figures
    ], ensure_ascii=False, indent=2)


def paper_brief_schema():
    return {
        "type": "object",
        "properties": {
            "pitch": {"type": "string"},
            "vision": {"type": "string"},
            "audience": {"type": "string"},
            "most_arresting_asset": {"type": "string"},
            "figures": {
                "type": "array",
                "items": {
                    "type": "object",
                    "properties": {
                        "key": {"type": "string"},
                        "claim": {"type": "string"},
                        "composite_path": {"type": ["string", "null"]},
                    },
                    "required": ["key", "claim"],
                },
            },
        },
        "required": ["pitch", "vision", "figures"],
    }


def paper_brief_task(abstract_text, figure_claims):
    figure_table = _paper_figure_claims_json(figure_claims)
    return f"""Act as the corresponding author. Derive a structured paper brief
from the abstract and figure claims below.

Pitch is the grandest supportable one-sentence biological or scientific claim,
not a method description. Vision states what a reader can now do. Name the one
figure or panel that would be most arresting on a poster. Preserve every supplied
concrete `composite_path`; do not invent paths or artifact ids.

## Abstract
{abstract_text}

## Figures
```json
{figure_table}
```

Return only data matching the supplied paper brief schema."""


def narrative_review_schema():
    return {
        "type": "object",
        "properties": {
            "hook_verdict": {
                "type": "object",
                "properties": {
                    "would_send_for_review": {
                        "type": "string",
                        "enum": ["yes", "weak", "no"],
                    },
                    "why": {"type": "string"},
                    "fig1_is": {"type": "string"},
                    "fig1_should_be": {"type": "string"},
                },
                "required": ["would_send_for_review", "why", "fig1_should_be"],
            },
            "figure_moves": {
                "type": "array",
                "items": {
                    "type": "object",
                    "properties": {
                        "what": {"type": "string"},
                        "from_fig": {"type": "string"},
                        "to_fig": {"type": "string"},
                        "why": {"type": "string"},
                    },
                    "required": ["what", "from_fig", "to_fig", "why"],
                },
            },
            "missing_panels": {
                "type": "array",
                "items": {
                    "type": "object",
                    "properties": {
                        "target_fig": {"type": "string"},
                        "what_to_show": {"type": "string"},
                        "analysis_needed": {"type": "string"},
                        "data_hint": {"type": "string"},
                    },
                    "required": ["target_fig", "what_to_show", "analysis_needed"],
                },
            },
            "kill_list": {
                "type": "array",
                "items": {
                    "type": "object",
                    "properties": {
                        "what": {"type": "string"},
                        "why": {"type": "string"},
                        "demote_to": {
                            "type": "string",
                            "enum": ["supplement", "caption", "delete"],
                        },
                    },
                    "required": ["what", "why", "demote_to"],
                },
            },
            "arc": {
                "type": "array",
                "items": {
                    "type": "object",
                    "properties": {
                        "fig": {"type": "string"},
                        "role": {
                            "type": "string",
                            "enum": ["hook", "mechanism", "evidence", "application", "supplement"],
                        },
                        "one_line": {"type": "string"},
                    },
                    "required": ["fig", "role", "one_line"],
                },
            },
            "boldest_defensible_fig1": {"type": "string"},
        },
        "required": [
            "hook_verdict",
            "figure_moves",
            "missing_panels",
            "kill_list",
            "arc",
            "boldest_defensible_fig1",
        ],
    }


def narrative_review_task(brief, deck_paths, rules_path=None):
    figure_table = _paper_figure_claims_json(brief.get("figures", []))
    paths = "\n".join(f"- `{path}`" for path in deck_paths)
    rules_line = f"\nDesign-rule source: `{rules_path}`" if rules_path else ""
    return f"""Act as the handling editor deciding whether this submission should
be sent for review. Judge the story rather than polishing figure craft.

Inspect every concrete image path with Wisp's `view_image` tool. The paths may
be page images rendered from a PDF. Do not invent a file resolver.

## Paper brief
**Pitch:** {brief.get('pitch', '—')}
**Vision:** {brief.get('vision', '—')}
**Audience:** {brief.get('audience', 'general scientist')}
**Most arresting asset:** {brief.get('most_arresting_asset', '—')}

## Figure deck images
{paths}{rules_line}

## Per-figure claims
```json
{figure_table}
```

Test whether Figure 1 alone creates a compelling hook. Propose the arc from hook
through mechanism and evidence to application; move misplaced panels; specify
missing panels and the concrete analyses needed; identify content to demote or
delete; and state the boldest defensible Figure 1. Return only data matching the
supplied narrative review schema."""

---
name: paper-narrative
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

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. 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. The brief and review instructions
   include JSON figure records so each path stays associated with its claim;
   keep those records when delegating, including paths with spaces or Unicode.
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.

Use `run_in_context` only for deterministic analyses requested by
`missing_panels`. Narrative reasoning and Agent delegation are not Runs.

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