1# Report Assembly: Progressive File Generation
2 
3## Length Requirements by Mode
4 
5| Mode | Target Words | Description |
6|------|--------------|-------------|
7| Quick | 2,000-4,000 | Baseline quality threshold |
8| Standard | 4,000-8,000 | Comprehensive analysis |
9| Deep | 8,000-15,000 | Thorough investigation |
10| UltraDeep | 15,000-20,000+ | Maximum rigor (at output limit) |
11 
12---
13 
14## Output Token Safeguard
15 
16**Claude Code default limit:** 32,000 output tokens (~24,000 words total per execution)
17 
18**Practical limits:**
19- Target <=20,000 words total output
20- Leave safety margin for tool call overhead
21- Reports >20,000 words require auto-continuation (see continuation.md)
22 
23---
24 
25## Progressive Section Generation
26 
27**Core Strategy:** Generate and write each section individually using Write/Edit tools. This allows unlimited report length while keeping each generation manageable.
28 
29### Phase 8.1: Setup
30 
31```bash
32# Create folder: ~/Documents/[TopicName]_Research_[YYYYMMDD]/
33mkdir -p ~/Documents/[folder_name]
34 
35# Initialize markdown file with frontmatter
36# Path: [folder]/research_report_[YYYYMMDD]_[slug].md
37```
38 
39### Phase 8.2: Section Generation Loop
40 
41**Pattern:** Generate section -> Write/Edit to file -> Move to next section
42Each Write/Edit call contains ONE section (<=2,000 words per call)
43 
44**Initialize research run (persist to disk):**
45```bash
46# Create run manifest and artifact files using citation_manager CLI
47python scripts/citation_manager.py init-run --out-dir [folder] --query "[question]" --mode [mode]
48# Creates: run_manifest.json, sources.jsonl, evidence.jsonl, claims.jsonl
49```
50 
51**Register each source as you encounter it:**
52```bash
53python scripts/citation_manager.py register-source \
54  --json '{"raw_url": "...", "title": "...", "source_type": "academic", "year": "2024"}' \
55  --dir [folder]
56# Returns stable source_id (sha256-based, survives renumbering and continuation)
57```
58 
59**Assign display numbers after all sources registered:**
60```bash
61python scripts/citation_manager.py assign-display-numbers --dir [folder]
62# Maps stable source_ids to [1], [2], [3]... for rendering
63```
64 
65Source identity is stable across edits and continuation. Display numbers are derived at render time, never stored in state. This survives context compaction and enables continuation agents to pick up citation state via stable IDs.
66 
67**Section sequence:**
68 
691. **Executive Summary** (200-400 words)
70   - Tool: Write(file, frontmatter + Executive Summary)
71   - Track citations
72   - Progress: "Executive Summary complete"
73 
742. **Introduction** (400-800 words)
75   - Tool: Edit(file, append Introduction)
76   - Track citations
77   - Progress: "Introduction complete"
78 
793. **Finding 1-N** (600-2,000 words each)
80   - Tool: Edit(file, append Finding N)
81   - Track citations
82   - Progress: "Finding N complete"
83 
844. **Synthesis & Insights**
85   - Novel insights beyond source statements
86   - Tool: Edit(append)
87 
885. **Limitations & Caveats**
89   - Counterevidence, gaps, uncertainties
90   - Tool: Edit(append)
91 
926. **Recommendations**
93   - Immediate actions, next steps, research needs
94   - Tool: Edit(append)
95 
967. **Bibliography** (CRITICAL)
97   - EVERY citation from citations_used list
98   - NO ranges, NO placeholders, NO truncation
99   - Tool: Edit(append)
100 
1018. **Methodology Appendix**
102   - Research process, verification approach
103   - Tool: Edit(append)
104 
105---
106 
107## File Organization
108 
109**1. Create dedicated folder:**
110- Location: `~/Documents/[TopicName]_Research_[YYYYMMDD]/`
111- Clean topic name (remove special chars, use underscores)
112 
113**2. File naming convention:**
114All files use same base name:
115- `research_report_20251104_topic_slug.md`
116- `research_report_20251104_topic_slug.html`
117- `research_report_20251104_topic_slug.pdf`
118 
119**3. Also save copy to:** `~/.claude/research_output/` (internal tracking)
120 
121---
122 
123## Word Count Per Section
124 
125**CRITICAL:** No single Edit call should exceed 2,000 words.
126 
127Example: 10 findings x 1,500 words = 15,000 words total
128- Each Edit call: 1,500 words (under limit)
129- File grows to 15,000 words
130- No single tool call exceeds limits
131