---
name: a-attia/research-paper-writing
source: https://app.decimal.ai/s/a-attia-research-paper-writing@1/SKILL.md
source_sha256: 425626985204
---

# Research Paper Writing

## Overview

Use this skill to rewrite a research paper into a reviewer-friendly, high-clarity draft.
Prioritize first-impression quality (figures/tables/layout), logical flow, and evidence-backed claims.

## Core Workflow

1. Clarify the paper story before sentence-level edits.
2. Use section-specific guidance in `references/`.
3. Rewrite paragraph-by-paragraph with one message per paragraph.
4. Run reverse outlining after writing each section.
5. Check every major claim in Abstract/Introduction against experimental evidence.
6. Run final-paper adversarial review with `references/paper-review.md`.

## Global Principles

1. Keep one paragraph for one message only.
2. State the paragraph message in the first sentence.
3. Make nouns self-contained; define new terms before reusing them.
4. Maintain sentence-to-sentence flow (cause, contrast, consequence, or refinement).
5. Iterate with adversarial self-review: read as a skeptical reviewer.
6. Treat visual quality as core content, not decoration.
7. Use a clean teaser and pipeline figure.
8. Use readable, minimal-ink tables.
9. Keep formatting consistent and tidy.

## Paragraph Clarity Check (Important)

Use this quick test whenever the user asks whether a paragraph "flows" or is clear.

1. Read as an external reader:
   - Does this paragraph have one explicit message?
   - Does the first sentence state what this paragraph will do?
   - Are all key nouns/terms readable without hidden context?
   - Does each sentence connect to the previous one with a clear relation (cause, contrast, consequence, refinement, example)?
2. Run reverse outlining for the current section:
   - Write down thesis/main claim.
   - Write down each paragraph topic sentence.
   - Write down the evidence/explanation points under each paragraph.
   - Check mapping: topic sentence -> thesis, and evidence -> topic sentence.
   - Revise or remove any paragraph that cannot be mapped cleanly.
3. If flow is still weak, add temporary section headers and explicit transition phrases during revision, then remove unnecessary headers before finalizing.

Source reference for this check:

- `references/does-my-writing-flow-source.md`

## Section Guides

Load only the needed section file:

- Introduction: `references/introduction.md`
- Abstract: `references/abstract.md`
- Related Work: `references/related-work.md`
- Method: `references/method.md`
- Experiments: `references/experiments.md`
- Conclusion: `references/conclusion.md`
- Paper review (Paper Review): `references/paper-review.md`
- Paragraph clarity source: `references/does-my-writing-flow-source.md`
- Example bank index: `references/examples/index.md`

## Paper Review Core Points

Use `references/paper-review.md` for the full checklist and workflow.

1. Add an end-of-draft self-review question list in five dimensions:
   - contribution,
   - writing clarity,
   - experimental strength,
   - evaluation completeness,
   - method design soundness.
2. Treat claim-evidence alignment as a hard constraint, especially for Abstract and Introduction.
3. Perform adversarial writing: review as a skeptical reviewer and resolve every high-risk question.
4. Revise until major rejection risks are explicitly addressed.

## Execution Rules

1. Build a mini-outline before drafting prose.
2. For each subsection, explicitly include motivation, design, and technical advantage when applicable.
3. Avoid writing style that looks like incremental patching of a naive baseline.
4. Keep terminology stable across the full paper.
5. If a claim cannot be supported by results, weaken or remove the claim.
6. Before finalizing, append and answer a five-dimension self-review question list, then revise the paper based on unresolved items.
7. Do not load all section references (Introduction/Abstract/Related Work/Method/Experiments/Conclusion) at once; load only the specific section guide needed for the current edit target.

## Output Contract

When asked to rewrite or draft sections, return:

1. A compact section outline (3-7 bullets).
2. Revised paragraphs with explicit paragraph roles (opening/challenge/method/advantage/evidence/limitation).
3. A short self-review checklist covering clarity, flow, terminology consistency, unsupported claims, and missing evidence.
4. A claim-evidence map for each major claim in the revised text using `Claim: ... | Evidence: ... | Status: supported/needs evidence`.

## Adjacent human-facing documents

This skill governs the **published paper draft** itself (Abstract,
Introduction, Related Work, Method, Experiments, Conclusion). When
the work also requires producing or revising **meta-documents** that
support the paper -- for example:

- updates to the project's `PLAN.md`,
- per-section research notes (`notes/section_<N>.md`),
- per-component implementation plans (`notes/impl_<component>.md`),
- the project's `README.md`,
- a reviewer-response draft,

those documents have a different audience (the user, co-authors,
reviewers) and a different style budget than the paper itself. Load
`~/.scicomp-research-skills/skills/human-facing-doc-authoring/SKILL.md`
for the conventions and per-doc-type structural skeletons. Use BOTH
skills together: paper-writing for the paper draft, human-facing for
any meta-doc.

## Resource discipline for paper-writing sessions

A paper-writing session typically iterates across multiple sections,
re-reads many survey notes, may re-grep the paper draft repeatedly,
and often spans multiple sessions before a section is finalised.
Whenever the session is going to be heavy (more than ~5 file reads,
multiple section drafts, or a span across multiple sittings), load
`~/.scicomp-research-skills/skills/agent-resource-discipline/SKILL.md`
at session start. In particular:

- `references/persistent-memory.md` -- the first-/last-action
  protocol that updates `notes/section_<N>.md` and `PLAN.md` status
  fields so the next session resumes cheaply.
- `references/context-window-budget.md` -- the rule that this skill's
  Execution Rule #7 ("do not load all section references at once")
  generalises to: do not load all survey notes at once, do not load
  the full `.txt` extraction of every cited paper -- target-grep
  instead.

Both skills compose: paper-writing for *what to write*; agent-resource-
discipline for *what to load while writing*.

---

## Note on this skill's references/ files

The references files under `references/` (abstract.md, conclusion.md,
experiments.md, introduction.md, method.md, paper-review.md,
related-work.md, examples/) are **vendored from the upstream
[Master-cai/Research-Paper-Writing-Skills](https://github.com/Master-cai/Research-Paper-Writing-Skills)
repository at commit 9ee5edd** (see ATTRIBUTION.md). They are
deliberately preserved without per-file date-stamp footers -- our
universal "every plan-of-record-style document ends with a date-stamp
footer" convention (root AGENTS.md Section 6) does not apply to
upstream-imported reference content; modifying the upstream files to
add footers would create false revision history.

When upstream evolves the references files, we may selectively
cherry-pick changes (per ATTRIBUTION.md "Pulling updates from
upstream"). When we substantially modify a reference file, we will
add a `*Revised YYYY-MM-DD by A. Attia: <note>.*` footer to that
specific file at that point. Until then the upstream provenance is
authoritative.

---

*Revised 2026-05-13: added "Adjacent human-facing documents" section
pointing at the human-facing-doc-authoring skill for meta-docs
(PLAN.md, section/impl notes, README, rebuttal) that this skill does
not directly govern. Revised 2026-05-13: added "Resource discipline
for paper-writing sessions" section pointing at the
agent-resource-discipline skill for the cross-cutting context-window /
persistent-memory protocol that complements this skill's Execution
Rule #7. Revised 2026-05-14 (post-fresh-audit): documented the
deliberate exception from the universal date-stamp-footer convention
for upstream-vendored references files (the eight files under
references/ that were imported from Master-cai upstream and have not
been substantially modified).*