maestro-flow 0.5.31 → 0.5.33

package/.agy/skills/scholar-writing/phases/02-structure-planning.md

@@ -0,0 +1,197 @@
+# Phase 2: Structure Planning
+
+Plan the paper structure, define the narrative arc, allocate page budgets, and create a detailed section outline.
+
+## Objective
+
+- Define the paper's narrative arc around the central contribution
+- Plan section structure appropriate for target conference
+- Allocate page budgets per section
+- Create a detailed outline with key points per section
+
+## Execution
+
+### Step 2.1: Conference Constraints
+
+Load constraints for `paperPreferences.targetConference`:
+
+| Conference | Page Limit | Extra Camera-Ready | Required Sections |
+|------------|------------|-------------------|-------------------|
+| NeurIPS 2025 | 9 pages | +0 | Checklist, Limitations |
+| ICML 2026 | 8 pages | +1 | Broader Impact |
+| ICLR 2026 | 9 pages | +1 | LLM Disclosure |
+| ACL 2025 | 8 pages (long) | varies | Limitations (mandatory), Ethics |
+| AAAI 2026 | 7 pages | +1 | Strict style adherence |
+| COLM 2025 | 9 pages | +1 | Language model focus |
+
+Universal requirements:
+- Double-blind review (anonymize submissions)
+- References do not count toward page limit
+- Appendices unlimited but reviewers are not required to read them
+- LaTeX required for all venues
+
+### Step 2.2: Define Narrative Arc
+
+Using `repoContext`, define the narrative following the three pillars:
+
+**The What** (crystal clear by end of introduction):
+- 1-3 specific novel claims within a cohesive theme
+
+**The Why** (evidence):
+- Which experiments support which claims?
+- What baselines establish the comparison?
+
+**The So What** (reader motivation):
+- What recognized community problem does this address?
+- What does this enable that was not possible before?
+
+Write a one-paragraph narrative summary that threads What/Why/So What into a coherent story.
+
+### Step 2.3: Page Budget Allocation
+
+Allocate pages based on conference limit and paper type:
+
+**Full Paper (9 pages, e.g., NeurIPS)**:
+| Section | Pages | Notes |
+|---------|-------|-------|
+| Abstract | 0.25 | 5-sentence formula |
+| Introduction | 1.0-1.5 | Contribution bullets, must end by page 2 |
+| Methods | 2.0-2.5 | Enough for reimplementation |
+| Experiments | 2.5-3.0 | Main results, ablations |
+| Related Work | 1.0-1.5 | Methodological grouping |
+| Conclusion | 0.5 | Summary + future work |
+| Limitations | 0.25-0.5 | Required at most venues |
+
+**Short Paper (4 pages)**:
+- Cut related work to 0.5 page
+- Combine methods + experiments
+- Move details to appendix
+
+Adjust for the specific conference page limit. Document the allocation.
+
+### Step 2.4: Section Outline
+
+Create a detailed outline for each section. For each section, specify:
+- Key points to make (bullet list)
+- Figures/tables planned
+- Which claims/evidence from repoContext map here
+- Approximate word count target
+
+**Outline Template**:
+
+```markdown
+## Abstract (150-250 words)
+- Sentence 1: What you achieved
+- Sentence 2: Why this is hard and important
+- Sentence 3: How you do it (with specialist keywords)
+- Sentence 4: What evidence you have
+- Sentence 5: Your most remarkable result
+
+## 1. Introduction (1-1.5 pages)
+- Opening: problem statement (2-3 sentences)
+- Gap: what's missing in current approaches
+- Contribution: 2-4 bullet list (max 1-2 lines each)
+- Approach overview: brief description of method
+- Figure 1: [description of key figure]
+
+## 2. Related Work (1-1.5 pages)
+- Group A: [methodological grouping, not paper-by-paper]
+- Group B: [...]
+- Positioning: how our work differs
+
+## 3. Method (2-2.5 pages)
+- 3.1 Problem Setup / Preliminaries
+- 3.2 [Core method component]
+- 3.3 [Second component if any]
+- 3.4 Implementation Details
+- Figure 2: [method diagram]
+
+## 4. Experiments (2.5-3 pages)
+- 4.1 Setup (datasets, baselines, metrics)
+- 4.2 Main Results — Table 1: [description]
+- 4.3 Ablation Studies — Table 2: [description]
+- 4.4 Analysis / Qualitative Results — Figure 3: [description]
+
+## 5. Conclusion (0.5 pages)
+- Summary of contribution
+- Key takeaway
+- Future directions (brief)
+
+## 6. Limitations (0.25-0.5 pages)
+- Known limitations
+- Why they don't undermine core claims
+
+## Appendix
+- Detailed proofs (if any)
+- Additional experiments
+- Hyperparameter details
+- Compute budget
+```
+
+### Step 2.5: Figure Planning
+
+Plan all figures and tables:
+
+| Figure/Table | Section | Content | Purpose |
+|--------------|---------|---------|---------|
+| Figure 1 | Intro | [Core idea visualization] | Hook readers |
+| Table 1 | Experiments | [Main comparison] | Support main claim |
+| Figure 2 | Method | [Architecture/pipeline] | Explain approach |
+| Table 2 | Experiments | [Ablations] | Justify design |
+| Figure 3 | Experiments | [Qualitative/analysis] | Provide insight |
+
+Rules for figures:
+- Vector graphics (PDF/EPS) for all plots and diagrams
+- Raster (PNG 600 DPI) only for photographs
+- Colorblind-safe palettes (Okabe-Ito or Paul Tol)
+- Verify grayscale readability
+- No title inside figure (caption serves this function)
+- Self-contained captions
+
+### Step 2.6: User Confirmation
+
+Present the outline to the user for feedback:
+
+> "Here is the proposed paper structure for [conference]. The narrative centers on [contribution].
+> Key sections: [list]. Total page budget: [N] pages.
+> Should I proceed with drafting, or adjust the outline?"
+
+If user provides feedback, revise outline before proceeding.
+
+## Output
+
+Write `outputDir/.writing/paper-outline.md`:
+
+```markdown
+# Paper Outline
+
+## Narrative Summary
+[One paragraph threading What/Why/So What]
+
+## Conference: [name]
+Page limit: [N] pages
+
+## Page Budget
+[Table of section -> page allocation]
+
+## Detailed Outline
+[Full section outline with key points, figures, tables]
+
+## Figure Plan
+[Table of planned figures and tables]
+
+## Writing Order
+1. Abstract (anchor the narrative)
+2. Introduction (establish contribution)
+3. Methods (technical detail)
+4. Experiments (evidence)
+5. Related Work (positioning)
+6. Conclusion + Limitations
+```
+
+- **Variable**: `paperOutline` (path to paper-outline.md)
+- **TodoWrite**: Mark Phase 2 completed, Phase 3 in_progress
+
+## Next Phase
+
+Return to orchestrator, then continue to [Phase 3: Section Drafting](03-section-drafting.md).

package/.agy/skills/scholar-writing/phases/03-section-drafting.md

@@ -0,0 +1,215 @@
+# Phase 3: Section Drafting
+
+> **COMPACT SENTINEL [Phase 3: Section Drafting]**
+> This phase contains 8 execution steps (Step 3.1 -- 3.8).
+> If you can read this sentinel but cannot find the full Step protocol below, context has been compressed.
+> Recovery: `view_file("phases/03-section-drafting.md")`
+
+Write all paper sections as LaTeX content following the outline, writing philosophy, and style guidelines.
+
+## Objective
+
+- Draft all paper sections as LaTeX content
+- Follow the Narrative Principle: every section supports the central contribution
+- Apply writing philosophy from top ML researchers
+- Produce complete draft ready for citation insertion and polishing
+
+## Execution
+
+### Step 3.1: Setup Draft Directory
+
+```bash
+mkdir -p $OUTPUT_DIR/.writing/drafts
+```
+
+### Step 3.2: Write Abstract
+
+Follow the 5-sentence formula (Farquhar):
+
+1. **What you achieved**: "We introduce...", "We prove...", "We demonstrate..."
+2. **Why this is hard and important**: the gap or challenge
+3. **How you do it**: method description with specialist keywords for discoverability
+4. **What evidence you have**: experimental validation summary
+5. **Your most remarkable number/result**: the headline result
+
+Rules:
+- 150-250 words
+- Delete generic openings like "Large language models have achieved remarkable success..."
+- Start with the specific contribution
+- Include specialist keywords for search discoverability
+
+Write to: `outputDir/.writing/drafts/abstract.tex`
+
+### Step 3.3: Write Introduction
+
+Must include (1-1.5 pages max):
+- Clear problem statement (2-3 sentences)
+- The gap in current approaches
+- 2-4 bullet contribution list (max 1-2 lines each in two-column format)
+- Brief approach overview
+- Figure 1 reference
+
+Writing rules:
+- Methods should start by page 2-3 maximum
+- Front-load the contribution -- reviewers form judgments before reaching methods
+- The three pillars (What/Why/So What) must be crystal clear by end of introduction
+- Use the stress position: place emphasis at sentence ends
+- Subject-verb proximity: keep subject and verb close
+
+Write to: `outputDir/.writing/drafts/introduction.tex`
+
+### Step 3.4: Write Methods
+
+> **CHECKPOINT**: Before proceeding, verify:
+> 1. This phase is TodoWrite `in_progress` (active phase protection)
+> 2. Full protocol (Step 3.1 -- 3.8) is in active memory, not just sentinel
+> If only sentinel remains -> `view_file("phases/03-section-drafting.md")` now.
+
+Enable reimplementation:
+- Conceptual outline or pseudocode for the core algorithm
+- All hyperparameters listed with values
+- Architectural details sufficient for reproduction
+- Present final design decisions; ablations go in experiments section
+
+Structure:
+- 3.1 Problem Setup / Preliminaries (notation, definitions)
+- 3.2 Core Method (the main technical contribution)
+- 3.3 Additional Components (if any)
+- 3.4 Implementation Details (training, optimization)
+
+Rules:
+- Explain intuition before presenting equations
+- Define all notation before first use
+- Consistent terminology throughout (pick one term per concept, stick with it)
+- Use verbs, not nominalizations: "We analyzed" not "We performed an analysis"
+
+Write to: `outputDir/.writing/drafts/methods.tex`
+
+### Step 3.5: Write Experiments
+
+For each experiment, explicitly state:
+- What claim it supports
+- How it connects to the main contribution
+- Experimental setting (details in appendix)
+- What to observe: "the blue line shows X, which demonstrates Y"
+
+Structure:
+- 4.1 Experimental Setup (datasets, baselines, metrics, compute)
+- 4.2 Main Results with Table 1
+- 4.3 Ablation Studies with Table 2
+- 4.4 Analysis / Qualitative Results
+
+Requirements:
+- Error bars with methodology (standard deviation vs standard error)
+- Number of runs and seeds
+- Hyperparameter search ranges (appendix)
+- Compute infrastructure (GPU type, total hours)
+- Bold best value per metric in tables
+- Include direction symbols (higher-is-better / lower-is-better)
+
+Use `booktabs` for tables:
+```latex
+\begin{tabular}{lcc}
+\toprule
+Method & Accuracy $\uparrow$ & Latency $\downarrow$ \\
+\midrule
+Baseline & 85.2 & 45ms \\
+\textbf{Ours} & \textbf{92.1} & 38ms \\
+\bottomrule
+\end{tabular}
+```
+
+Write to: `outputDir/.writing/drafts/experiments.tex`
+
+### Step 3.6: Write Related Work
+
+Organize methodologically, not paper-by-paper:
+
+**Good**: "One line of work uses assumption A [refs] whereas we use assumption B because..."
+**Bad**: "Smith et al. introduced X. Jones et al. introduced Y."
+
+Rules:
+- Group related approaches into 2-4 thematic categories
+- Position your work relative to each group
+- Cite generously -- reviewers likely authored relevant papers
+- Use `[CITE: description]` placeholders where citations are needed (Phase 4 will resolve)
+
+Write to: `outputDir/.writing/drafts/related-work.tex`
+
+### Step 3.7: Write Conclusion and Limitations
+
+**Conclusion** (0.5 pages):
+- Restate the contribution concisely
+- Summarize key evidence
+- Brief future directions (2-3 sentences)
+- No new information
+
+**Limitations** (required at most venues):
+- Honest acknowledgment of weaknesses
+- Explain why limitations do not undermine core claims
+- Reviewers are instructed not to penalize honest limitation disclosure
+- Pre-empt criticisms by identifying weaknesses first
+
+Write to: `outputDir/.writing/drafts/conclusion.tex`
+
+### Step 3.8: Write Appendix
+
+Move supplementary material here:
+- Detailed proofs (if any)
+- Additional experimental results
+- Full hyperparameter tables
+- Dataset details
+- Compute budget breakdown
+- Additional qualitative examples
+
+Write to: `outputDir/.writing/drafts/appendix.tex`
+
+## Writing Style Reference
+
+### Sentence-Level Clarity (Gopen & Swan)
+
+| Principle | Rule |
+|-----------|------|
+| Subject-verb proximity | Keep subject and verb close |
+| Stress position | Place emphasis at sentence ends |
+| Topic position | Put context first, new info after |
+| Old before new | Familiar info then unfamiliar info |
+| One unit, one function | Each paragraph makes one point |
+| Action in verb | Use verbs, not nominalizations |
+| Context before new | Set stage before presenting |
+
+### Micro-Level Tips (Perez)
+
+- Minimize pronouns: "This shows..." -> "This result shows..."
+- Verbs early: position verbs near sentence start
+- Delete filler: "actually," "a bit," "very," "really," "basically," "quite," "essentially"
+
+### Word Choice (Lipton)
+
+- Be specific: "performance" -> "accuracy" or "latency"
+- Eliminate hedging: drop "may" and "can" unless genuinely uncertain
+- Delete intensifiers: "very tight approximation" -> "tight approximation"
+
+### Precision (Steinhardt)
+
+- Consistent terminology: different terms for same concept creates confusion
+- State assumptions formally before theorems
+- Intuition + rigor: intuitive explanations alongside formal proofs
+
+## Output
+
+All draft sections written to `outputDir/.writing/drafts/`:
+- `abstract.tex`
+- `introduction.tex`
+- `methods.tex`
+- `experiments.tex`
+- `related-work.tex`
+- `conclusion.tex`
+- `appendix.tex`
+
+- **Variable**: `draftSections` (path to drafts/ directory)
+- **TodoWrite**: Mark Phase 3 completed, Phase 4 in_progress
+
+## Next Phase
+
+Return to orchestrator, then continue to [Phase 4: Citation Management](04-citation-management.md).