v0.1.0 to v0.1.4

---

name: paper-discourse-graph

description: "Audit LaTeX papers as discourse graphs when paragraph flow, story continuity, readability, reader-state breadcrumbs, payoff chains, or figure/equation placement matter. Use when the user asks whether a section feels abrupt, wasteful, machine-generated, monotonous, hard to parse, or wants to zoom in/out across paragraphs before editing."

metadata:

---

# Paper Discourse Graph

Use this skill to review a paper section as a reader-state graph, not

only as a linear outline. The goal is to see what each paragraph

plants, what it pays off, where notation appears before intuition, and

where a justification detour interrupts the main story.

## 1. Workflow

### 1.1 Establish scope

Identify the source `.tex` file or section to audit. If the user wants

discussion before editing, produce findings and proposed interventions

only.

Look for project-local guidance before running a generic pass:

- `AGENT_REVIEW_BRIEF.md`

- `docs/*review*brief*.md`

- `tools/discourse_graph/profiles/*.json`

- paper-specific profiles or terminology docs

### 1.2 Choose a profile

Use the most specific available profile:

1. user-provided `--profile`

2. project-local profile, if present

3. bundled `references/profiles/cphast.json` for C-PHAST drafts

4. bundled `references/profiles/default_scientific_paper.json`

Profiles define the central reader question, audience needs, domain

terms, and topic checks. Keep project taste in profiles, not in the

engine.

### 1.3 Run the CLI

From this skill directory:

```bash

python scripts/discourse_graph_audit.py <source.tex> \

--section <stable-id> \

--profile references/profiles/default_scientific_paper.json \

--out <report.md> \

--json-out <graph.json>

```

For C-PHAST:

```bash

python scripts/discourse_graph_audit.py paper/sec/3_method_arxiv.tex \

--section 3 \

--profile references/profiles/cphast.json \

--out paper/docs/plans/discourse_graph_sec3.md \

--json-out paper/docs/plans/discourse_graph_sec3.json

```

Optional LLM chunks:

```bash

python scripts/discourse_graph_audit.py <source.tex> \

--section <stable-id> \

--out <report.md> \

--llm-jsonl <nodes.jsonl>

```

### 1.4 Interpret the report

Treat the graph as triage, not truth. The labels are prompts for

manual review.

Important node roles:

- `scene`: visible example or running situation

- `question`: planted reader question

- `claim`: assertion or section-level promise

- `mechanism`: method component or construction

- `definition` / `notation`: formal object introduction

- `justification`: reason, proof sketch, or defensive support

- `evidence`: figure, table, theorem, algorithm, or equation block

- `boundary`: scope limit or condition

- `payoff`: answer to earlier setup

- `handoff`: transition to the next object

Important risk labels:

- `abrupt`: weak continuity into the current block

- `detour`: useful material that may interrupt the active story

- `unpaid_question`: a planted question without nearby payoff

- `premature_notation`: dense formal terms before visible grounding

- `weak_parent_link`: paragraph is weakly tied to its heading

- `bridge_candidate`: possible bridge that may rescue a detour

- `unconnected_evidence`: figure/table/algorithm not clearly recalled

## 2. Review Taste

For each paragraph or block, ask:

- What does the reader know right now?

- What question did the previous block plant?

- Does this block answer, sharpen, or defer that question?

- Is the payoff close enough, or is the reader carrying too much load?

- Is this block story-bearing, justification-bearing, evidence-bearing,

implementation-bearing, or boundary-bearing?

Prefer a chain where understanding progressively accumulates:

visible scene -> reader question -> mechanism -> formal object ->

evidence -> payoff -> next question.

Use visible language before formal terms. A dense equation should feel

inevitable because the previous paragraph made the need for that

object obvious.

## 3. Output Format

Report findings with:

- file and line range

- live reader question

- risk label

- why the current placement breaks or helps the story

- smallest proposed intervention

Use labels:

- **Payoff**: answers a live reader question

- **Plant**: intentionally creates the next question

- **Bridge**: connects intuition to a formal object

- **Detour**: useful but not needed for the current story step

- **Stray**: does not support the current claim chain

When the user asks to discuss, do not edit. Rank the highest-value

changes and ask which ones to land.

## 4. Bundled Resources

- `scripts/discourse_graph_audit.py`: command-line entry point

- `scripts/discourse_graph/`: dependency-free LaTeX segmentation,

heuristics, schema, and rendering code

- `references/profiles/default_scientific_paper.json`: general profile

- `references/profiles/cphast.json`: C-PHAST profile with typed

factors, charts, ports, PHASTCore, and action-card checks

## 5. Pitfalls

- Do not treat lexical overlap as a correctness judgment.

- Do not force every paragraph to use explicit transition phrases.

- Do not remove rigorous caveats merely because they are detours;

decide whether they belong later, in an appendix, or in a tighter

boundary sentence.

- Do not let profile-specific vocabulary leak into unrelated papers.