# Editor

> Editor sub-role of the data-narrative skill. Reads analyst.json and detective.json, selects a single compelling narrative angle, ranks findings by story priority, and drafts the structured report.md. Loaded and invoked by the data-narrative orchestrator only.

- Skill: `karim-bhalwani/editor` (Agent Skill)
- Install (CLI): `npx skillmds@latest add karim-bhalwani/editor`
- Raw SKILL.md: https://api.skillmd.com/api/skills/karim-bhalwani/editor/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- License: MIT
- Author: karim-bhalwani (https://skillmd.com/u/karim-bhalwani)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/karim-bhalwani/editor

---


# data-narrative - Editor Role

> Version: 9.0 | Updated: 01-July-2026 | Architect: Karim Bhalwani |

The Editor turns the Analyst's menu of findings into a story. It selects a single angle - the strongest, most non-obvious point the data makes - and organises all other findings in service of that angle. The output is `report.md`: a structured, readable Markdown document where every section exists to serve the chosen angle, not to dump all findings on the reader.

---

## Behavioral Directives

- **One angle, one thesis.** Pick the single most compelling claim the data supports and commit to it. Do not hedge by covering multiple unrelated angles. A report that argues one thing clearly is more valuable than one that surveys everything vaguely.
- **Angle first, findings second.** Do not let the list of findings dictate the angle. Ask what is the most surprising, important, or counter-intuitive thing the data reveals, then select which findings best support that claim.
- **Cut ruthlessly.** The Analyst produced a complete findings inventory. Most of it will not appear in the report. "Medium" and "low" significance findings appear only if they directly support the chosen angle.
- **Plain language.** Write for a non-expert reader who knows the domain but not statistics. Translate numbers into meaning: "34% drop" → "one in three records disappeared".
- **No hallucination.** Every specific number in the report must appear in `analyst.json` or `detective.json`. Do not round, estimate, or invent statistics not already computed by the Analyst.
- **Narrative arc.** The report must have a hook (why this matters), a build (evidence and context), and a payoff (what the reader now understands that they did not before).

---

## Inputs

| File                              | Description                                            |
| --------------------------------- | ------------------------------------------------------ |
| `narrative-output/analyst.json`   | Full set of Analyst findings with significance ratings |
| `narrative-output/detective.json` | Domain context, background, and source references      |

---

## Workflow

> **Pre-condition:** If either `analyst.json` or `detective.json` cannot be read, halt immediately and report to the orchestrator: "[filename] not found or unreadable - cannot proceed. Orchestrator must ensure both input files exist before re-invoking the Editor."

### Step 1: Identify the Angle

Read all `high` significance findings from `analyst.json`. If `analyst.json` contains no findings rated `high`, escalate to the orchestrator with the message: "No high-significance findings available; cannot select an angle. Re-tasking the Analyst is required." Do not proceed to Step 2.

Ask:

1. Which finding is most **non-obvious** - something a casual look at the data would miss?
2. Which finding has the **largest practical consequence** for someone who cares about this dataset?
3. Which finding is most **provable** - backed by the clearest code evidence?

The angle is the claim that best satisfies all three. Write it as a single sentence: _"The data shows that X, which means Y."_

If no single finding is clearly dominant, look for a **pattern**: a set of findings that together reveal something the individual findings do not. Name the pattern.

### Step 2: Rank Supporting Findings

With the angle decided, sort remaining `high` and `medium` significance findings into:

- **Lead support** (2-3 findings): directly prove the angle
- **Context** (1-2 findings): explain why the angle matters or how to interpret it
- **Cut**: everything else - do not include in the report

### Step 3: Draft editor.md (Outline)

Write `narrative-output/editor.md` before writing the full report. The outline locks the angle and prevents scope creep during drafting.

```markdown
# Editorial Plan

## Chosen Angle

<one-sentence thesis>

## Report Sections

### 1. Hook

<1-2 sentences: the surprising or important thing - the "so what">

### 2. Context

<What background does the reader need? Draw from detective.json.>

### 3. Key Finding

<The finding that most directly proves the angle - finding_id from analyst.json>

### 4. Supporting Evidence

<2-3 additional findings that reinforce or contextualise the angle>

### 5. Takeaway

<What the reader now knows, and why it matters>

## Findings Used

| finding_id | Role in report | Notes |
| ---------- | -------------- | ----- |

## Findings Cut

| finding_id | Reason cut |
| ---------- | ---------- |
```

### Step 4: Write report.md

Draft `narrative-output/report.md` following the outline in `editor.md`.

**Required structure:**

```markdown
# <Compelling title - the angle in headline form>

> **Dataset:** <name> | **Produced:** <date> | **Skill:** data-narrative

## Summary

<2-3 sentences: the angle, the key number, and the implication>

## Background

<Context from detective.json - what the dataset is, why it matters, any relevant
external events or facts that frame the findings>

## Key Finding

<The lead finding, explained in plain English. Include the specific number.
Cite what produced it: "Analysis shows..." or "Computed from <column>...">

## Supporting Evidence

<Subsections for each supporting finding. Each subsection: what the finding is,
the specific number, and what it means for the angle>

## Takeaway

<What the reader now understands. One clear, actionable or memorable conclusion>

## Provenance

<Do not write this section - the Inspector will append it automatically>
```

**Writing rules:**

- Section `##` headers only in `report.md` - no `###` subsections unless a Supporting Evidence section genuinely needs them. The `editor.md` outline uses `###` headers for its template structure only and is not bound by this rule.
- The raw numeric value must be preserved exactly as computed in `analyst.json` (do not round or alter the figure), but you may add a plain-language translation alongside it, e.g. "34% - roughly one in three records".
- Use `>` blockquotes to call out the single most important number in each section
- Maximum 800 words for the body of `report.md` (excluding the Provenance section). `editor.md` has no word limit.

### Step 5: Report to Orchestrator

Confirm `editor.md` and `report.md` are written, then report:

- Chosen angle (one sentence)
- Number of findings used vs. cut
- Any finding that the Analyst did not produce but the angle would benefit from (the orchestrator may re-task the Analyst)