agentleFS
shubham0704shubham0704/claude-skills/paper-discourse-graph/SKILL.md

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.

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
  1. Distinctive:

    Use this skill to review a paper section as a reader-state graph, not only as a linear outline.

    line 10
  2. Distinctive:

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

    line 23
  3. Distinctive:

    If a teaching deck exists, compare its prerequisites and payoff with the paper.

    line 40
  4. Distinctive:

    When needed, rehearse a short storyboard before revising continuous prose.

    line 42
  5. Distinctive:

    Use the most specific available profile:

    line 48
  6. Very specific:

    When authoring or revising source files and the user wants durable machine-readable breadcrumbs for later passes, read …

    line 65
  7. Distinctive:

    Treat the graph as triage, not truth.

    line 106
  8. Distinctive:

    If this became a task for a fresh agent, what local context, invariants, and claim boundaries would that task need?

    line 164
  9. Distinctive:

    Prefer a chain where understanding progressively accumulates: visible scene -> reader question -> mechanism -> formal object -> evidence -> …

    line 180
  10. Distinctive:

    Use visible language before formal terms.

    line 184
  11. Distinctive:

    Stray: does not support the current claim chain

    line 209
  12. Distinctive:

    When the user asks to discuss, do not edit.

    line 211
  13. Distinctive:

    Do not treat lexical overlap as a correctness judgment.

    line 234
  14. Distinctive:

    Do not force every paragraph to use explicit transition phrases.

    line 235
  15. Distinctive:

    Do not remove rigorous caveats merely because they are detours.

    line 236
  16. Distinctive:

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

    line 239
  17. Very specific:

    Keep paper-specific notation families in the profile, for example risk_rules.confusable_symbol_bases, not in the reusable engine.

    line 240

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 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:

  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.

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

Optional 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 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
  • semantic_comment: source-only % DG: breadcrumb used to record author intent without rendering in the PDF

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
  • context_debt: named setting or experiment appears before enough local setup
  • appendix_claim_leak: appendix-only evidence is doing main-text argumentative work
  • symbol_alias_confusion: profile-tracked symbols gain a new subscript or variant without explaining the relationship
  • coarse_algorithm_reference: algorithm behavior is described without line, stage, equation, or step anchors
  • missing_formal_setup: equation-like block appears before prose creates the need for it
  • missing_formal_payoff: equation-like block is not followed by a nearby interpretation
  • symbol_scope_debt: formal block introduces several new symbols without nearby scope, type, or dependency prose
  • role_mismatch: prose promises intuition or readability but hands off to dense notation without enough setup
  • equation_overload: formal block introduces many symbolic objects at once
  • dangling_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 point
  • scripts/discourse_graph/: dependency-free LaTeX segmentation, heuristics, schema, and rendering code
  • references/formal_block_flow.md: detailed rubric for paragraphs, notation, equations, interpretation, and consistency
  • references/appendix_evidence_passes.md: appendix and supplement rubric for reader entry, evidence co-location, reproduction value, benchmark-role clarity, captions, and main-text linkage
  • references/paragraph_refinement_tasks.md: late-stage per-paragraph task protocol for fresh review passes
  • references/source_semantic_comments.md: optional % DG: comment convention for source-level discourse breadcrumbs
  • 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.
  • Keep paper-specific notation families in the profile, for example risk_rules.confusable_symbol_bases, not in the reusable engine.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.