wtf-p 0.1.0

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

@@ -0,0 +1,132 @@
+<questioning_guide>
+The initialization phase is vision extraction, not requirements gathering. You're helping the researcher discover and articulate their core argument. This isn't a contract negotiation — it's collaborative thinking.
+
+<philosophy>
+**You are a thinking partner, not an interviewer.**
+
+The researcher often has a fuzzy idea. Your job is to help them sharpen it. Ask questions that make them think "oh, I hadn't considered that angle" or "yes, that's exactly my contribution."
+
+Don't interrogate. Collaborate.
+</philosophy>
+
+<critical_rule>
+**ALL questions MUST use AskUserQuestion.**
+
+Never ask questions inline as plain text. Every exploration question uses the AskUserQuestion tool with thoughtful options that help the researcher articulate their vision.
+
+This applies to:
+- Opening questions ("What's the core argument?")
+- Follow-up questions ("You mentioned X — what would that imply?")
+- Sharpening questions ("What's the single key contribution?")
+- Boundary questions ("What's out of scope?")
+- Decision gates ("Ready to proceed?")
+
+The AskUserQuestion format helps researchers think by presenting concrete options to react to, rather than facing a blank text field.
+</critical_rule>
+
+<conversation_arc>
+**1. Open**
+
+Use AskUserQuestion:
+- header: "Core Argument"
+- question: "What is the main argument or contribution of your paper?"
+- options: Contextual starting points if available, otherwise broad categories + "Let me describe it"
+
+Let them respond. Then follow up based on what they said.
+
+**2. Follow the thread**
+
+Whatever they said — dig into it. What's the key insight? What gap does this fill?
+
+Use AskUserQuestion with options that probe what they mentioned:
+- header: "[Topic they mentioned]"
+- question: "You mentioned [X] — what's the key insight there?"
+- options: 2-3 interpretations of what they might mean + "Something else"
+
+**3. Sharpen the core**
+
+Help them distinguish the essential from the nice-to-have.
+
+Use AskUserQuestion:
+- header: "Key Contribution"
+- question: "If reviewers remember one thing, what should it be?"
+- options: Key aspects they've mentioned + "The methodology" + "The findings" + "Something else"
+
+**4. Find the boundaries**
+
+What is this paper NOT about? Explicit exclusions prevent scope creep.
+
+Use AskUserQuestion:
+- header: "Scope"
+- question: "What's explicitly NOT in this paper?"
+- options: Tempting tangents + "Nothing specific" + "Let me list them"
+
+**5. Ground in reality**
+
+Only ask about constraints that actually exist.
+
+Use AskUserQuestion:
+- header: "Constraints"
+- question: "Any hard constraints?"
+- options: ["Page/word limit", "Submission deadline", "Data limitations", "None", "Multiple constraints"]
+</conversation_arc>
+
+<academic_specific_probes>
+**"It's a contribution to the field"** →
+- header: "Contribution"
+- question: "Contribution how?"
+- options: ["New method", "New findings", "Challenges existing view", "Synthesizes existing work", "Let me describe"]
+
+**"It fills a gap"** →
+- header: "Gap"
+- question: "What gap specifically?"
+- options: ["Method gap", "Data gap", "Theory gap", "Application gap", "Let me describe"]
+
+**"It's important for practitioners"** →
+- header: "Practical Impact"
+- question: "What would change for practitioners?"
+- options: ["New technique they can use", "Changes how they think", "Saves time/money", "Let me describe"]
+
+**Venue targeting:**
+- header: "Target Venue"
+- question: "What's the target venue?"
+- options: [Common venues for their field + "Undecided" + "Let me specify"]
+</academic_specific_probes>
+
+<coverage_check>
+By the end of questioning, you should understand:
+
+- [ ] What the core argument/contribution is (the thesis)
+- [ ] Why this matters (the significance)
+- [ ] Who the audience is (even if broad field)
+- [ ] What evidence supports it (data, analysis)
+- [ ] What's NOT in scope (boundaries)
+- [ ] Any real constraints (page limits, deadlines)
+- [ ] What exists already (building on prior work?)
+
+If gaps remain, weave questions naturally into the conversation.
+</coverage_check>
+
+<decision_gate>
+When you feel you understand the vision, use AskUserQuestion:
+
+- header: "Ready?"
+- question: "Ready to create PROJECT.md, or explore more?"
+- options (ALL THREE REQUIRED):
+  - "Create PROJECT.md" - Finalize and continue
+  - "Ask more questions" - I'll dig into areas we haven't covered
+  - "Let me add context" - You have more to share
+
+Loop until "Create PROJECT.md" selected.
+</decision_gate>
+
+<anti_patterns>
+- **Interrogation** - Firing questions without building on answers
+- **Checklist walking** - Going through domains regardless of conversation flow
+- **Academic speak** - "What are your hypotheses?" before understanding the idea
+- **Rushing** - Minimizing questions to get to "the writing"
+- **Assuming** - Filling gaps with assumptions instead of asking
+- **Method-first** - Asking about methodology before understanding the question
+- **Shallow acceptance** - Taking vague answers without probing for specifics
+</anti_patterns>
+</questioning_guide>

package/write-the-f-paper/references/research-pitfalls.md

@@ -0,0 +1,208 @@
+<research_pitfalls>
+
+<purpose>
+This document catalogs literature research mistakes and provides verification strategies for academic writing.
+</purpose>
+
+<known_pitfalls>
+
+<pitfall_citation_scope>
+**What**: Citing a paper for a claim it doesn't actually make
+**Example**: Citing Smith2023 for "effect size of 0.5" when Smith2023 reports a different study
+**Why it happens**: Relying on secondary sources or memory instead of checking primary source
+**Prevention**:
+```xml
+<verification_checklist>
+**CRITICAL**: For every citation:
+□ Have I read the actual source (not just abstract)?
+□ Does the source actually say what I'm claiming?
+□ Is the page/section reference correct?
+□ Am I citing the original source (not a secondary mention)?
+</verification_checklist>
+```
+</pitfall_citation_scope>
+
+<pitfall_outdated_literature>
+**What**: Citing outdated findings that have been superseded
+**Example**: Citing a 2010 meta-analysis when a 2023 one exists with different conclusions
+**Why it happens**: Not checking for recent literature updates
+**Prevention**:
+```xml
+<verification_checklist>
+□ Search for systematic reviews/meta-analyses (most current)
+□ Check citation counts and "cited by" for newer work
+□ Verify no replication failures or corrections exist
+□ Ensure methodology hasn't been superseded
+</verification_checklist>
+```
+</pitfall_outdated_literature>
+
+<pitfall_cherry_picking>
+**What**: Only citing sources that support your argument, ignoring contradictory evidence
+**Example**: Claiming "research consistently shows X" while ignoring studies showing not-X
+**Why it happens**: Confirmation bias, incomplete literature search
+**Prevention**:
+```xml
+<verification_checklist>
+□ Search for contradictory evidence explicitly
+□ Check for debate/controversy in the field
+□ Include limitations and alternative interpretations
+□ Acknowledge conflicting findings in Discussion
+</verification_checklist>
+```
+</pitfall_cherry_picking>
+
+<pitfall_misattribution>
+**What**: Attributing ideas to wrong sources or claiming originality for existing ideas
+**Example**: Claiming "we are the first to..." when prior work exists
+**Why it happens**: Incomplete literature review
+**Prevention**:
+```xml
+<verification_checklist>
+□ Search for prior work using multiple query formulations
+□ Check key papers' references for relevant prior work
+□ Verify "first" claims with thorough search
+□ When in doubt, phrase as "to our knowledge"
+</verification_checklist>
+```
+</pitfall_misattribution>
+
+<pitfall_source_quality>
+**What**: Citing low-quality or non-peer-reviewed sources for empirical claims
+**Example**: Citing a blog post or preprint for established facts
+**Why it happens**: First search result used without quality check
+**Prevention**:
+```xml
+<source_verification>
+For empirical claims:
+- [ ] Peer-reviewed journal (preferred)
+- [ ] Published conference proceedings (acceptable)
+- [ ] Government/institutional reports (for statistics)
+- [ ] Preprints only if noting "not peer-reviewed"
+</source_verification>
+```
+</pitfall_source_quality>
+
+<pitfall_false_consensus>
+**What**: Claiming broad consensus when field is actually divided
+**Example**: "It is well established that..." when significant debate exists
+**Why it happens**: Exposure to limited subset of literature
+**Prevention**:
+```xml
+<verification_checklist>
+□ Check for review papers discussing field debates
+□ Search for "critique of X" or "X controversy"
+□ Verify claim with multiple independent sources
+□ Use hedged language if consensus uncertain
+</verification_checklist>
+```
+</pitfall_false_consensus>
+
+<pitfall_effect_size_conflation>
+**What**: Confusing statistical significance with practical importance
+**Example**: Citing p < .001 without noting tiny effect size
+**Why it happens**: Focus on p-values over effect sizes
+**Prevention**:
+```xml
+<verification_checklist>
+□ Report effect sizes, not just significance
+□ Check sample size (large samples find tiny effects)
+□ Compare to meaningful benchmarks in field
+□ Note practical vs. statistical significance
+</verification_checklist>
+```
+</pitfall_effect_size_conflation>
+
+<pitfall_definitional_drift>
+**What**: Using terms inconsistently or differently from cited sources
+**Example**: Your definition of "resilience" differs from cited paper's definition
+**Why it happens**: Not checking how sources define key terms
+**Prevention**:
+```xml
+<verification_checklist>
+□ Define key terms explicitly in paper
+□ Check cited sources use terms same way
+□ Note when sources use different definitions
+□ Be consistent throughout your paper
+</verification_checklist>
+```
+</pitfall_definitional_drift>
+</known_pitfalls>
+
+<red_flags>
+
+<red_flag_all_support>
+**Warning**: All cited sources perfectly support your claims
+**Problem**: Real literature has nuance and contradictions
+**Action**: Look harder for alternative viewpoints
+</red_flag_all_support>
+
+<red_flag_old_citations>
+**Warning**: Most citations are >5-10 years old in active field
+**Problem**: May be missing recent developments
+**Action**: Update literature search with recent date filters
+</red_flag_old_citations>
+
+<red_flag_secondary_citations>
+**Warning**: "Smith (2020) reports that Jones (2018) found..."
+**Problem**: Telephone game introduces errors
+**Action**: Go to primary source (Jones 2018) directly
+</red_flag_secondary_citations>
+
+<red_flag_no_limitations>
+**Warning**: No limitations mentioned for cited studies
+**Problem**: All studies have limitations
+**Action**: Note relevant limitations, especially for key claims
+</red_flag_no_limitations>
+
+<red_flag_unanimous_field>
+**Warning**: "All researchers agree..." or "The literature clearly shows..."
+**Problem**: Fields rarely have complete consensus
+**Action**: Verify with meta-analyses, check for debates
+</red_flag_unanimous_field>
+</red_flags>
+
+<literature_search_best_practices>
+
+**1. Use multiple databases:**
+- Google Scholar (broad)
+- Field-specific databases (PubMed, PsycINFO, etc.)
+- Citation tracking (forward and backward)
+
+**2. Use multiple query formulations:**
+- Synonyms and related terms
+- Different orderings
+- Include/exclude specific contexts
+
+**3. Check "cited by" for key papers:**
+- Finds newer work building on foundations
+- Reveals debates and critiques
+
+**4. Read abstracts critically:**
+- Distinguish methods, findings, interpretations
+- Note sample sizes and contexts
+
+**5. Maintain bibliography as you go:**
+- Update sources/literature.md continuously
+- Note relevance and key quotes
+- Track what you've actually read vs. skimmed
+</literature_search_best_practices>
+
+<quick_reference>
+
+Before finalizing citations, verify:
+
+- [ ] Primary source actually read (not just abstract)
+- [ ] Claim accurately reflects source's findings
+- [ ] No newer work supersedes this finding
+- [ ] Contradictory evidence acknowledged
+- [ ] Source quality appropriate for claim type
+- [ ] Key terms used consistently with sources
+- [ ] Effect sizes reported where relevant
+- [ ] Consensus claims verified with multiple sources
+- [ ] "First to" claims thoroughly searched
+- [ ] All references formatted correctly
+
+**Living Document**: Update after each citation error discovered
+</quick_reference>
+</research_pitfalls>

package/write-the-f-paper/templates/config.json

@@ -0,0 +1,30 @@
+{
+  "mode": "interactive",
+  "depth": "standard",
+  "document_type": "paper",
+  "output_format": "markdown",
+  "gates": {
+    "confirm_project": true,
+    "confirm_sections": true,
+    "confirm_roadmap": true,
+    "confirm_outline": true,
+    "confirm_plan": true,
+    "write_next_plan": true,
+    "issues_review": true,
+    "confirm_transition": true
+  },
+  "writing": {
+    "claude_mode": "co-author",
+    "citation_style": "apa",
+    "verify_on_complete": true
+  },
+  "verification": {
+    "citation_check": true,
+    "coherence_check": true,
+    "rubric_check": true
+  },
+  "safety": {
+    "always_confirm_destructive": true,
+    "backup_before_major_edits": true
+  }
+}

package/write-the-f-paper/templates/context.md

@@ -0,0 +1,179 @@
+# Section Context Template
+
+Template for `.planning/sections/XX-name/{section}-CONTEXT.md` - captures the user's vision for a section.
+
+**Purpose:** Document how the user imagines the section working. This is vision context, not technical analysis. Research details come from the research workflow.
+
+---
+
+## File Template
+
+```markdown
+# Section [X]: [Name] - Context
+
+**Gathered:** [date]
+**Status:** [Ready for research / Ready for planning]
+
+<vision>
+## How This Section Should Work
+
+[User's description of how they imagine this section functioning for the reader. What should the reader understand after reading it? What's the "story" of this section? This is the "pitch" version, not the detailed outline.]
+
+</vision>
+
+<essential>
+## What Must Be Nailed
+
+[The core of this section. If we only get one thing right, what is it? What's the non-negotiable that makes this section successful?]
+
+- [Essential thing 1]
+- [Essential thing 2]
+- [Essential thing 3 if applicable]
+
+</essential>
+
+<boundaries>
+## What's Out of Scope
+
+[Explicit exclusions for this section. What are we NOT covering? Where does this section end and the next begin?]
+
+- [Not covering X - that's Section Y]
+- [Not including Z - deferred to future work]
+- [Explicitly excluding W]
+
+</boundaries>
+
+<specifics>
+## Specific Ideas
+
+[Any particular things the user has in mind. References to papers they like. Specific arguments or evidence to include. "I want it to flow like X paper" or "The key evidence is Y."]
+
+[If none: "No specific requirements - open to standard approaches"]
+
+</specifics>
+
+<sources>
+## Available Sources
+
+[What material the user has available for this section]
+
+- Literature: [Key papers to cite]
+- Data: [Figures, tables, statistics available]
+- Prior drafts: [Existing text to incorporate]
+
+</sources>
+
+<notes>
+## Additional Context
+
+[Anything else captured during the discussion that doesn't fit above. User's priorities, concerns mentioned, relevant background.]
+
+[If none: "No additional notes"]
+
+</notes>
+
+---
+
+*Section: XX-name*
+*Context gathered: [date]*
+```
+
+<good_examples>
+```markdown
+# Section 3: Methods - Context
+
+**Gathered:** 2025-01-20
+**Status:** Ready for research
+
+<vision>
+## How This Section Should Work
+
+When reviewers read this methods section, they should feel confident they could replicate the study. I want it to feel rigorous but not tedious - every detail should earn its place. The flow should be: who participated, what they did, and how we analyzed it.
+
+The section should anticipate reviewer questions about validity and address them preemptively.
+
+</vision>
+
+<essential>
+## What Must Be Nailed
+
+- **Reproducibility** - Someone could replicate this study from the methods alone
+- **Validity** - Address potential confounds and how we controlled for them
+- **Ethical compliance** - IRB approval and participant consent clear
+
+</essential>
+
+<boundaries>
+## What's Out of Scope
+
+- Detailed results (just analysis approach here)
+- Extended rationale for method choices (brief is fine)
+- Preliminary/pilot study details (not relevant)
+
+</boundaries>
+
+<specifics>
+## Specific Ideas
+
+- I like how Smith (2023) structured their participant section - demographics first, then inclusion criteria
+- We should include the exact prompt text used (reviewer always asks)
+- The analysis follows Cohen's framework - cite appropriately
+
+</specifics>
+
+<sources>
+## Available Sources
+
+- Literature: Cohen (2020) for analysis framework, Smith (2023) for structure example
+- Data: Participant demographics table ready, Figure 2 (study flow) ready
+- Prior drafts: Had a rough methods draft in proposal - reusable but needs expansion
+
+</sources>
+
+<notes>
+## Additional Context
+
+User is worried reviewers will question the sample size (N=45). Need to address power analysis or limitation. Also mentioned that the IRB number is #2024-0123 (needs to appear in text).
+
+</notes>
+
+---
+
+*Section: 03-methods*
+*Context gathered: 2025-01-20*
+```
+</good_examples>
+
+<guidelines>
+**This template captures VISION, not detailed outlines.**
+
+The user is the visionary. They know:
+- How they imagine the section working for readers
+- What it should accomplish
+- What's essential vs nice-to-have
+- References to papers they like
+- Sources they have available
+
+The user does NOT know (and shouldn't be asked):
+- Exact paragraph structure (Claude figures out during planning)
+- Citation formatting (Claude handles)
+- Transitions between paragraphs (Claude writes)
+- Word allocation within section (Claude calculates)
+
+**Content should read like:**
+- A researcher describing what they want the section to do
+- "When readers finish this section, they should understand..."
+- "The most important thing to convey is..."
+- "I want this to feel like Smith's methods, not Jones's"
+
+**Content should NOT read like:**
+- A paragraph-by-paragraph outline
+- A list of citations to include
+- Word count targets
+- Detailed structure
+
+**After creation:**
+- File lives in section directory: `.planning/sections/XX-name/{section}-CONTEXT.md`
+- Research phase adds investigation results if needed
+- Planning phase creates executable tasks informed by both vision AND research
+</guidelines>

package/write-the-f-paper/templates/continue-here.md

@@ -0,0 +1,142 @@
+# Continue-Here Template
+
+Copy and fill this structure for `.planning/sections/XX-name/.continue-here.md`:
+
+```yaml
+---
+section: XX-name
+task: 3
+total_tasks: 7
+status: in_progress
+last_updated: 2025-01-15T14:30:00Z
+---
+```
+
+```markdown
+<current_state>
+[Where exactly are we in the writing? What's the immediate context?]
+</current_state>
+
+<completed_work>
+[What got written this session - be specific]
+
+- Task 1: [name] - Done
+- Task 2: [name] - Done
+- Task 3: [name] - In progress, [what's done on it]
+</completed_work>
+
+<remaining_work>
+[What's left in this section]
+
+- Task 3: [name] - [what's left to write]
+- Task 4: [name] - Not started
+- Task 5: [name] - Not started
+</remaining_work>
+
+<decisions_made>
+[Key decisions and why - so next session doesn't re-debate]
+
+- Decided to use [X] framing because [reason]
+- Chose [approach] over [alternative] because [reason]
+</decisions_made>
+
+<word_count>
+Current: [X] words written
+Target: [Y] words for section
+Remaining budget: [Z] words
+</word_count>
+
+<blockers>
+[Anything stuck or waiting on external factors]
+
+- [Blocker 1]: [status/workaround]
+</blockers>
+
+<context>
+[Mental state, "vibe", anything that helps resume smoothly]
+
+[What were you thinking about? What was the plan?
+This is the "pick up exactly where you left off" context.]
+</context>
+
+<next_action>
+[The very first thing to do when resuming]
+
+Start with: [specific action]
+</next_action>
+```
+
+<yaml_fields>
+Required YAML frontmatter:
+
+- `section`: Directory name (e.g., `02-methods`)
+- `task`: Current task number
+- `total_tasks`: How many tasks in section
+- `status`: `in_progress`, `blocked`, `almost_done`
+- `last_updated`: ISO timestamp
+</yaml_fields>
+
+<guidelines>
+- Be specific enough that a fresh Claude instance understands immediately
+- Include WHY decisions were made, not just what
+- Include word count progress so next session knows budget
+- The `<next_action>` should be actionable without reading anything else
+- This file gets DELETED after resume - it's not permanent storage
+</guidelines>
+
+<example>
+```yaml
+---
+section: 03-methods
+task: 4
+total_tasks: 6
+status: in_progress
+last_updated: 2025-01-20T16:45:00Z
+---
+```
+
+```markdown
+<current_state>
+Writing the Analysis subsection of Methods. Just finished the Measures subsection. Have participant demographics and procedures done.
+</current_state>
+
+<completed_work>
+- Task 1: Participants subsection - Done (demographics, N=45, inclusion criteria)
+- Task 2: Procedures subsection - Done (study flow, timing, conditions)
+- Task 3: Measures subsection - Done (all instruments described with citations)
+- Task 4: Analysis subsection - In progress, wrote intro paragraph about approach
+</completed_work>
+
+<remaining_work>
+- Task 4: Analysis - Need to describe specific statistical tests and software
+- Task 5: Ethical considerations - IRB statement, consent process
+- Task 6: Final polish - Transitions, word count trimming
+</remaining_work>
+
+<decisions_made>
+- Used Cohen (2020) framework for analysis - matches prior literature
+- Decided NOT to include power analysis in main text (will add to supplementary if reviewers ask)
+- Put measures before analysis (reviewer suggested this order)
+</decisions_made>
+
+<word_count>
+Current: 892 words written
+Target: 1200 words for section
+Remaining budget: 308 words
+</word_count>
+
+<blockers>
+None currently
+</blockers>
+
+<context>
+The analysis section needs to justify N=45 indirectly through effect size discussion. Main worry is reviewer pushback on sample size. Tone should be confident but not dismissive of limitation.
+
+Planning to use "Following Cohen (2020), we employed..." structure for consistency.
+</context>
+
+<next_action>
+Start with: Continue Task 4 - write the specific statistical tests paragraph (t-tests for group comparisons, regression for predictors)
+</next_action>
+```
+</example>