document-planner

What this skill does

# Document Planner

## Overview

This skill collaboratively builds writing plans at any scope — from whole-thesis chapter maps down to statement-level paragraph outlines with verified citations. It is the single planning skill for all document types and hierarchy levels.

The process is **fundamentally collaborative**. The author is a subject-matter expert who knows what points are needed to communicate clearly. You are a writing expert who structures documents logically, divides responsibilities into sections, and maintains narrative coherence across the wider document. Neither party works autonomously — every structural decision is discussed.

**CRITICAL — Zotero access policy**: NEVER call `mcp__deep-zotero__*` tools directly. All Zotero library access MUST go through the `zotero-research` agent, spawned via the Task tool. Only the `zotero-research` agent is permitted to call the MCP tools.

## When to Use This Skill

- Planning a new thesis from scratch (whole-thesis scope)
- Planning individual chapters from a thesis-level plan
- Building paragraph-level or statement-level plans for sections
- Revising the structure of an already-planned section
- Planning a standalone paper or report

## Chapter Types

Each chapter type has a distinct structure and writing approach. Use these when proposing chapter plans.

### Background Chapter
Literature-review style treatment. Provides context and foundation.
- **Structure**: Introduction → Major themes (organised thematically, NOT study-by-study) → Summary with gaps
- **Writing approach**: Synthesize across sources. Every claim needs citation(s). Identify gaps and controversies. Connect to thesis objectives.
- **Citation density**: High (1-3 citations per paragraph)
- **Figures**: Conceptual diagrams, timelines, comparison tables

### Meat Chapter (Research Chapter)
Paper-like IMRaD structure presenting original research. Each should be publishable as standalone.
- **Structure**: Introduction → Brief background (reference full background chapter) → Methods → Results → Discussion → Conclusion
- **Writing approach**: Self-contained but connected to thesis narrative. Methods fully reproducible. Results before interpretation.
- **Citation density**: Medium in intro/discussion, low in methods/results (own work)
- **Figures**: Data plots, block diagrams, result visualizations

### Conclusions Chapter
Synthesis of thesis findings and contributions.
- **Structure**: Summary of work → Key findings → Contributions → Limitations
- **Writing approach**: No new material. Reference thesis chapters, not external sources. Specific about contributions. Honest about limitations.
- **Citation density**: None (reference thesis chapters only)

### Future Work Chapter
Research directions and open questions.
- **Structure**: Immediate extensions → Longer-term directions → Open questions
- **Writing approach**: Concrete and actionable. Connect to thesis limitations.
- **Citation density**: Low

## Inputs

1. **Target scope**: Whole thesis, chapter, section, or subsection
2. **Document directory**: The directory containing the `.tex` file and (optionally) a `plan.md`

## Document Hierarchy

Three documents form an authority hierarchy for content. Higher-level documents set narrative and structure; lower-level documents add detail:

1. **`.tex` file** (most detailed, authoritative for existing prose)
2. **Directory-level `plan.md`** (paragraph/statement-level plan, created/maintained by this skill)
3. **Parent-level `plan.md`** (chapter-level or thesis-level plan, sets narrative goals)

If there is a `plan.md` one directory above the document directory, treat it as the hierarchical master plan for this document.

**Parent plan detail level:** The thesis-level plan should contain section purposes, high-level bullet points, and narrative goals. It does not contain references — those are resolved at the directory-level plan during Phase 3. The document-planner may update the parent plan to reflect structural changes (section reordering, new/removed sections, cross-chapter scope changes) but must NOT inflate it with paragraph-level detail, figure descriptions, or expanded sub-points. Those belong in the directory-level plan only.

### Startup: Read and Reconcile

1. **Read the `.tex` file first.** Existing content is authoritative — it must not be removed without explicit user discussion. The user edits this file between sessions.
2. **Read the directory-level `plan.md`** if it exists. This is the detailed plan from previous sessions. The user may have modified it between sessions.
3. **Read the parent-level `plan.md`** (e.g., `thesis/plan.md`). This contains the high-level narrative and key points.

**If the directory-level `plan.md` does not exist**, create one by copying in the parent plan's content for this document as a starting point.

### Reconciliation Rules

Compare the three documents and resolve discrepancies before proceeding:

- **Content in a higher-level doc missing from a lower-level doc**: Ask the user whether to (a) remove it from the higher-level doc, or (b) add it to the lower-level doc(s) in this or a future round.
- **Content in a lower-level doc that diverges from or modifies the narrative/key points in a higher-level doc**: Ask the user whether to (a) update the higher-level doc to match the new narrative, or (b) modify the lower-level doc to fit the existing narrative.

This hierarchy applies outside thesis structures too. Any document directory should have a `plan.md` and a `.tex` file; create them if missing.

### Structural Mismatches

When section headings, ordering, or structure differ between documents (e.g., `.tex` has different subsection titles than `plan.md`), **ask the user for guidance** — do not silently pick one. Present the mismatch and ask which version to follow, then update the other document(s) to match.

### Understanding the Parent Plan

The parent-level plan is a **thin outline** — a best attempt at a high-level overview of points that will meet narrative goals. It was typically built collaboratively with the author, so it **lacks specific detail**. Treat it as a structural starting point, not a content-complete source.

### Cold Start (No Higher-Level Plan)

When there is no parent-level `plan.md`, build the thin starting plan collaboratively:

1. Ask the author what this document needs to achieve and who the audience is
2. Propose a section structure with narrative bullet points based on the author's input
3. Iterate with the author until the high-level structure is agreed
4. Write this as the directory-level `plan.md` and proceed to Phase 2

For whole-thesis cold starts, first establish the overall narrative (what is the thesis about, what is the contribution, what story does it tell), then map chapters (background, meat, conclusions) with their connections before planning individual chapters.

## Workflow

### Phase 1: Read and Reconcile

Follow the Startup procedure above. Report what was found in each document and any discrepancies requiring user input.

### Phase 2: Narrative Structure and Paragraph Flow

**This is the core collaborative phase.** Before touching references or detailed points, establish the narrative arc and paragraph flow for each section.

#### Top-Down Planning Across Hierarchy Levels

Documents have multiple levels of hierarchy (thesis → chapter → section → subsection → paragraph). **Plan top-down**: complete the narrative arc and prerequisite check at the highest level before descending to plan individual children at the next level. Then work through children sequentially, planning each one at its own level before descending further.

**Procedure:**

1. **Plan the highest level first.** For a thesis, this means chapter ordering. For a chapter, section-level narrative arc.
2. **Get author agreement** on this level before proceeding.
3. **Descend one level.** Work through children **sequentially** — finish one child's plan before starting the next.
4. **Repeat**