paper-discourse-graph
Skill2 starsChanged 6 months agoMITView on GitHub
Audit LaTeX papers as discourse graphs when paragraph flow, story continuity, readability, reader-state breadcrumbs, payoff chains, appendix/supplement structure, 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; also use for GRE-style paragraph logic checks such as topic promise, paragraph unity, sentence-to-sentence coherence, given-to-new flow, overload, payoff, and handoff.
In this repository10 other files it gives its agents.
The file
Show its rules and text
We split this skill into the rules it gives an agent
17 rules. About 0 are common, 15 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈15
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 10
Use this skill to review a paper section as a reader-state graph, not only as a linear outline.
- Distinctive: line 23
Look for project-local guidance before running a generic pass:
- Distinctive: line 40
If a teaching deck exists, compare its prerequisites and payoff with the paper.
- Distinctive: line 42
When needed, rehearse a short storyboard before revising continuous prose.
- Distinctive: line 48
Use the most specific available profile:
- Very specific: line 65
When authoring or revising source files and the user wants durable machine-readable breadcrumbs for later passes, read …
- Distinctive: line 106
Treat the graph as triage, not truth.
- Distinctive: line 164
If this became a task for a fresh agent, what local context, invariants, and claim boundaries would that task need?
- Distinctive: line 180
Prefer a chain where understanding progressively accumulates: visible scene -> reader question -> mechanism -> formal object -> evidence -> …
- Distinctive: line 184
Use visible language before formal terms.
- Distinctive: line 209
Stray: does not support the current claim chain
- Distinctive: line 211
When the user asks to discuss, do not edit.
- Distinctive: line 234
Do not treat lexical overlap as a correctness judgment.
- Distinctive: line 235
Do not force every paragraph to use explicit transition phrases.
- Distinctive: line 236
Do not remove rigorous caveats merely because they are detours.
- Distinctive: line 239
Do not let profile-specific vocabulary leak into unrelated papers.
- Very specific: line 240
Keep paper-specific notation families in the profile, for example risk_rules.confusable_symbol_bases, not in the reusable engine.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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.mddocs/*review*brief*.mdtools/discourse_graph/profiles/*.json- paper-specific profiles or terminology docs
1.2 Check the whole argument before local polish
For a paper-level revision, connect the opening question to the proposed insight, the mechanism, and the exact evidence that answers it. For a narrow edit, inspect only the relevant part of that chain. Distinguish three cases:
- Exposition gap: the answer exists but its placement or explanation hides it.
- Evidence gap: the paper has not yet answered the question; prose cannot close it.
- Scope mismatch: the result answers a narrower or different question than promised.
If a teaching deck exists, compare its prerequisites and payoff with the paper; do not import its spoken assumptions or one-slide-per-paragraph structure. When needed, rehearse a short storyboard before revising continuous prose. Report the most consequential gap first. Lexical overlap with a generic heading such as "Introduction" is not a useful acceptance criterion by itself.
1.3 Choose a profile
Use the most specific available profile:
- user-provided
--profile - project-local profile, if present
- bundled
references/profiles/cphast.jsonfor C-PHAST drafts - 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.
For methods, theory, or appendix sections where paragraphs hand off to
notation and equations, also read
references/formal_block_flow.md.
For appendix, supplement, benchmark-protocol, result-table, or
figure-placement audits, also read
references/appendix_evidence_passes.md.
When authoring or revising source files and the user wants durable
machine-readable breadcrumbs for later passes, read
references/source_semantic_comments.md.
For late-stage paragraph-by-paragraph refinement, task breakdowns for
fresh agents, requests to zoom into each paragraph with a fresh mind,
or GRE-style paragraph evaluation of topic sentence, unity, coherence,
development, and transition, read references/paragraph_refinement_tasks.md.
1.4 Run the CLI
From this skill directory:
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:
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.jsonOptional LLM chunks:
python scripts/discourse_graph_audit.py <source.tex> \
--section <stable-id> \
--out <report.md> \
--llm-jsonl <nodes.jsonl>1.5 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 situationquestion: planted reader questionclaim: assertion or section-level promisemechanism: method component or constructiondefinition/notation: formal object introductionjustification: reason, proof sketch, or defensive supportevidence: figure, table, theorem, algorithm, or equation blockboundary: scope limit or conditionpayoff: answer to earlier setuphandoff: transition to the next objectsemantic_comment: source-only% DG:breadcrumb used to record author intent without rendering in the PDF
Important risk labels:
abrupt: weak continuity into the current blockdetour: useful material that may interrupt the active storyunpaid_question: a planted question without nearby payoffpremature_notation: dense formal terms before visible groundingweak_parent_link: paragraph is weakly tied to its headingbridge_candidate: possible bridge that may rescue a detourunconnected_evidence: figure/table/algorithm not clearly recalledcontext_debt: named setting or experiment appears before enough local setupappendix_claim_leak: appendix-only evidence is doing main-text argumentative worksymbol_alias_confusion: profile-tracked symbols gain a new subscript or variant without explaining the relationshipcoarse_algorithm_reference: algorithm behavior is described without line, stage, equation, or step anchorsmissing_formal_setup: equation-like block appears before prose creates the need for itmissing_formal_payoff: equation-like block is not followed by a nearby interpretationsymbol_scope_debt: formal block introduces several new symbols without nearby scope, type, or dependency proserole_mismatch: prose promises intuition or readability but hands off to dense notation without enough setupequation_overload: formal block introduces many symbolic objects at oncedangling_reference: paragraph starts from this/these/such object without a clear local antecedent
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?
- If this became a task for a fresh agent, what local context, invariants, and claim boundaries would that task need?
For sentence-level paragraph flow, use the paragraph-logic lens:
- Topic promise: can the paragraph be summarized in 6--10 words?
- Unity: does every sentence serve that promise?
- Given-to-new flow: does each sentence start from known ground and add one new object or relation?
- Load: does the paragraph introduce more than two or three new objects before payoff?
- Payoff: does the final sentence tell the reader what changed or why the paragraph mattered?
- Handoff: does the next paragraph feel inevitable rather than adjacent?
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.
For formal blocks, check the local loop: paragraph motivates need -> notation names object -> equation commits to definition/update/loss/constraint/readout -> paragraph interprets what changed for the reader.
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 pointscripts/discourse_graph/: dependency-free LaTeX segmentation, heuristics, schema, and rendering codereferences/formal_block_flow.md: detailed rubric for paragraphs, notation, equations, interpretation, and consistencyreferences/appendix_evidence_passes.md: appendix and supplement rubric for reader entry, evidence co-location, reproduction value, benchmark-role clarity, captions, and main-text linkagereferences/paragraph_refinement_tasks.md: late-stage per-paragraph task protocol for fresh review passesreferences/source_semantic_comments.md: optional% DG:comment convention for source-level discourse breadcrumbsreferences/profiles/default_scientific_paper.json: general profilereferences/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.
- Keep paper-specific notation families in the profile, for example
risk_rules.confusable_symbol_bases, not in the reusable engine.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

