wtf-p 0.1.0

package/write-the-f-paper/references/length-estimation.md

@@ -0,0 +1,148 @@
+<length_estimation>
+Writing plans must maintain consistent quality from first task to last. This requires understanding quality degradation and splitting aggressively.
+
+<quality_insight>
+Claude degrades when it *perceives* context pressure and enters "completion mode."
+
+| Context Usage | Quality | Claude's State |
+|---------------|---------|----------------|
+| 0-30% | PEAK | Thorough, nuanced writing |
+| 30-50% | GOOD | Confident, solid prose |
+| 50-70% | DEGRADING | Efficiency mode begins |
+| 70%+ | POOR | Rushed, generic text |
+
+**The 40-50% inflection point:** Claude sees context mounting and thinks "I'd better conserve now." Result: "I'll finish the remaining paragraphs more concisely" = quality crash.
+
+**The rule:** Stop BEFORE quality degrades, not at context limit.
+</quality_insight>
+
+<context_target>
+**Plans should complete within ~50% of context usage.**
+
+Why 50% not 80%?
+- No context anxiety possible
+- Quality maintained start to finish
+- Room for unexpected complexity
+- If you target 80%, you've already spent 40% in degradation mode
+</context_target>
+
+<task_rule>
+**Each plan: 2-3 tasks maximum. Stay under 50% context.**
+
+| Section Complexity | Tasks/Plan | Context/Task | Total |
+|-------------------|------------|--------------|-------|
+| Simple (abstract, short sections) | 3 | ~10-15% | ~30-45% |
+| Medium (methods, results) | 2-3 | ~15-20% | ~40-50% |
+| Complex (intro, discussion) | 2 | ~20-25% | ~40-50% |
+
+**When in doubt: Default to 2 tasks.** Better to have an extra plan than degraded quality.
+</task_rule>
+
+<word_count_context_mapping>
+| Words Written | Context Impact |
+|---------------|----------------|
+| 100-300 words | ~10-15% (small) |
+| 300-600 words | ~20-30% (medium) |
+| 600+ words | ~40%+ (large - split) |
+
+| Section Type | Context/Task |
+|--------------|--------------|
+| Abstract (150-250 words) | ~15% |
+| Introduction (~1000 words) | ~40% (split into 2-3 plans) |
+| Methods (~1500 words) | ~50% (split into 2-3 plans) |
+| Results (~1000 words) | ~40% (split into 2 plans) |
+| Discussion (~1500 words) | ~50% (split into 2-3 plans) |
+</word_count_context_mapping>
+
+<split_signals>
+
+<always_split>
+- **More than 3 paragraph clusters** - Even if word count seems manageable
+- **Multiple distinct arguments** - Each argument = separate plan
+- **Section >800 words** - Split by paragraph groups
+- **Multiple citation clusters** - One plan per evidence group
+- **Introduction + Methods** - Never combine different section types
+</always_split>
+
+<consider_splitting>
+- Estimated >600 words total
+- Complex arguments requiring evidence
+- Sections requiring different writing modes
+- Natural semantic boundaries (opening → body → close)
+</consider_splitting>
+</split_signals>
+
+<splitting_strategies>
+**By paragraph:** Introduction → 01: Hook + gap, 02: Thesis + roadmap
+
+**By argument:** Discussion → 01: Interpretation, 02: Implications, 03: Limitations + future
+
+**By complexity:** Methods → 01: Design + participants, 02: Procedures, 03: Analysis
+
+**By mode:** Results → 01: Scaffold main findings (user fills), 02: Co-author supporting analyses
+</splitting_strategies>
+
+<anti_patterns>
+**Bad - Comprehensive plan:**
+```
+Plan: "Complete Introduction"
+Tasks: 6 (hook, context, gap, thesis, contributions, roadmap)
+Result: Task 1-3 good, Task 4-6 rushed
+```
+
+**Good - Atomic plans:**
+```
+Plan 1: "Introduction Opening" (2 tasks: hook, context)
+Plan 2: "Introduction Core" (2 tasks: gap, thesis)
+Plan 3: "Introduction Close" (2 tasks: contributions, roadmap)
+Each: 30-40% context, peak quality, atomic commits
+```
+</anti_patterns>
+
+<section_recommendations>
+
+| Section | Recommended Plans | Tasks Each |
+|---------|-------------------|------------|
+| Abstract | 1 (reviewer mode) | 1-2 |
+| Introduction | 2-3 | 2 each |
+| Methods | 2-3 | 2-3 each |
+| Results | 2 | 2 each |
+| Discussion | 2-3 | 2 each |
+| Conclusion | 1 | 2 |
+
+**Total for typical paper:** 10-15 plans, not 6 (one per section)
+
+</section_recommendations>
+
+<depth_calibration>
+**Depth controls plan COUNT, not plan SIZE.**
+
+| Depth | Typical Sections | Typical Plans/Section | Tasks/Plan |
+|-------|------------------|----------------------|------------|
+| Quick | 4-5 | 1-2 | 2-3 |
+| Standard | 5-6 | 2-3 | 2-3 |
+| Comprehensive | 6-8 | 3-4 | 2-3 |
+
+Tasks/plan is CONSTANT at 2-3. The 50% context rule applies universally.
+
+**Key principle:** Derive from actual content. Depth determines how aggressively you combine things, not a target to hit.
+
+- Comprehensive introduction = 4 plans (because intro genuinely has 4 components)
+- Comprehensive abstract = 1 plan (because that's all it is)
+
+Don't pad simple sections to hit a number. Don't compress complex sections to look efficient.
+</depth_calibration>
+
+<summary>
+**2-3 tasks, 50% context target:**
+- All writing: Peak quality
+- Git: Atomic per-task commits
+- Subagent plans: Fresh context
+
+**The principle:** Aggressive atomicity. More plans, smaller scope, consistent quality.
+
+**The rule:** If in doubt, split. Quality over consolidation. Always.
+
+**Depth rule:** Depth increases plan COUNT, never plan SIZE.
+</summary>
+</length_estimation>

package/write-the-f-paper/references/plan-format.md

@@ -0,0 +1,361 @@
+<overview>
+Claude-executable writing plans have a specific format that enables Claude to write without interpretation. This reference defines what makes a plan executable vs. vague.
+
+**Key insight:** PLAN.md IS the executable prompt. It contains everything Claude needs to write the section, including objective, context references, tasks, verification, success criteria, and output specification.
+</overview>
+
+<core_principle>
+A plan is Claude-executable when Claude can read the PLAN.md and immediately start writing without asking clarifying questions.
+
+If Claude has to guess the argument, tone, or what to include - the task is too vague.
+</core_principle>
+
+<prompt_structure>
+Every PLAN.md follows this XML structure:
+
+```markdown
+---
+section: XX-name
+plan: YY
+mode: [co-author/scaffold/reviewer]
+word_target: [X]
+---
+
+<objective>
+[What section/content and why]
+Purpose: [What reader will understand]
+Output: [Word count] words covering [topics]
+</objective>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/structure/argument-map.md
+@.planning/sources/literature.md
+</context>
+
+<tasks>
+<task type="auto" mode="co-author">
+  <name>Task N: [Name]</name>
+  <target>[word count]</target>
+  <action>[what to write, key points, tone]</action>
+  <verify>[how to check]</verify>
+  <done>[criteria]</done>
+</task>
+
+<task type="checkpoint:human-verify" gate="blocking">
+  <what-written>[what Claude drafted]</what-written>
+  <how-to-verify>[what to check - argument, voice, accuracy]</how-to-verify>
+  <resume-signal>[how to continue - "approved" or describe issues]</resume-signal>
+</task>
+
+<task type="checkpoint:decision" gate="blocking">
+  <decision>[content direction choice]</decision>
+  <context>[why this matters]</context>
+  <options>
+    <option id="option-a"><name>[Name]</name><pros>[pros]</pros><cons>[cons]</cons></option>
+    <option id="option-b"><name>[Name]</name><pros>[pros]</pros><cons>[cons]</cons></option>
+  </options>
+  <resume-signal>[how to indicate choice]</resume-signal>
+</task>
+</tasks>
+
+<verification>
+[Overall section checks]
+</verification>
+
+<success_criteria>
+[Measurable completion]
+</success_criteria>
+
+<output>
+[SUMMARY.md specification]
+</output>
+```
+
+</prompt_structure>
+
+<task_anatomy>
+Every writing task has required fields:
+
+<field name="target">
+**What it is**: Word count goal for this task.
+
+**Good**: `~200 words`, `150-200 words`
+**Bad**: "a paragraph", "some text"
+
+Be specific about length.
+</field>
+
+<field name="action">
+**What it is**: Specific writing instructions, including key points and tone.
+
+**Good**: "Write opening paragraph establishing the research gap. Key points: (1) current methods fail at X, (2) this matters because Y, (3) hint at our approach. Tone: confident but not dismissive of prior work. Cite Smith2023 and Jones2022."
+
+**Bad**: "Write the introduction", "Explain the problem"
+
+Include: key arguments, evidence to use, citations to include, tone guidance.
+</field>
+
+<field name="verify">
+**What it is**: How to check the writing is complete.
+
+**Good**:
+- Word count within target range
+- All key points addressed
+- Citations included
+- Flows from previous content
+
+**Bad**: "It's good", "Sounds academic"
+
+Must be checkable without subjective judgment.
+</field>
+
+<field name="done">
+**What it is**: Acceptance criteria - the measurable state of completion.
+
+**Good**: "~200 words establishing research gap, cites Smith2023 and Jones2022, transitions to thesis statement"
+
+**Bad**: "Introduction is written"
+
+Should be verifiable.
+</field>
+</task_anatomy>
+
+<task_modes>
+Tasks have a `mode` attribute for writing approach:
+
+<mode name="co-author">
+**Claude drafts, user refines**
+
+```xml
+<task type="auto" mode="co-author">
+  <name>Draft methods overview</name>
+  <target>300 words</target>
+  <action>
+    Write methods section overview covering:
+    - Study design (randomized controlled trial)
+    - Participants (N=150, recruited from...)
+    - Key procedures (3 phases over 6 weeks)
+    Tone: precise, replicable detail level
+  </action>
+  <verify>300 ±30 words, all three areas covered</verify>
+  <done>Methods overview ready for user refinement</done>
+</task>
+```
+
+Use for: Methods, procedures, boilerplate, initial drafts.
+</mode>
+
+<mode name="scaffold">
+**Claude outlines, user fills**
+
+```xml
+<task type="auto" mode="scaffold">
+  <name>Create results section outline</name>
+  <target>outline + placeholder text</target>
+  <action>
+    Create detailed outline for results section:
+    - Main finding 1: [placeholder for specific result]
+    - Main finding 2: [placeholder for specific result]
+    - Supporting analyses: [placeholder]
+    Include: structure, key points to make, suggested citations
+    Do NOT write full prose - user will fill
+  </action>
+  <verify>Outline has clear structure, all findings have placeholders</verify>
+  <done>Outline ready for user to fill with specific results</done>
+</task>
+```
+
+Use for: Results (user knows specifics), arguments requiring judgment.
+</mode>
+
+<mode name="reviewer">
+**User writes, Claude critiques**
+
+```xml
+<task type="auto" mode="reviewer">
+  <name>Review user's abstract draft</name>
+  <action>
+    Read user's abstract and provide feedback on:
+    1. Is the problem clearly stated?
+    2. Is the method summarized adequately?
+    3. Are findings specific (not vague)?
+    4. Is the contribution clear?
+    5. Word count appropriate for venue?
+
+    Use Socratic questions, not prescriptive fixes.
+  </action>
+  <verify>Feedback addresses all 5 areas</verify>
+  <done>User has actionable feedback to improve abstract</done>
+</task>
+```
+
+Use for: Abstract, discussion, conclusions, voice-critical sections.
+</mode>
+</task_modes>
+
+<checkpoint_types>
+
+**checkpoint:human-verify** (90%)
+Human confirms writing captures intent.
+
+```xml
+<task type="checkpoint:human-verify" gate="blocking">
+  <what-written>Introduction opening (~200 words)</what-written>
+  <how-to-verify>
+    1. Does this capture the research gap accurately?
+    2. Is the tone right for your target venue?
+    3. Any factual errors?
+  </how-to-verify>
+  <resume-signal>Type "approved" or describe changes needed</resume-signal>
+</task>
+```
+
+**checkpoint:decision** (9%)
+Human chooses content direction.
+
+```xml
+<task type="checkpoint:decision" gate="blocking">
+  <decision>Framing of contribution</decision>
+  <context>Two valid ways to position your work.</context>
+  <options>
+    <option id="novel"><name>Emphasize novelty</name><pros>Highlights contribution</pros><cons>May invite scrutiny</cons></option>
+    <option id="extend"><name>Frame as extension</name><pros>Builds on established work</pros><cons>May seem incremental</cons></option>
+  </options>
+  <resume-signal>Select: novel or extend</resume-signal>
+</task>
+```
+
+**checkpoint:human-action** (1% - rare)
+User provides information Claude can't know.
+
+```xml
+<task type="checkpoint:human-action" gate="blocking">
+  <action>Provide specific experimental result</action>
+  <instructions>I need the exact p-value and effect size to complete this sentence.</instructions>
+  <resume-signal>Provide: p-value and effect size</resume-signal>
+</task>
+```
+
+</checkpoint_types>
+
+<context_references>
+Use @file references to load context:
+
+```markdown
+<context>
+@.planning/PROJECT.md           # Paper vision and thesis
+@.planning/ROADMAP.md           # Section structure
+@.planning/structure/argument-map.md  # Claims and evidence
+@.planning/structure/outline.md       # Section skeleton
+@.planning/sources/literature.md      # Citations available
+@.planning/sections/01-intro/01-01-SUMMARY.md  # Prior section
+</context>
+```
+
+Reference files Claude needs before writing.
+</context_references>
+
+<verification_section>
+Overall section verification:
+
+```markdown
+<verification>
+Before declaring section complete:
+- [ ] Word count: [target] ±10%
+- [ ] All key arguments from argument-map addressed
+- [ ] Citations included where claims made
+- [ ] Logical flow maintained
+- [ ] Connects to prior/next sections
+</verification>
+```
+
+</verification_section>
+
+<specificity_levels>
+<too_vague>
+
+```xml
+<task type="auto" mode="co-author">
+  <name>Write introduction</name>
+  <target>???</target>
+  <action>Write the introduction</action>
+  <verify>???</verify>
+  <done>Introduction is written</done>
+</task>
+```
+
+Claude: "What's the argument? What to cite? What tone?"
+</too_vague>
+
+<just_right>
+
+```xml
+<task type="auto" mode="co-author">
+  <name>Draft introduction hook and problem statement</name>
+  <target>200 words</target>
+  <action>
+    Write opening that:
+    1. Opens with compelling hook about [topic]
+    2. Establishes current state of field (cite Smith2023)
+    3. Identifies the gap: [specific gap]
+    4. Stakes: why this matters for [audience]
+
+    Tone: Confident, not hedging. Direct statements.
+    End with transition to next paragraph (thesis preview).
+  </action>
+  <verify>~200 words, all 4 points addressed, Smith2023 cited</verify>
+  <done>Opening establishes gap, ready for thesis statement</done>
+</task>
+```
+
+Claude can write this immediately.
+</just_right>
+
+<too_detailed>
+Writing the actual prose in the plan. Trust Claude to write from clear instructions.
+</too_detailed>
+</specificity_levels>
+
+<anti_patterns>
+<vague_actions>
+
+- "Write about the topic"
+- "Explain the methodology"
+- "Discuss the results"
+- "Add some analysis"
+
+These require Claude to decide WHAT to write. Specify it.
+</vague_actions>
+
+<unverifiable_completion>
+
+- "It reads well"
+- "The argument is strong"
+- "Academic enough"
+- "Good flow"
+
+These require subjective judgment. Make it objective.
+</unverifiable_completion>
+
+<missing_context>
+
+- "Use appropriate citations"
+- "Follow academic conventions"
+- "Match the paper's style"
+
+Claude doesn't know your style. Be explicit.
+</missing_context>
+</anti_patterns>
+
+<sizing_tasks>
+Good task size: One paragraph cluster or argument unit.
+
+**Too small**: "Write topic sentence" (combine with paragraph)
+**Just right**: "Draft opening paragraph establishing research gap" (focused, specific)
+**Too big**: "Write entire introduction" (split into paragraph-level tasks)
+
+If a section is >500 words, break into multiple tasks.
+If a task is one sentence, combine with related tasks.
+</sizing_tasks>

package/write-the-f-paper/references/principles.md

@@ -0,0 +1,158 @@
+<principles>
+Core principles for the Write The F***ing Paper planning system.
+
+<solo_writer_claude>
+
+You are planning for ONE person (the researcher) and ONE writing partner (Claude).
+- No committees, stakeholders, co-author coordination overhead
+- User is the expert/visionary with domain knowledge
+- Claude is the writing partner and advisor
+- Estimate effort in words/sections, not human writing time
+</solo_writer_claude>
+
+<plans_are_prompts>
+
+PLAN.md is not a document that gets transformed into a prompt.
+PLAN.md IS the prompt. It contains:
+- Objective (what section/content and why)
+- Context (@file references to structure, sources)
+- Tasks (with word targets and verification)
+- Success criteria (measurable)
+
+When planning a section, you are writing the prompt that will execute it.
+</plans_are_prompts>
+
+<initialization_leverage>
+
+The most leveraged moment is paper initialization.
+- Deep questioning here = better arguments downstream
+- Vague thesis = weak paper
+- Spend the tokens on understanding the core argument
+- Don't rush to "the writing"
+</initialization_leverage>
+
+<scope_control>
+
+Plans must complete within reasonable context usage.
+
+**Quality degradation curve:**
+- 0-30% context: Peak quality writing
+- 30-50% context: Good quality writing
+- 50-70% context: Degrading quality
+- 70%+ context: Poor quality, rushed prose
+
+**Solution:** Aggressive atomicity - split into small, focused plans.
+- One section or subsection per plan maximum
+- Each plan independently executable
+- Better to have many focused plans than few sprawling ones
+</scope_control>
+
+<writing_modes>
+
+Claude adapts its role based on section needs:
+
+**Co-Author Mode (Claude drafts):**
+- Best for: Methods, procedures, boilerplate
+- Claude writes first draft, user refines
+- User provides key facts, Claude structures prose
+
+**Scaffold Mode (Claude outlines):**
+- Best for: Results, arguments requiring user judgment
+- Claude creates detailed outline with key points
+- User fills in actual prose
+
+**Reviewer Mode (Claude critiques):**
+- Best for: Abstract, discussion, conclusions
+- User writes, Claude provides feedback
+- Socratic questioning to strengthen arguments
+
+Choose mode based on section type and user preference.
+</writing_modes>
+
+<deviation_rules>
+
+Plans are guides, not straitjackets. During writing:
+
+1. **Auto-fix prose issues** - Fix awkward sentences, improve flow
+2. **Auto-add critical elements** - Missing transitions, unclear references
+3. **Auto-fix blockers** - Citation format issues, broken references
+4. **Ask about argument changes** - Major thesis modifications, stop and ask
+5. **Log enhancements** - Nice-to-have improvements, log to Issues, continue
+</deviation_rules>
+
+<three_layer_verification>
+
+Every section gets verified against three criteria:
+
+**1. Citation Check (Mechanical):**
+- All claims have citations
+- Citations formatted correctly
+- No broken references
+
+**2. Argument Coherence (Logical):**
+- Claims follow from evidence
+- No logical contradictions
+- Flow between paragraphs
+
+**3. Rubric Check (Requirements):**
+- Required elements present
+- Word count targets met
+- Format requirements satisfied
+</three_layer_verification>
+
+<ship_drafts>
+
+No perfectionism. Get words on paper.
+
+Draft → Review → Revise → Ship
+
+Milestones mark submission rounds (draft-1 → revision-1 → final).
+</ship_drafts>
+
+<atomic_commits>
+
+**Git commits = context engineering for Claude.**
+
+Each writing task gets its own commit immediately after completion:
+- Format: `write({section}-{plan}): {description}`
+- Types: write, revise, cite, polish, docs
+- One final metadata commit per plan: `docs({section}-{plan}): complete [section-name]`
+
+**Why per-task commits:**
+- Git history shows writing evolution
+- Each task independently revertable
+- Better recovery if section needs rework
+- Clear record of what was written when
+</atomic_commits>
+
+<advisor_voice>
+
+Claude's voice in WTF-P is that of an experienced academic advisor:
+
+- Ask questions before suggesting solutions
+- Be supportive but honest about weaknesses
+- Focus on clarity and logical rigor
+- Respect the writer's voice and expertise
+- Never condescend or lecture
+- Celebrate progress genuinely
+
+When reviewing work:
+- Start with what's working
+- Ask clarifying questions before critiquing
+- Suggest, don't prescribe
+- Explain the "why" behind suggestions
+</advisor_voice>
+
+<anti_academic_theater>
+
+NEVER include:
+- Artificial word padding to meet counts
+- Jargon for jargon's sake
+- Unnecessary hedging ("it could be argued that perhaps...")
+- Citation chains without reading the sources
+- "Future work" sections that are cop-outs
+- Passive voice when active is clearer
+
+If it sounds like academic throat-clearing, delete it.
+</anti_academic_theater>
+</principles>