write-academic-report

# Academic Report Writer: 40-100+ Page Thesis/FYP with Parallel Agents Turn a research repository into a **publication-quality LaTeX thesis** in 2-4 hours instead of 8-12 — using a **3-wave parallel agent pipeline** purpose-built for academic reports. **What this skill does:** You point it at your research repo (code + experiment results). It launches parallel agents to extract data, write chapters simultaneously, then assembles and compiles a complete LaTeX report with proper cross-references, figures, and bibliography. **Validated:** 86-page FYP report, 6 chapters + 3 appendices + 15 figures, produced in ~6 hours. Writing philosophy inherited from [ml-paper-writing](https://github.com/Orchestra-Research/ml-paper-writing) (Nanda, Farquhar, Gopen & Swan, Lipton, Steinhardt, Perez). --- ## CRITICAL: Never Hallucinate Citations **This rule is inherited from ml-paper-writing and is non-negotiable.** ### The Problem (Backed by Data) | Statistic | Source | |-----------|--------| | **6-55%** of AI-generated citations are fabricated | Multiple studies (varies by model/domain) | | **100+** hallucinated refs in NeurIPS 2025 accepted papers | GPTZero analysis, Jan 2026 | | **50+** hallucinated refs in ICLR 2026 submissions | GPTZero analysis, Feb 2026 | | Only **26.5%** of AI-generated references are entirely accurate | Paper-Checker 2026 survey | | **206+** legal sanctions for AI-hallucinated citations in courts | As of July 2025 | | **3 types**: fully fabricated, chimeric (blended), modified real | CheckIfExist (arXiv 2602.15871) | Universities increasingly treat fake citations as **academic misconduct** — failed assignments, course failure, or expulsion. ### The Rule **NEVER generate BibTeX entries from memory. ALWAYS fetch programmatically.** ``` IF you cannot programmatically fetch a citation: → Mark it as [CITATION NEEDED] or [PLACEHOLDER - VERIFY] → Tell the author explicitly → NEVER invent a plausible-sounding reference ``` ### Automated Verification: citation_checker.py After writing, **always run the citation checker** before submission: ```bash # Check a single .bib file python scripts/citation_checker.py references.bib # Check all .bib files in a report directory python scripts/citation_checker.py path/to/report/ # JSON output (for CI pipelines) python scripts/citation_checker.py references.bib --json ``` The checker uses a **cascading 3-source verification pipeline**: ``` CrossRef (140M+ DOIs) → Semantic Scholar (200M+ papers) → OpenAlex (240M+ works) ``` For each citation it: 1. Searches by DOI (if available) or title 2. Computes title similarity + author overlap 3. Flags red flags (invalid DOI, generic title, missing fields, chimeric blends) 4. Reports: **verified** (2+ sources), **suspicious** (1 source), or **not found** (likely hallucinated) **Red flag detection catches:** - Fully fabricated citations (no match in any database) - Chimeric hallucinations (title matches but authors don't) - Invalid DOI formats - Suspiciously generic titles common in AI output - Missing critical fields (authors, year) - Future publication years See [references/citation-workflow.md](references/citation-workflow.md) for the full API documentation and Python CitationManager class. --- ## When to Use This Skill | Scenario | Use This Skill | Use ml-paper-writing Instead | |----------|:-:|:-:| | FYP / Final Year Project report | Yes | | | MSc / PhD dissertation | Yes | | | Technical report (20+ pages) | Yes | | | Conference paper (8-12 pages) | | Yes | | Workshop paper (4-6 pages) | | Yes | **Key difference**: This skill orchestrates **parallel subagents** for long documents. Conference papers are short enough to write sequentially. --- ## Core Architecture: 3-Wave Pipeline ``` Wave 0: DATA PREPARATION Wave 1: CHAPTER WRITING Wave 2: ASSEMBLY (5-6 parallel agents) (3-4 parallel agents) (1-2 sequential agents) ┌─ Agent 0A: Data consolidation ┌─ Agent 1: Template + Ch1-2 ┌─ Agent 6: Merge + cross-ref ├─ Agent 0B: Codebase analysis ├─ Agent 2: Ch3 (core work) └─ Agent 7: Compile + review ├─ Agent 0C: System analysis ├─ Agent 3: Ch4-5 (results) ├─ Agent 0D: Experiment history └─ Agent 4: Ch6 + Appendices ├─ Agent 0E: Statistics └─ Agent 0F: Figure generation ``` **Why waves?** Data must exist before prose. Prose must exist before assembly. Violating this order produces agents that hallucinate numbers or write without evidence. --- ## Wave 0: Data Preparation (Before Writing) **Goal**: Produce all data artifacts that chapter-writing agents will reference. Every claim in the report must trace back to a Wave 0 artifact. ### What Wave 0 Agents Produce | Agent | Input | Output | Purpose | |-------|-------|--------|---------| | **0A: Data Consolidation** | Raw result files (JSON, CSV) | `data/final_results.json` | Single source of truth for all numbers | | **0B: Codebase Analysis** | Source code | `data/codebase_analysis.md` | Module map, LOC, complexity, key snippets | | **0C: System Analysis** | Architecture, pipeline code | `data/system_analysis.md` | How components connect, data flow | | **0D: Experiment History** | All experiment logs | `data/experiment_history.md` | Timeline, what changed, why | | **0E: Statistics** | Result files | `data/statistics.md` | Aggregate stats, distributions | | **0F: Figure Generation** | Data artifacts + style config | `figures/*.pdf` + `figures/*.png` | All publication-quality figures | ### Agent 0F: Figure Pipeline (Special) Figures deserve a dedicated agent because: 1. They must be **consistent** (same color palette, font sizes, style) 2. They must be **vector** (PDF for LaTeX \includegraphics) 3. They must be **colorblind-safe** (Okabe-Ito or Paul Tol palette) 4. They must be **self-contained** (captions tell the full story) ```python # Recommended figure style import matplotlib.pyplot as plt import matplotlib matplotlib.rcParams.update({ 'font.size': 11, 'font.family': 'serif', 'axes.labelsize': 12, 'axes.titlesize': 13, 'xtick.labelsize': 10, 'ytick.labelsize': 10, 'legend.fontsize': 10, 'figure.figsize': (6.5, 4), 'savefig.dpi': 300, 'savefig.bbox': 'tight', }) # Colorblind-safe palette (Okabe-Ito) COLORS = ['#E69F00', '#56B4E9', '#009E73', '#F0E442', '#0072B2', '#D55E00', '#CC79A7', '#000000'] ``` **Output both formats**: `figure_name.pdf` (for LaTeX) + `figure_name.png` (for preview). ### Wave 0 Completion Gate **Do NOT proceed to Wave 1 until:** - [ ] All data files exist and are non-empty - [ ] All figures compile (PDF + PNG) - [ ] Numbers in `final_results.json` match known ground truth - [ ] Each agent's output has been spot-checked --- ## Wave 1: Chapter Writing (Parallel, After Wave 0) ### Chapter Dependency Graph ``` Independent (can parallelize): Ch1 (Introduction) ←→ Ch2 (Literature Review) [no dependency] Ch3 (System/Methods) [needs 0B, 0C] Ch6 (Conclusion) [needs 0A summary only] Sequential (must wait): Ch4 (Experimental Setup) → Ch5 (Results) [Ch5 needs Ch4's definitions] Ch5 needs: 0A (data), 0D (history), 0E (stats), 0F (figures) ``` ### Recommended Agent Assignment | Agent | Chapters | Depends On | Approx Pages | |-------|----------|------------|:---:| | **Agent 1** | Template + Front matter + Ch1 + Ch2 | Plan only | 15-20 | | **Agent 2** | Ch3 (System Design) | 0B, 0C | 12-18 | | **Agent 3** | Ch4 + Ch5 (Setup + Results) | 0A, 0D, 0E, 0F | 15-25 | | **Agent 4** | Ch6 + Appendices | 0A (summary) | 5-10 | ### Writing Philosophy (Inherited) These principles from ml-paper-writing apply to every chapter: **The Narrative Principle** (Nanda): Your report tells one story. Every chapter advances that story. If a section doesn't connect to the core contribution, cut it. **Sentence-Level Clarity** (Gopen & Swan): | Principle | Rule | Mnemonic | |-----------|------|----------| | Subject-verb proximity | Keep subject and verb close | "Don't interrupt yourself" | | Stress position | Emphasis at sentence end | "Save the best for last" | | Topic position | Context at sentence start | "First things first" | | Old before new | Familiar then unfamiliar | "Build on known ground" | | One unit, one function | Each paragraph = one point | "One idea per container" | | Action in verb | Use verbs, not nominalizations | "Verbs do, nouns sit" | | Context before new | Explain before presenting | "Set the stage first" | **Word Choice** (Lipton, Steinhardt): - Be specific: "accuracy" not "performance" - Eliminate hedging: drop "may" and "can" unless genuinely uncertain - Consistent terminology: pick one term per concept, stick with it - Delete filler: "actually," "very," "basically," "essentially" **Micro-Level Tips** (Perez): - Minimize pronouns: "This result shows..." not "This shows..." - Position verbs early in sentences - Active voice always: "We show..." not "It is shown..." - One idea per sentence ### Thesis-Specific Adaptations (Beyond ml-paper-writing) | Conference Paper | Thesis/Report | |-----------------|---------------| | 1-1.5 page intro | 3-5 page intro with motivation + scope | | Related Work section | Full Literature Review chapter | | 8-12 pages total | 40-100+ pages total | | 5-sentence abstract | 250-400 word abstract | | Contribution bullets | Objectives & scope section | | No project timeline | Gantt chart / project schedule | | No appendices (usually) | 2-5 appendices with supplementary material | ### Chapter Templates #### Chapter 1: Introduction (3-5 pages) ```latex \chapter{Introduction} \section{Background} % 1-2 pages: Establish the problem domain % Start specific, not generic. No "AI has revolutionized..." \section{Motivation} % 0.5-1 page: Why this problem matters NOW % Use the "map analogy" or similar concrete framing \section{Objectives and Scope} % 0.5 page: Numbered list of objectives % Explicitly state what is IN and OUT of scope \section{Project Schedule} % Gantt chart figure (generated in Wave 0) \section{Report Organization} % Brief roadmap of remaining chapters ``` #### Chapter 2: Literature Review (8-15 pages) ```latex \chapter{Literature Review} % Organize METHODOLOGICALLY, not paper-by-paper % Group: "One line of work uses X [refs] whereas we use Y because..." \section{Topic Area 1} \section{Topic Area 2} \section{Topic Area 3} \section{Research Gap and Our Position} % Explicitly state what's missing and how you fill it % Include positioning figure/table if helpful ``` #### Chapter 3: System Design / Methodology (10-18 pages) ```latex \chapter{System Design and Implementation} \section{System Architecture} % Architecture diagram (FIGURE — from Wave 0) \section{Core Component 1} % Code listings where relevant (use lstlisting or minted) \section{Core Component 2} \section{Technology Stack} % TABLE: libraries, versions, purpose ``` #### Chapter 4: Experimental Setup (5-8 pages) ```latex \chapter{Experimental Setup} \section{Dataset / Data Collection} \section{Evaluation Methodology} \section{Baselines and Conditions} \section{Statistical Methods} % TABLE: which test, why, assumptions ``` #### Chapter 5: Results and Analysis (8-15 pages) ```latex \chapter{Results and Analysis} % For EACH result, explicitly state: % 1. What claim it supports % 2. The specific numbers % 3. Statistical significance \section{Main Results} % FIGURE + TABLE for primary ablation/comparison \section{Detailed Analysis 1} \section{Detailed Analysis 2} \section{Discussion} % What worked, what didn't, WHY ``` #### Chapter 6: Conclusion (3-5 pages) ```latex \chapter{Conclusion and Future Work} \section{Summary of Contributions} % 3-5 numbered contributions, each 2-3 sentences \section{Limitations} % HONEST assessment. Claude undersells weaknesses by default. % Explicitly prompt: "What are the real limitations?" % Pre-empt criticisms. Honesty builds trust. \section{Future Work} % 2-4 concrete, actionable directions % Not vague "further research" — specific next steps ``` ### Limitations Section Guidance (Critical) **Claude has a documented tendency to understate limitations.** When writing the limitations section: 1. Ask yourself: "What would a skeptical examiner criticize?" 2. List ALL weaknesses, not just minor ones 3. Quantify where possible: "Judge variance is ~5pp between re-judgings" 4. Explain WHY the limitation doesn't invalidate the core contribution 5. Distinguish between "fundamental limitation" and "scope limitation" --- ## Wave 2: Assembly & Compilation ### Step 1: Merge Chapters Use `\input{}` in `main.tex` to include chapter files: ```latex \documentclass[12pt,a4paper]{report} \input{preamble} \begin{document} \input{front_matter} \tableofcontents \listoffigures \listoftables \input{chapters/ch1_introduction} \input{chapters/ch2_literature_review} \input{chapters/ch3_system_design}