maestro-flow 0.5.31 → 0.5.33

package/.agents/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: `read_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 track_tasks `in_progress` (active phase protection)
+> 2. Full protocol (Step 3.1 -- 3.8) is in active memory, not just sentinel
+> If only sentinel remains -> `read_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)
+- **track_tasks**: Mark Phase 3 completed, Phase 4 in_progress
+
+## Next Phase
+
+Return to orchestrator, then continue to [Phase 4: Citation Management](04-citation-management.md).

package/.agents/skills/scholar-writing/phases/04-citation-management.md

@@ -0,0 +1,310 @@
+# Phase 4: Citation Management
+
+> **COMPACT SENTINEL [Phase 4: Citation Management]**
+> This phase contains 7 execution steps (Step 4.1 -- 4.7).
+> If you can read this sentinel but cannot find the full Step protocol below, context has been compressed.
+> Recovery: `read_file("phases/04-citation-management.md")`
+
+Find, verify, and format all citations. Replace placeholders with verified references. Build a clean bibliography.
+
+## Objective
+
+- Resolve all `[CITE: ...]` and `[CITATION NEEDED]` placeholders in the draft
+- Verify every citation via web_search and Google Scholar
+- Build a verified `references.bib` file
+- Ensure no hallucinated citations remain
+
+## Critical Rule
+
+**NEVER generate BibTeX entries from memory. ALWAYS fetch programmatically.**
+
+AI-generated citations have a ~40% error rate. Hallucinated references are a serious form of academic misconduct that can result in desk rejection or retraction.
+
+| Action | Correct | Wrong |
+|--------|---------|-------|
+| Adding a citation | Search API -> verify -> fetch BibTeX | Write BibTeX from memory |
+| Uncertain about a paper | Mark as `[CITATION NEEDED]` | Guess the reference |
+| Cannot find exact paper | Note: "placeholder - verify" | Invent similar-sounding paper |
+
+## Execution
+
+### Step 4.1: Inventory Citation Needs
+
+Scan all draft files for citation placeholders:
+
+```bash
+# Find all citation placeholders
+grep -rn "CITE:\|CITATION NEEDED\|PLACEHOLDER\|cite{.*TODO" $OUTPUT_DIR/.writing/drafts/
+```
+
+Create a citation inventory:
+
+```markdown
+## Citation Inventory
+| # | Placeholder | Context | Section | Status |
+|---|-------------|---------|---------|--------|
+| 1 | [CITE: transformer paper] | "attention mechanism [CITE]" | methods | pending |
+| 2 | [CITE: RLHF survey] | "alignment techniques [CITE]" | related | pending |
+| ... | ... | ... | ... | ... |
+```
+
+### Step 4.2: Collect Existing Citations
+
+Load citations already found in Phase 1 (from `repoContext.existingCitations`):
+
+- Read any `.bib` files found in the repo
+- Extract citation keys and paper metadata
+- These are pre-verified (researcher already used them)
+- Add directly to `references.bib`
+
+### Step 4.3: Search and Verify Each Citation
+
+> **CHECKPOINT**: Before proceeding, verify:
+> 1. This phase is track_tasks `in_progress` (active phase protection)
+> 2. Full protocol (Step 4.1 -- 4.7) is in active memory, not just sentinel
+> If only sentinel remains -> `read_file("phases/04-citation-management.md")` now.
+
+For each pending citation in the inventory, follow this mandatory 7-step process:
+
+**Step A: web_search to Find the Paper**
+
+Execute web_search with specific query patterns:
+
+```javascript
+// Example 1: Classic paper with known authors and year
+web_search({
+  query: "Attention is All You Need Vaswani 2017",
+  allowed_domains: ["arxiv.org", "scholar.google.com", "aclanthology.org"]
+})
+
+// Example 2: Recent paper with topic and year
+web_search({
+  query: "RLHF language model alignment 2023",
+  allowed_domains: ["arxiv.org", "scholar.google.com"]
+})
+
+// Example 3: Paper from specific organization
+web_search({
+  query: "sparse autoencoders interpretability Anthropic",
+  allowed_domains: ["arxiv.org", "scholar.google.com", "anthropic.com"]
+})
+
+// Example 4: Conference paper with venue
+web_search({
+  query: "BERT NLP pretraining NeurIPS 2018",
+  allowed_domains: ["papers.nips.cc", "scholar.google.com"]
+})
+```
+
+What to look for in results:
+- Paper title matches intended citation
+- Authors are correct
+- Publication year is correct
+- Venue (conference/journal) is identified
+
+**Step B: Verify on Google Scholar**
+
+Execute targeted Google Scholar search:
+
+```javascript
+// Direct Google Scholar search
+web_search({
+  query: "site:scholar.google.com Attention is All You Need Vaswani",
+  allowed_domains: ["scholar.google.com"]
+})
+
+// Alternative: Use paper title + first author
+web_search({
+  query: "site:scholar.google.com \"BERT: Pre-training of Deep Bidirectional Transformers\" Devlin",
+  allowed_domains: ["scholar.google.com"]
+})
+```
+
+Verification checklist:
+- Paper appears in Google Scholar results
+- Title matches exactly (or very close)
+- Authors match
+- Year matches
+- Venue is listed
+- Citation count is reasonable (not 0 for papers older than 1 year)
+
+**If paper NOT found on Google Scholar**: STOP. Do not cite. Mark as `[CITATION NEEDED - not found on Google Scholar]`.
+
+**Step C: Confirm Paper Details**
+
+Double-check all metadata:
+- Title: exact title from Google Scholar
+- Authors: all authors, in order
+- Year: publication year
+- Venue: conference/journal name
+- DOI: if available
+
+**Step D: Retrieve BibTeX**
+
+Priority order:
+1. **Google Scholar** (click "Cite" -> "BibTeX")
+2. **DOI content negotiation**: fetch from `https://doi.org/{DOI}` with `Accept: application/x-bibtex`
+3. **arXiv**: "Export BibTeX Citation" on sidebar
+
+NEVER write BibTeX from memory. Always copy from a verified source.
+
+**Step E: Verify the Claim**
+
+If citing for a specific claim (not just general reference):
+- Access the paper via web_search (PDF or HTML)
+- Search for keywords related to the claim
+- Confirm the claim is explicitly stated or clearly implied
+- Note the section/page where claim appears
+
+If you cannot access the paper:
+- Only cite for general contributions (if verified on Google Scholar)
+- Mark as `[CLAIM NOT VERIFIED - no access to paper]`
+
+**Step F: Generate Citation Key**
+
+Use consistent format: `author_year_firstword`
+
+```
+vaswani_2017_attention
+devlin_2019_bert
+brown_2020_language
+```
+
+**Step G: Add to Bibliography**
+
+Add verified BibTeX entry to `references.bib`.
+
+### Step 4.4: Handle Verification Failures
+
+For citations that cannot be verified:
+
+```latex
+% Option 1: Explicit placeholder
+\cite{PLACEHOLDER_smith2023_verify}  % TODO: Could not verify - scientist must confirm
+
+% Option 2: Note in text
+... as shown in prior work [CITATION NEEDED - could not verify Smith et al. 2023].
+```
+
+Track all failures:
+
+```markdown
+## Unverified Citations
+| # | Description | Reason | Action Needed |
+|---|-------------|--------|---------------|
+| 1 | Smith 2023 on reward hacking | Not found on Google Scholar | Scientist must verify |
+| 2 | Jones 2022 on scaling laws | Different authors found | Confirm correct paper |
+```
+
+### Step 4.5: Search for Additional Citations
+
+Beyond resolving placeholders, proactively search for:
+
+- Recent papers in the same area (last 2 years)
+- Key baselines that should be cited
+- Seminal works in the field
+- Papers by likely reviewers
+
+Search strategies:
+- `[main technique] + [application domain]`
+- `[baseline method] comparison`
+- `[problem name] state-of-the-art`
+- Author names from existing citations
+
+Verify each additional citation through the same 7-step process.
+
+### Step 4.6: Update Draft with Citations
+
+Replace all placeholders in draft files with verified `\cite{}` commands:
+
+```
+Before: "The transformer architecture [CITE: transformer paper] introduced..."
+After:  "The transformer architecture \cite{vaswani_2017_attention} introduced..."
+```
+
+Copy updated drafts to maintain history:
+```bash
+cp -r $OUTPUT_DIR/.writing/drafts/ $OUTPUT_DIR/.writing/drafts-pre-citation/
+```
+
+Then update the draft files in-place.
+
+### Step 4.7: Citation Report
+
+Generate a citation status report:
+
+```markdown
+## Citation Report
+
+### Summary
+- Total citations: [N]
+- Verified: [M]
+- Placeholders remaining: [K]
+- From existing repo: [J]
+
+### Verified Citations
+[List of all verified citations with key, title, venue, year]
+
+### Remaining Placeholders
+[List of unresolved citations with reasons]
+
+### Recommendation
+[Any suggestions for the scientist regarding citations]
+```
+
+Report to user:
+> "I've resolved [M] of [N] citations. [K] remain as placeholders that need your verification:
+> - [list of unverified citations with reasons]
+> Please verify these before submission."
+
+## BibTeX Format Reference
+
+### Conference Paper
+```bibtex
+@inproceedings{vaswani_2017_attention,
+  title = {Attention Is All You Need},
+  author = {Vaswani, Ashish and Shazeer, Noam and Parmar, Niki and
+            Uszkoreit, Jakob and Jones, Llion and Gomez, Aidan N and
+            Kaiser, Lukasz and Polosukhin, Illia},
+  booktitle = {Advances in Neural Information Processing Systems},
+  volume = {30},
+  year = {2017}
+}
+```
+
+### Journal Article
+```bibtex
+@article{hochreiter_1997_long,
+  title = {Long Short-Term Memory},
+  author = {Hochreiter, Sepp and Schmidhuber, J{\"u}rgen},
+  journal = {Neural Computation},
+  volume = {9},
+  number = {8},
+  pages = {1735--1780},
+  year = {1997}
+}
+```
+
+### arXiv Preprint
+```bibtex
+@misc{brown_2020_language,
+  title = {Language Models are Few-Shot Learners},
+  author = {Brown, Tom and Mann, Benjamin and Ryder, Nick and others},
+  year = {2020},
+  eprint = {2005.14165},
+  archiveprefix = {arXiv},
+  primaryclass = {cs.CL}
+}
+```
+
+## Output
+
+- **File**: `outputDir/.writing/references.bib` (verified bibliography)
+- **File**: Updated draft files in `outputDir/.writing/drafts/` (citations resolved)
+- **File**: `outputDir/.writing/citation-report.md` (status report)
+- **Variable**: `verifiedBib` (path to references.bib), `updatedDraft` (path to drafts/)
+- **track_tasks**: Mark Phase 4 completed, Phase 5 in_progress
+
+## Next Phase
+
+Return to orchestrator, then continue to [Phase 5: Anti-AI Polish](05-anti-ai-polish.md).