Phy Write Academic Report

SKILL.md

---
name: write-academic-report
description: "Write 40-100+ page academic reports (FYP, thesis, dissertation) with parallel Claude Code subagents. 3-wave pipeline: Wave 0 extracts data from your research repo, Wave 1 writes chapters in parallel (3-4x faster), Wave 2 compiles LaTeX with automated cross-reference auditing. Inherits academic writing standards from Nanda, Gopen & Swan, Lipton."
version: 1.0.3
author: Canlah AI
license: MIT
tags: [Academic Report, Thesis Writing, FYP, Dissertation, LaTeX, Parallel Agents, Claude Code Skill]
dependencies: [tectonic]
homepage: https://canlah.ai
---

# 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}
\input{chapters/ch4_experimental_setup}
\input{chapters/ch5_results}
\input{chapters/ch6_conclusion}

\bibliographystyle{plain}
\bibliography{references}

\appendix
\input{appendices/appendix_a}
\input{appendices/appendix_b}
\end{document}
```

### Step 2: Cross-Reference Audit (Mandatory)

With parallel agents writing chapters independently, **duplicate labels are inevitable**.

Run the automated audit script:

```bash
python scripts/cross_ref_audit.py report_dir/
```

This checks:
- Duplicate `\label{}` definitions
- Undefined `\ref{}` and `\cite{}` references
- Orphaned labels (defined but never referenced)
- Figure/table numbering consistency
- BibTeX key duplicates

See [scripts/cross_ref_audit.py](scripts/cross_ref_audit.py) for the full script.

### Step 3: Compile with Tectonic

**Tectonic** is strongly recommended over BasicTeX/TeX Live for local compilation:

```bash
# Install (macOS)
brew install tectonic

# Compile (handles all passes automatically)
tectonic main.tex

# Or with verbose output
tectonic -X compile main.tex
```

**Why Tectonic?**
- No `sudo`, no `tlmgr install`
- Handles BibTeX + multiple passes automatically
- Downloads packages on-demand
- Single binary, no distribution management

See [references/compilation-guide.md](references/compilation-guide.md) for alternatives and troubleshooting.

### Step 4: Quality Review

Final quality checks:

```
Post-Compilation Checklist:
- [ ] No undefined references (\ref, \cite)
- [ ] No duplicate labels
- [ ] All figures render at correct size
- [ ] Table of Contents is accurate
- [ ] List of Figures / Tables is complete
- [ ] Page numbers are correct
- [ ] Bibliography entries are complete
- [ ] Appendices are properly lettered
- [ ] No overfull/underfull hbox warnings (major ones)
- [ ] Consistent formatting across all chapters
```

---

## Tables and Figures

### Tables

Use `booktabs` for professional tables:

```latex
\usepackage{booktabs}
\begin{table}[t]
\centering
\caption{Comparison of conditions. Best results in \textbf{bold}.}
\label{tab:main_results}
\begin{tabular}{lcc}
\toprule
Condition & Success Rate $\uparrow$ & p-value \\
\midrule
Baseline & 25.6\% & --- \\
Summary & 27.8\% & 0.839 \\
\textbf{URL} & \textbf{50.0\%} & $<$0.001 \\
\textbf{Tools} & \textbf{50.0\%} & $<$0.001 \\
\bottomrule
\end{tabular}
\end{table}
```

**Rules:**
- Bold best value per metric
- Include direction symbols (higher/lower is better)
- Right-align numerical columns
- Consistent decimal precision
- Caption ABOVE table (convention for tables)

### Figures

- **Vector graphics** (PDF) for all plots and diagrams
- **Raster** (PNG 300+ DPI) only for screenshots/photographs
- **Colorblind-safe palettes** (Okabe-Ito recommended)
- **No title inside figure** — the caption serves this function
- **Self-contained captions** — reader should understand without main text
- Caption BELOW figure (convention for figures)

```latex
\begin{figure}[t]
\centering
\includegraphics[width=0.85\textwidth]{figures/architecture.pdf}
\caption{System architecture showing the five core modules.
         Arrows indicate data flow from browser automation (left)
         through state abstraction to the output graph (right).}
\label{fig:architecture}
\end{figure}
```

---

## University Template Handling

### Generic Thesis Template

A minimal, clean university thesis template is provided in `templates/university-thesis/`. It includes:
- A4 paper, 12pt, report class
- Front matter (title page, abstract, acknowledgements, TOC)
- Chapter structure with `\input{}`
- Bibliography with natbib
- Appendix support

### Adapting to Your University

Most universities provide their own LaTeX template. To adapt:

1. **Start from your university's template** (not ours)
2. Copy the `\input{}` chapter structure from our template
3. Keep university style files untouched
4. Add only necessary packages

| University Feature | Where to Adapt |
|-------------------|----------------|
| Title page format | `front_matter.tex` — follow university spec exactly |
| Margin requirements | `preamble.tex` — use university's geometry settings |
| Font requirements | `preamble.tex` — usually Times New Roman or Computer Modern |
| Citation style | `\bibliographystyle{}` — university specifies (Harvard, APA, IEEE, etc.) |
| Appendix format | Check if university wants lettered (A, B, C) or numbered |

---

## Workflow: End-to-End

### Step-by-Step Execution

```
1. UNDERSTAND THE PROJECT
   - Read the codebase, results, existing docs
   - Identify the core contribution

2. PLAN THE REPORT
   - Define chapter structure
   - Map: which data → which chapter
   - Identify figures needed
   - Create the execution plan

3. WAVE 0: DATA PREPARATION
   - Launch 5-6 parallel agents
   - Wait for ALL to complete
   - Verify outputs (spot-check numbers)

4. WAVE 1: CHAPTER WRITING
   - Launch 3-4 parallel agents
   - Each agent gets: chapter template + relevant Wave 0 data
   - Independent chapters can run in parallel

5. WAVE 2: ASSEMBLY
   - Merge chapters into main.tex
   - Run cross_ref_audit.py
   - Fix duplicate labels, undefined refs
   - Compile with tectonic
   - Quality review

6. ITERATE
   - Author reviews output
   - Targeted revisions (specific chapters/sections)
   - Re-compile and verify
```

### Time Estimates (Based on Validated Run)

| Wave | Agents | Typical Duration | Notes |
|------|:------:|:----------------:|-------|
| Wave 0 | 5-6 | 30-60 min | Depends on codebase size |
| Wave 1 | 3-4 | 60-90 min | Longest wave |
| Wave 2 | 1-2 | 20-40 min | Mostly automated |
| **Total** | | **2-4 hours** | For ~80 page report |

Without parallel agents, the same report takes 8-12 hours.

---

## Key Lessons (From Production Use)

1. **Data before prose**: Agents write poorly without concrete numbers. Wave 0 is essential.
2. **Tectonic over BasicTeX**: `brew install tectonic` — no sudo, handles packages automatically.
3. **Cross-ref audit is mandatory**: Parallel agents create duplicate labels. Automated script catches them.
4. **Figure pipeline separate**: Generate all figures first, reference later. Don't embed matplotlib in chapter agents.
5. **Honest limitations**: Explicitly prompt for limitations — Claude undersells weaknesses by default.
6. **zsh gotcha**: `grep '!'` breaks in zsh due to history expansion. Use Python scripts for pattern matching.
7. **Plan file as source of truth**: Write the full execution plan before launching any agents.
8. **Spot-check Wave 0**: Don't blindly pass data artifacts to writing agents. Verify key numbers.

---

## Common Issues and Solutions

| Issue | Solution |
|-------|----------|
| Duplicate `\label{}` across chapters | Run `cross_ref_audit.py`, rename with chapter prefix |
| Missing package in tectonic | Tectonic auto-downloads; if stuck, try `tectonic -X compile` |
| Figures too large / overlapping text | Use `[width=0.85\textwidth]` and `[htbp]` float placement |
| BibTeX not resolving | Run tectonic twice, or check `.bib` file syntax |
| Inconsistent notation across chapters | Define macros in `preamble.tex`, shared across all `\input{}` files |
| Agent writes without evidence | Wave 0 completion gate — never skip data preparation |
| Abstract too long for university | Keep to word limit; conference 5-sentence formula still works |
| Examiner criticizes missing limitations | Use the explicit limitations prompting strategy |

---

## References

### Inherited from ml-paper-writing

| Document | Contents |
|----------|----------|
| [references/writing-guide.md](references/writing-guide.md) | Gopen & Swan 7 principles, micro-tips, word choice |
| [references/citation-workflow.md](references/citation-workflow.md) | Citation APIs, Python code, BibTeX management |

### New for write-report

| Document | Contents |
|----------|----------|
| [references/compilation-guide.md](references/compilation-guide.md) | Tectonic, latexmk, cross-ref audit, local compilation |
| [references/parallel-pipeline.md](references/parallel-pipeline.md) | Wave architecture, agent orchestration, dependency graph |
| [scripts/cross_ref_audit.py](scripts/cross_ref_audit.py) | Automated cross-reference and duplicate label checker |
| [templates/university-thesis/](templates/university-thesis/) | Generic university thesis LaTeX template |

---

## Author

**[Canlah AI](https://canlah.ai)** — Run performance marketing without breaking your brand.

- GitHub: [github.com/PHY041](https://github.com/PHY041)
- All Skills: [clawhub.ai/PHY041](https://clawhub.ai/PHY041)