# Refactor Structure > Diagnoses and fixes a paper's argument architecture and narrative flow, independent of any venue. Checks whether the story is built in the right order, whether each section does its job, whether the intro promises what the body delivers, and whether the contribution -> evidence -> conclusion arc holds — then produces a restructuring plan (move / merge / split / cut sections) the author approves B… - **Type:** Skill - **Install:** `agentstack add skill-shaishavmaisuria-research-paper-lifecycle-skills-refactor-structure` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [ShaishavMaisuria](https://agentstack.voostack.com/s/shaishavmaisuria) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** Apache-2.0 - **Upstream author:** [ShaishavMaisuria](https://github.com/ShaishavMaisuria) - **Source:** https://github.com/ShaishavMaisuria/research-paper-lifecycle-skills/tree/main/skills/refactor-structure - **Website:** https://shaishavmaisuria.github.io/research-paper-lifecycle-skills/ ## Install ```sh agentstack add skill-shaishavmaisuria-research-paper-lifecycle-skills-refactor-structure ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Refactor Structure Fix the *architecture* of the argument, not its words. A paper can be grammatical, on-template, and within the page limit and still fail because the story is assembled in the wrong order, a section doesn't do its job, the introduction promises things the body never delivers, or the conclusion outruns the evidence. This skill diagnoses those problems and produces a **restructuring plan** — move / merge / split / cut, with the reasoning for each — that the author approves before a single section is rewritten. It plans and (on approval) executes the moves. It does not reword sentences (that is `polish-prose`) and it does not fit the paper to a venue's rules (that is `tailor-to-venue`). ## When to use - "The structure feels off" / "it doesn't flow" / "reorganize my paper". - Reviewers said: hard to follow, disorganized, the story is unclear, the contribution is buried, related work is in the wrong place, a section doesn't belong. - The intro over-promises (claims a proof / user study / ablation the body doesn't contain), or the conclusion claims something never evidenced. - Redundant sections (two Background sections), or one section doing two jobs (Results carrying Threats-to-Validity). Not for: sentence wording / de-AI-ifying (`polish-prose`), page limits / templates / track fit (`tailor-to-venue`), the Related Work section's *content* (`draft-related-work`), or whether the citations are real (`verify-citations`). ## Inputs - The draft: main `.tex` file (the script follows `\input`/`\include`). - Optional: the paper's intended contribution list and target paper type, from `.paper-memory/profile.yml` if present (a theory paper and an empirical paper have different expected arcs). If absent, ask the author for the one-sentence claim and the contribution bullets. ## Process ### 1. Read the structure, don't re-read the paper Run the bundled extractor to get the skeleton on one screen: ``` python3 skills/refactor-structure/scripts/outline_extract.py ``` It prints the section/subsection tree, each unit's **first sentence** (the topic sentence — where a well-built section announces its job), and per-unit signals (word count, citations, whether it carries floats/equations/lists, units that open with *no* topic sentence). Use `--md` to drop the skeleton into the plan, `--json` to drive your own analysis, `--no-inputs` to run on a single section file. Exit 2 on bad input. This is a **structure map, not a verdict** — it tells you what is where; the diagnosis below is the judgment. ### 2. Establish the intended arc Before judging order, know what the paper is *trying* to argue. Read the contribution bullets and the abstract's claim. Write down, in one line each: the problem, the claimed contribution(s), the evidence that should back each contribution, and the conclusion each contribution licenses. This is the spine every later check measures against. ### 3. Diagnose against the architecture checklist Work through [references/architecture-checklist.md](references/architecture-checklist.md), which covers the seven failure modes (wrong order, a section not doing its job, gaps, redundancy, misplaced content, intro/body mismatch, a broken contribution -> evidence -> conclusion arc) and the standard section arcs by paper type. The two highest-value, most objective checks: - **Promise-vs-delivery.** For every contribution bullet and every "we show / we prove / we evaluate" in the intro, find the section that delivers it. A promised proof, user study, or ablation with no home section is a gap the reader (and reviewer) will hold against the paper. Conversely, list any major result section the intro never advertised. - **Conclusion-vs-evidence.** Every claim in the conclusion must trace back to a result in the body. A conclusion that introduces a *new* claim (e.g. "scales to any number of nodes" with no scaling experiment) is an arc break — flag it as either "remove the claim" or "the body is missing the experiment that would support it." See [references/diagnosis-patterns.md](references/diagnosis-patterns.md) for how each symptom maps to a concrete remedy (move / merge / split / cut) and the ripple effects to check (forward references, "as we show in Section~X" pointers, a cut section's surviving citations). ### 4. Write the restructuring plan (the author approves it before any edit) Produce, do not apply. Write `paper-workspace/writing/restructuring-plan.md` with: 1. **Current skeleton** — the `--md` outline from step 1. 2. **Intended arc** — the spine from step 2. 3. **Diagnosis** — findings grouped by failure mode, each with: what's wrong, why it hurts the argument, severity (blocks comprehension / weakens it / minor), and the proposed remedy. 4. **Proposed skeleton** — the section tree *after* the plan, so the author sees the new order at a glance. 5. **Ordered move list** — each move/merge/split/cut as a discrete, reversible step with its ripple effects, sequenced so the document stays coherent between steps. Present the diagnosis with the cheaper path called out: often a reorder plus two merges fixes more than a rewrite. Where a symptom has more than one reading — *is* the user study missing, or just unlabeled? — show both and ask; never silently assume a section is absent when it might live in an `\input` file. ### 5. Execute on approval, one step at a time Only after the author signs off, apply the moves in order. After each structural change, re-run `outline_extract.py` to confirm the skeleton matches the proposed one, and fix the ripple effects the plan listed (cross-references, "see Section~X" pointers, a moved section's label). Moving prose is mechanical; do not silently reword it — flag any sentence that needs new connective tissue for the author (or hand it to `polish-prose`). A reference orphaned by a cut (a now-dangling `\cite`) routes through `verify-citations`; a claim left without evidence — e.g. the conclusion-vs-evidence break in step 3 — routes through `verify-claims` for a proper claim→evidence audit. Never invent a citation or a result to patch either. ## Output - A reviewable `paper-workspace/writing/restructuring-plan.md`: current skeleton -> intended arc -> diagnosis -> proposed skeleton -> ordered moves. - On approval, the applied moves with a re-extracted skeleton confirming the result and a ripple-effect checklist (cross-refs, pointers, labels). - The author decides every move; nothing is rewritten at sentence level here. ## Adapt to your discipline The failure modes are field-agnostic; the *expected arc* is not. [references/architecture-checklist.md](references/architecture-checklist.md) gives CS-paper arcs (systems / ML-empirical / theory). Fork it for your field: IMRaD for experimental science, a different placement of Related Work, a Methods-before-Results vs. interleaved convention, or essay-style argument structure in the humanities. ## Guardrails - **Plan before you touch the paper.** Diagnosis and the move list come first; the author approves before any section is moved, merged, split, or cut. - It restructures; it does not reword. Sentence-level edits are `polish-prose`; venue/track/page fit is `tailor-to-venue`. Do not silently rewrite moved prose — flag seams for the author. - Never fabricate a result, section, or citation to "fill a gap." A missing user study is reported as missing; the fix is to add the work or drop the promise, never to invent it. - Never delete content the author may want; a cut is a *proposal*, and cut text is preserved (note where it went) so it is recoverable. - Diagnosis is from reading the structure, not from a venue rule or memory; the extractor's output and the draft are ground truth. It never claims the restructure will get the paper accepted. - Never submit anything anywhere on the author's behalf. ## Relationship to other skills - `tailor-to-venue` — venue/track fit, page budget, template, blind level. Run *after* the argument is sound; structure-then-fit, not the reverse. - `polish-prose` — sentence-level wording, hedging, AI-tells. Run *after* the structure is settled, so you polish prose you're keeping. - `draft-related-work` — the *content* of the Related Work section; this skill only decides where that section sits and whether it does its job. - `verify-claims` — when a conclusion claim outruns the evidence (an arc break), this skill flags the structural break; `verify-claims` audits whether the claim is actually supported. `verify-citations` is the separate check that a `.bib` entry resolves (e.g. a reference orphaned by a cut). - `simulate-reviewers` / `assess-paper` — if a mock review flagged "hard to follow", this skill is the fix. ## Memory Uses the shared `.paper-memory/` convention in the user's paper directory (full spec: [`paper-memory-convention.md`](../paper-profile/references/paper-memory-convention.md)). - **At start:** read `profile.yml` (paper type sets the expected arc) and `lessons.md` — lead with any recurring structural habit already recorded (e.g. "you habitually bury Threats to Validity in Results") so you check for it first. - **At end:** append durable findings via `reflect-and-improve`'s `reflect_log.py append` in the shared format `- [YYYY-MM-DD] (refactor-structure | ) pattern -> recommendation`. A habit seen across drafts is `recurring`; a one-off is `this-paper`. Don't log routine single moves. - Create `.paper-memory/` on demand and offer to add it to the project `.gitignore`; it is local-only and never uploaded or copied into this repo. ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [ShaishavMaisuria](https://github.com/ShaishavMaisuria) - **Source:** [ShaishavMaisuria/research-paper-lifecycle-skills](https://github.com/ShaishavMaisuria/research-paper-lifecycle-skills) - **License:** Apache-2.0 - **Homepage:** https://shaishavmaisuria.github.io/research-paper-lifecycle-skills/ Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-shaishavmaisuria-research-paper-lifecycle-skills-refactor-structure - Seller: https://agentstack.voostack.com/s/shaishavmaisuria - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.