🎓 Write a thesis chapter, start to finish

Status: tutorial.

Written for a doctoral or master's student who wants a chapter of their own thesis drafted from their own library, and who has not used this pipeline before. Assumed: nothing. This page deliberately repeats what other documents also say, so that you can finish a chapter without leaving it. Not covered here: how retrieval ranks (RETRIEVAL.md) and why each prose rule exists (WRITING-STANDARDS.md).

Sister tutorials: a survey, a textbook chapter, a tutorial, a deep-research report.

🧭 Table of contents

• What makes this genre different
• What you will have at the end
• Before you start
• Step 1: the research question, the examiner, the slug
• Step 2: open the dossier
• Step 3: write an outline (optional, recommended)
• Step 4: ask for the chapter
• Step 5: gate, render, sidecar
• Step 6: put it in your thesis
• Step 7: read the review aids
• Step 8: change something
• When something goes wrong

⚖ What makes this genre different

The output is a LaTeX fragment, not a document: no \documentclass, no \begin{document}, no preamble. It is written to be \input into the thesis you already have, so your own template, numbering and bibliography stay in charge.

This has three deliberate consequences:

• Citations are \citep{...}/\citet{...}, not [@citekey]. The gate reads both, so the guarantee is unchanged.
• The fragment carries no References section. Your thesis has one thesis-wide bibliography, and a second one landing mid-chapter would compete with it.
• Figures are inline \inputs inside a hand-written figure float, because the fragment has to stay self-contained once it leaves this pipeline. The skill hands each figure it decides on to figure-drawer, which draws the TikZ file and its ASCII twin (FIGURE-DRAWER.md).

🎯 What you will have at the end

For a chapter you decide to call thesis/methods:

Path	What it is
content/drafts/thesis/methods.tex	the fragment: the canonical copy, the thing you \input
content/dossiers/thesis/methods/	scope, kept evidence, rejected candidates, every search run
content/rendered/thesis/methods.pdf	a standalone preview, so you can read it before it is in the thesis
content/rendered/thesis/methods.md	a Markdown preview of the same
content/rendered/thesis/methods.evidence.pdf	the evidence sidecar: each cited source with the spans that justified it

🔧 Before you start

Three things, once per machine.

1. Install it and get a project directory. Either

pip install chitragupta-cli
chitragupta init my-thesis
cd my-thesis

or clone the repository and cp config.toml.example config.toml.

2. Export your library to BibTeX, at papers/bibliography.bib, with the PDF file paths attached:

mkdir -p papers
cp /path/to/your-library.bib papers/bibliography.bib

3. Build the corpus:

chitragupta corpus sync
chitragupta corpus ledger          # a summary: how many entries, how many parsed

If nothing is parsed, your export has no usable PDF paths. Fix that first, because a chapter cannot be grounded in a corpus with no text in it.

Every command here also works as python -m chitragupta.<layer> ....

🔬 Step 1: the research question, the examiner, the slug

The research question is the one thing this genre will not proceed sensibly without. A thesis chapter argues toward an RQ instead of summarising papers in sequence. Write it down in one sentence, e.g. "RQ2: under what conditions does a reduced-order surrogate remain faithful enough to support a safety decision?"

The examiner is your reader. Name what they already know, so background is recapped where it is needed and nowhere else. "An examiner in control engineering who has never worked with digital twins" produces a very different chapter from "an examiner who supervises three digital-twin students".

The slug is the path under content/drafts/, without the suffix:

You are writing	Use
the methods chapter of one thesis	thesis/methods
a chapter that shares a topic with other genres	dt/thesis-chapter
a standalone chapter	methods

🗂 Step 2: open the dossier

chitragupta draft dossier init content/drafts/thesis/methods.tex \
    --genre thesis-chapter

Note the .tex suffix: this genre's draft is LaTeX.

That writes eight files. Exactly one is yours to fill in: scope.md. The rest (evidence.md, rejected.md, sections.md, retrieval.md, steering.md, revisions.md, README.md) are written for you as the chapter is produced.

What goes in scope.md

init writes it with every heading present and empty. Five things are yours:

Field	What goes in it	Why it is asked for
- language:	a BCP-47 tag: en-GB, en-US, en-IN	ships unset; your institution decides it, and an unset one silently gets the model's own
## Reader	the examiner, in one sentence, including what they have just read	background gets recapped where it is needed and nowhere else
## Covers	the RQ this chapter serves, and nothing beyond it	keeps the chapter from absorbing the next one
## Does not cover	what belongs to other chapters, and any theme the corpus could not support	an examiner reads an unexplained absence as an oversight
## Glossary	each recurring term with its one pinned definition	the field that matters most in this genre: an examiner notices terminology drift, and this is what a later revision is held to

Set the dialect with the command, so the format is right:

chitragupta draft dossier set-language content/drafts/thesis/methods.tex en-GB

A filled-in thesis-chapter scope.md follows; the whole file is at examples/dossiers/thesis-chapter/scope.md:

# Scope

- genre: thesis-chapter
- language: en-GB
- draft: content/drafts/thesis/methods.tex
- created: 2026-09-15
- corpus: 214 citekeys, digest `a31f0c4b77de`
- draft digest: not recorded (run `dossier stamp` once the draft is ready)

## Reader

The external examiner: a control engineer who has supervised
reduced-order modelling work but has never built a digital twin, and who
will read adversarially for the claim that outruns its evidence. They
have just read chapters 1-3, so the motivation is established and must
not be re-argued here.

## Covers

RQ2 only: under what conditions a reduced-order surrogate stays faithful
enough to support a safety decision.

## Does not cover

The empirical evaluation. That is chapter 5, and moving any of it here
would leave chapter 5 as a results table with no argument.

Learned surrogates (neural). Deliberate: the thesis' contribution is in
projection-based reduction, and the two literatures have different
notions of error entirely.

## Glossary

- **Surrogate** -- any cheaper model standing in for the full-order
  simulation. Reserved for the projection-based kind; a learned stand-in
  is called an emulator.
- **Fidelity** -- error on the quantities the safety decision depends
  on, never a global norm. Pinned here because three cited papers use it
  the other way and the chapter must not drift into their sense.
- **Error bound** -- a guarantee that holds for every admissible input,
  as opposed to an observed maximum error on a test set, which is called
  an empirical fit throughout.

The two glossary entries that say "pinned here because the sources use it differently" let a chapter keep its own vocabulary while citing papers that do not share it.

🗺 Step 3: write an outline (optional, recommended)

For a chapter arguing toward an RQ, declaring the arc yourself is usually better than letting it be inferred:

chitragupta draft dossier init content/drafts/thesis/methods.tex \
    --genre thesis-chapter --outline

Look at what the corpus holds before you commit to sections:

chitragupta draft retrieve search "surrogate model fidelity" --k 15

Then edit content/dossiers/thesis/methods/outline.md. Three fields per section:

Field	What goes in it	What the skill does with it
brief:	steering in your own words	consumed once, never appears in the chapter
claim:	your own prose: the argument you intend to make	rewritten and grounded; any sentence the corpus cannot support is reported back rather than shipped
queries:	a - list of search terms	run verbatim instead of the skill inventing sub-themes

A section needs at least a brief: or a claim:; queries: is optional even then. Sections may nest (### under ##), which this genre uses more than the others, because a chapter's technical core usually has two or three families to treat separately.

This genre gets the most out of claim:. A thesis chapter argues, and writing your intended argument as claim: blocks means the skill either grounds each one or tells you it cannot, before an examiner finds the gap.

A worked example follows; the whole file is at examples/dossiers/thesis-chapter/outline.md:

## Why the surrogate question arises here

brief: Connect back to RQ1's result. Two paragraphs, no literature dump
-- the reader has just read chapter 3.

## What "faithful enough" has meant in the literature

claim: Fidelity is defined against a decision, not in the abstract, and
the field has no shared threshold.

queries:

- surrogate model fidelity criterion
- reduced order model validation

## Methods that bound the error

brief: This is the chapter's technical core. Prefer sources that state
an error bound over ones that report an empirical fit.

queries:

- reduced order model error bound
- surrogate uncertainty quantification

## Why the existing bounds do not transfer to my setting

brief: The gap that motivates chapter 5. Be explicit that this is my
argument, grounded where the corpus supports it.

queries:

- error bound assumptions violated nonlinear

Validate it:

chitragupta draft dossier outline content/drafts/thesis/methods.tex --check

🗣 Step 4: ask for the chapter

Ask in ordinary words, in a session in this project directory:

Draft the methods chapter of my thesis into content/drafts/thesis/methods.tex. RQ2 is: under what conditions does a reduced-order surrogate remain faithful enough to support a safety decision? The dossier and outline are there.

"Thesis chapter", "dissertation section" or "RQ-driven chapter" is what selects thesis-chapter-writer. Give it the RQ in the same message, because the RQ is the spine of everything it writes.

What it then does: clarifies the RQ if you did not give one, retrieves broadly and filters, re-searches thin concepts, checks for disagreement between kept sources, drafts the fragment with \citep/\citet, records provenance, and maps each section to the citekeys it cites. It never writes a citekey it did not get from a retrieval result.

✅ Step 5: gate, render, sidecar

The skill runs these. Run them yourself after any hand edit.

chitragupta draft gate content/drafts/thesis/methods.tex

OK means every \citep{...} key is real. FAIL names the line; fix the key or drop the claim.

Previews are for reading; the fragment stays canonical:

chitragupta draft render content/drafts/thesis/methods.tex --format pdf
chitragupta draft render content/drafts/thesis/methods.tex --format md

This genre should always emit the evidence sidecar. Your reader is an examiner reading adversarially for the claim that outruns its evidence, and the sidecar is what lets them check one:

chitragupta draft evidence content/drafts/thesis/methods.tex --format pdf

It is a separate standalone document, never something your thesis \inputs.

Then stamp it, so a later drift report knows what it is comparing against:

chitragupta draft dossier stamp content/drafts/thesis/methods.tex

📎 Step 6: put it in your thesis

Copy or symlink the fragment into your thesis tree and \input it:

\chapter{Methods}
\input{chapters/methods.tex}

Three things your thesis preamble must provide, because a fragment carries no preamble of its own:

• natbib or whatever supplies \citep/\citet. You almost certainly have this already.
• Every citekey the chapter cites, in your thesis .bib. They came from your own export, so this is normally already true.
• \usepackage{tikz} and the TikZ libraries any figure needs, if the chapter has figures. Each figure file names its libraries in a \usetikzlibrary line at the top; put those names in your preamble too.

The chapter writes no \renewcommand{\thefigure} and no hand-typed figure numbers, so your thesis numbers everything consistently.

🔍 Step 7: read the review aids

None of these can block anything; all exit 0. --write files a report under content/review/thesis/ for the agenda below to read; provenance files its report on every run and has no --write.

chitragupta draft style content/drafts/thesis/methods.tex
chitragupta review verbatim scan content/drafts/thesis/methods.tex --write
chitragupta review uncited content/drafts/thesis/methods.tex --write
chitragupta review provenance content/drafts/thesis/methods.tex
chitragupta review quotation content/drafts/thesis/methods.tex --write
chitragupta review support content/drafts/thesis/methods.tex --write

For a thesis chapter, three are worth more than the rest:

• review verbatim. Reuse of a source's wording is the failure with consequences at a viva. It reports wording shared with any parsed source, cited or not, in three buckets: long, short and quoted (the last being an attributed quotation, which is legitimate).
• review support. It checks whether each citation entails the claim it is attached to, which mechanises the examiner's own reading habit.
• review quotation. It checks that each quoted span matches the source it cites, word for word.

If the chapter has TikZ figures, also:

chitragupta review figure content/drafts/thesis/methods.tex --write

The agenda: all of them as one worklist

chitragupta review agenda content/drafts/thesis/methods.tex

The agenda merges the reports the aids above filed into one ranked worklist. It never runs an aid itself, and it names any aid whose report is absent. AGENDA.md explains every section of the file; WRITE-A-SURVEY.md's step 7 covers the [unattended]/[surfaced] classes, --baseline and --accept. What follows is the part specific to a thesis chapter.

For the methods chapter we have been building, the report reads like this (the fixed "How to read this" paragraph is left out):

# Agenda: content/drafts/thesis/methods.tex

> **Review aid, not a gate.** This report is evidence for a human
> judgement, never a verdict. A driver may read it back; no draft is
> blocked by what it says. See SOUL.md, and docs/ARCHITECTURE.md's
> "Layer 4: the review layer".

- Draft: `content/drafts/thesis/methods.tex`
- Command: `chitragupta review agenda content/drafts/thesis/methods.tex`
- chitragupta 6.166.1

## Sources

- Citation provenance: read
- Verbatim scan: read
- Citation coverage: not run
- Multi-source synthesis: not run
- TikZ layout check: read, no item class defined
- Uncited prose: read
- Quotation integrity: read
- Claim support: read
- Prose (style_check): read
- Dossier drift: read
- Recorded-but-uncited citekeys: read
- Accepted items: none recorded for this draft

## Summary

- 5 unsupported-claim
- 3 verbatim-run
- 2 uncited-claim
- 1 misquoted

## Findings

### unsupported-claim

- `b7c2109af441` [surfaced] (4.3 Why the existing bounds do not
  transfer): `\citep{benner_survey_2015}` scores weak: The available
  a-priori bounds assume a linearity the water-network model does not
- `1c9e77d0a2b8` [surfaced] (4.2 Methods that bound the error):
  `\citep{rozza_reduced_2008}` scores no support found: and the bound
  degrades gracefully outside the training envelope

### verbatim-run

- `3e716e1cee1c` [unattended] (4.1 What "faithful enough" has meant):
  17-word verbatim run citing `benner_survey_2015`, 8 matched
- `dc32161a46ac` [unattended] (4.2 Methods that bound the error):
  13-word verbatim run citing `rozza_reduced_2008`

### misquoted

- `9f04b1e7c3a2` [surfaced] (4.1 What "faithful enough" has meant): the
  quoted span differs from the source at 3 words -- "error bound" for
  "error estimate"

### uncited-claim

- `a1971eb28d62` [surfaced] (4.4 What this chapter establishes):
  Projection-based reduction is the only family with a-priori guarantees

Reading that as the author: the misquoted item is the one to fix first. A quotation that says "bound" where the source said "estimate" is the error this chapter's own glossary exists to prevent, and an examiner who spots it will doubt the rest. The two unsupported-claim items are the sentences where your argument outruns your sources: either soften them, or find the source that carries them. The uncited-claim in the closing section is a claim you have made on your own authority in a place the chapter said it would not.

The [unattended] verbatim runs can be handed off: ask to "work the review agenda" and agenda-reviser repairs them one at a time, re-running the gate after each and logging every attempt in revisions.md.

📝 Step 8: change something

Never re-run the genre skill to make a change. Ask for a revision:

The examiner will not accept the claim in section 2 without a bound. Soften it and cite whatever in the corpus actually states one.

That selects draft-reviser, which reads the dossier, edits only what is affected, and logs it in revisions.md.

After any hand edit of your own:

chitragupta draft gate content/drafts/thesis/methods.tex
chitragupta draft dossier stamp content/drafts/thesis/methods.tex

Back it up, since content/drafts/ is gitignored:

chitragupta draft dossier export thesis/methods

🚑 When something goes wrong

What you see	What it means	What to do
The skill refuses, saying the ledger is empty	no corpus	chitragupta corpus sync
gate says FAIL	a \citep key is not in the corpus	correct it or drop the claim; never add it by hand
The preview PDF fails on a figure	the figure's TikZ does not compile	ask to fix the figure, which figure-drawer handles; a broken figure fails the whole render
Your thesis build fails on \citep	no natbib in your preamble	add it; the fragment cannot
Your thesis build fails on of in a node position	the TikZ library is not loaded in your preamble	add \usetikzlibrary{...} with the names the figure file lists
The chapter reads like a summary, not an argument	the RQ was never stated	give the RQ and ask draft-reviser to re-frame around it
A cited paper left your library	the corpus moved	chitragupta draft dossier status --all, then ask for a re-grounding pass, which draft-reviser runs