Ar9av/PaperOrchestra / skills/content-refinement-agent
content-refinement-agent
VerifiedStep 5 of the PaperOrchestra pipeline (arXiv:2604.05018). Iteratively refine drafts/paper.tex by simulating peer review and applying targeted revisions, with strict accept/revert halt rules, deterministic 0-100 decision bands (Accept/Minor/Major/Reject) that drive a target-met early stop, and a Devil's Advocate concession-threshold guard that blocks acceptance on unresolved critical findings. Maintains a worklog and snapshots each iteration so revert is real, not symbolic. TRIGGER when the orchestrator delegates Step 5 or when the user asks to "refine the draft", "iterate on the paper", or "run peer review on this paper".
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 19.3 KB |
| references/ai-failure-modes.md | markdown | 813 B |
| references/claim-evidence-map.md | markdown | 3.1 KB |
| references/da-reviewer.md | markdown | 3.9 KB |
| references/halt-rules.md | markdown | 6.1 KB |
| references/prompt.md | markdown | 5.7 KB |
| references/reverse-outline.md | markdown | 3.0 KB |
| references/reviewer-rubric.md | markdown | 6.8 KB |
| references/safe-revision-rules.md | markdown | 4.8 KB |
| references/writing-quality-check.md | markdown | 720 B |
| scripts/apply_worklog.py | script | 3.1 KB |
| scripts/concession_guard.py | script | 7.5 KB |
| scripts/decision_band.py | script | 3.6 KB |
| scripts/reverse_outline.py | script | 10.3 KB |
| scripts/score_delta.py | script | 7.2 KB |
| scripts/score_trajectory.py | script | 8.6 KB |
| scripts/snapshot.py | script | 1.6 KB |
| scripts/test_reverse_outline.py | script | 5.7 KB |
| scripts/update_critique_memory.py | script | 11.1 KB |
references/reverse-outline.md
View on GitHub# Reverse Outlining
A reverse outline is the paper's argument with all the prose removed: one line
per paragraph — its topic sentence — read in order. Sentence-level review
cannot find what this finds. A paper can be locally excellent everywhere and
still have no argument, and the only way to see that is to stop reading the
sentences.
The generated outline is the reviewer's input for the **Logical Flow** axis of
`references/reviewer-rubric.md`.
## Running it
```bash
python skills/content-refinement-agent/scripts/reverse_outline.py \
--paper workspace/drafts/paper.tex \
--out workspace/reverse_outline.md \
--json workspace/reverse_outline.json
```
Exit 0 always, unless `--strict` is passed (then exit 1 when any paragraph
carries a flag). Default advisory mode is correct for the loop: the flags are
prompts for judgment, not defects.
## What the flags mean
| Flag | Heuristic | What it usually indicates |
|---|---|---|
| `no-topic-sentence` | Opening sentence is under six words, or opens on a connective (*However*, *Moreover*, *Therefore*) | The message lives further down the paragraph. Reviewers skimming topic sentences miss it entirely. |
| `overlong` | More than 8 sentences or 220 words | Two messages sharing a paragraph. Split at the pivot. |
| `multi-pivot` | Two or more contrastive turns (*however*, *in contrast*, *on the other hand*) | Each pivot changes direction; two changes of direction is two paragraphs. |
| `orphan` | Single sentence, under 60 words | Belongs to a neighbouring paragraph, or is a heading written as prose. |
| `citation-dump` | More citations than sentences | Related Work listing papers instead of positioning against them. |
Run-in bold headings (`\textbf{Policy engine.} The engine evaluates...`) are
merged into the sentence that follows, so the convention does not register as
a missing topic sentence.
## Reading the outline
Read only the numbered topic sentences of a section, in order, and ask:
1. Does the sequence make an argument, or is it a list of related facts?
2. Does each topic sentence follow from the previous one — cause, contrast,
consequence, refinement, or example?
3. Can each topic sentence be mapped to the section's thesis? A paragraph that
maps to nothing gets cut, not rewritten.
4. Is any paragraph's actual message different from its topic sentence? That
is the paragraph to fix first.
Structural findings go into the revision agenda as *reorder / merge / split /
cut* instructions. Sentence-level rewriting cannot fix a sequencing problem,
and iterations spent polishing a misordered section are iterations the halt
rules count against the budget.
## Provenance
The reverse-outlining practice and the one-paragraph-one-message rule follow
[Master-cai/Research-Paper-Writing-Skills](https://github.com/Master-cai/Research-Paper-Writing-Skills)
(MIT). The flag heuristics and the script are PaperOrchestra's. See also
`skills/shared/section_rhetoric.md` for the per-section paragraph-role
templates the outline is checked against.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |