wtf-p 0.1.0

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

@@ -0,0 +1,223 @@
+# Continuation Format
+
+Standard format for presenting next steps after completing a command or workflow.
+
+## Core Structure
+
+```
+---
+
+## ▶ Next Up
+
+**{identifier}: {name}** — {one-line description}
+
+`{command to copy-paste}`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `{alternative option 1}` — description
+- `{alternative option 2}` — description
+
+---
+```
+
+## Format Rules
+
+1. **Always show what it is** — name + description, never just a command path
+2. **Pull context from source** — ROADMAP.md for sections, PLAN.md `<objective>` for plans
+3. **Command in inline code** — backticks, easy to copy-paste, renders as clickable link
+4. **`/clear` explanation** — always include, keeps it concise but explains why
+5. **"Also available" not "Other options"** — sounds more app-like
+6. **Visual separators** — `---` above and below to make it stand out
+
+## Variants
+
+### Execute Next Plan
+
+```
+---
+
+## ▶ Next Up
+
+**02-01: Methods Overview** — Draft study design and participant sections
+
+`/wtfp:write-section .planning/sections/02-methods/02-01-PLAN.md`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- Review plan before executing
+- `/wtfp:list-assumptions 2` — check assumptions
+
+---
+```
+
+### Plan a Section
+
+```
+---
+
+## ▶ Next Up
+
+**Section 2: Methods** — Describe study design, participants, and procedures
+
+`/wtfp:plan-section 2`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `/wtfp:discuss-section 2` — gather context first
+- `/wtfp:research-gap 2` — investigate literature
+
+---
+```
+
+### Section Complete, Ready for Next
+
+```
+---
+
+## ✓ Section 2 Complete
+
+2/2 plans executed
+800 words written
+
+## ▶ Next Up
+
+**Section 3: Results** — Present main findings and analyses
+
+`/wtfp:plan-section 3`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `/wtfp:review-section 2` — verify before continuing
+- `/wtfp:discuss-section 3` — gather context first
+
+---
+```
+
+### Multiple Equal Options
+
+When there's no clear primary action:
+
+```
+---
+
+## ▶ Next Up
+
+**Section 3: Results** — Present main findings and analyses
+
+**To plan directly:** `/wtfp:plan-section 3`
+
+**To discuss context first:** `/wtfp:discuss-section 3`
+
+**To research literature:** `/wtfp:research-gap 3`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+```
+
+### Draft Complete
+
+```
+---
+
+## 🎉 Draft Complete
+
+All 6 sections written
+Total: 6,500 words
+
+## ▶ Next Up
+
+**Review & Polish** — Verify and prepare for submission
+
+`/wtfp:review-section` — run full verification
+`/wtfp:export-latex` — generate LaTeX output
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `/wtfp:submit-milestone "draft-1"` — archive this version
+
+---
+```
+
+## Pulling Context
+
+### For sections (from ROADMAP.md):
+
+```markdown
+### 2. Methods
+- **Goal**: Describe study design, participants, and procedures
+- **Word Target**: 1500 words
+```
+
+Extract: `**Section 2: Methods** — Describe study design, participants, and procedures`
+
+### For plans (from PLAN.md `<objective>`):
+
+```xml
+<objective>
+Draft the study design and participant description.
+
+Purpose: Establish methodological rigor and replicability.
+Output: 800 words covering design, participants, procedures.
+</objective>
+```
+
+Extract: `**02-01: Methods Overview** — Draft study design and participant sections`
+
+## Anti-Patterns
+
+### Don't: Command-only (no context)
+
+```
+## To Continue
+
+Run `/clear`, then paste:
+/wtfp:write-section .planning/sections/02-methods/02-01-PLAN.md
+```
+
+User has no idea what 02-01 is about.
+
+### Don't: Missing /clear explanation
+
+```
+`/wtfp:plan-section 3`
+
+Run /clear first.
+```
+
+Doesn't explain why. User might skip it.
+
+### Don't: "Other options" language
+
+```
+Other options:
+- Review roadmap
+```
+
+Sounds like an afterthought. Use "Also available:" instead.
+
+### Don't: Fenced code blocks for commands
+
+```
+```
+/wtfp:plan-section 3
+```
+```
+
+Fenced blocks inside templates create nesting ambiguity. Use inline backticks instead.

package/write-the-f-paper/references/git-integration.md

@@ -0,0 +1,241 @@
+<overview>
+Git integration for WTF-P framework.
+</overview>
+
+<core_principle>
+
+**Commit outcomes, not process.**
+
+The git log should read like a changelog of what was written, not a diary of planning activity.
+</core_principle>
+
+<commit_points>
+
+| Event                   | Commit? | Why                                              |
+| ----------------------- | ------- | ------------------------------------------------ |
+| PROJECT + OUTLINE created | YES   | Paper initialization                             |
+| PLAN.md created         | NO      | Intermediate - commit with plan completion       |
+| RESEARCH.md created     | NO      | Intermediate                                     |
+| CONTEXT.md created      | NO      | Intermediate                                     |
+| **Writing task completed** | YES  | Atomic unit of work (1 commit per task)         |
+| **Plan completed**      | YES     | Metadata commit (SUMMARY + STATE + ROADMAP)     |
+| Handoff created         | YES     | WIP state preserved                              |
+
+</commit_points>
+
+<git_check>
+
+```bash
+[ -d .git ] && echo "GIT_EXISTS" || echo "NO_GIT"
+```
+
+If NO_GIT: Run `git init` silently. WTF-P projects always get their own repo.
+</git_check>
+
+<commit_formats>
+
+<format name="initialization">
+## Paper Initialization (project + outline together)
+
+```
+docs: initialize [paper-title] ([N] sections)
+
+[One-liner thesis from PROJECT.md]
+
+Sections:
+1. [section-name]: [goal]
+2. [section-name]: [goal]
+3. [section-name]: [goal]
+```
+
+What to commit:
+
+```bash
+git add .planning/
+git commit
+```
+
+</format>
+
+<format name="task-completion">
+## Task Completion (During Plan Execution)
+
+Each writing task gets its own commit immediately after completion.
+
+```
+{type}({section}-{plan}): {task-name}
+
+- [Key content 1]
+- [Key content 2]
+- [Key content 3]
+```
+
+**Commit types:**
+- `write` - New content written
+- `revise` - Content revised/improved
+- `cite` - Citations added
+- `polish` - Prose refined
+- `docs` - Metadata updates
+
+**Examples:**
+
+```bash
+# Standard writing task
+git add paper/introduction.md
+git commit -m "write(01-01): draft introduction opening
+
+- Establishes research gap (~200 words)
+- Cites Smith2023 and Jones2022
+- Transitions to thesis statement
+"
+
+# Revision task
+git add paper/methods.md
+git commit -m "revise(02-01): strengthen methods clarity
+
+- Added participant demographics
+- Clarified procedure timeline
+- Added missing protocol details
+"
+
+# Citation task
+git add paper/discussion.md .planning/sources/literature.md
+git commit -m "cite(04-01): add supporting citations
+
+- Added Chen2024 for alternative interpretation
+- Updated literature index
+"
+```
+
+</format>
+
+<format name="plan-completion">
+## Plan Completion (After All Tasks Done)
+
+After all tasks committed, one final metadata commit captures plan completion.
+
+```
+docs({section}-{plan}): complete [section-name] plan
+
+Tasks completed: [N]/[N]
+Words written: [X]
+- [Task 1 name]
+- [Task 2 name]
+- [Task 3 name]
+
+SUMMARY: .planning/sections/XX-name/{section}-{plan}-SUMMARY.md
+```
+
+What to commit:
+
+```bash
+git add .planning/sections/XX-name/{section}-{plan}-PLAN.md
+git add .planning/sections/XX-name/{section}-{plan}-SUMMARY.md
+git add .planning/STATE.md
+git add .planning/ROADMAP.md
+git commit
+```
+
+**Note:** Paper content NOT included - already committed per-task.
+
+</format>
+
+<format name="handoff">
+## Handoff (WIP)
+
+```
+wip: [section-name] paused at task [X]/[Y]
+
+Current: [task name]
+[If blocked:] Blocked: [reason]
+```
+
+What to commit:
+
+```bash
+git add .planning/
+git commit
+```
+
+</format>
+</commit_formats>
+
+<example_log>
+
+**Per-task commits for academic writing:**
+```
+# Section 04 - Discussion
+1a2b3c docs(04-01): complete discussion plan
+4d5e6f write(04-01): draft implications and future work
+7g8h9i write(04-01): draft interpretation of findings
+0j1k2l write(04-01): draft summary of results
+
+# Section 03 - Results
+3m4n5o docs(03-01): complete results plan
+6p7q8r write(03-01): draft supporting analyses
+9s0t1u write(03-01): draft main findings
+
+# Section 02 - Methods
+5y6z7a docs(02-01): complete methods plan
+8b9c0d write(02-01): draft analysis approach
+1e2f3g write(02-01): draft procedures
+4h5i6j write(02-01): draft participants
+
+# Section 01 - Introduction
+7k8l9m docs(01-01): complete introduction plan
+0n1o2p write(01-01): draft thesis and roadmap
+3q4r5s write(01-01): draft research gap
+6t7u8v write(01-01): draft opening hook
+
+# Initialization
+9w0x1y docs: initialize research-paper (6 sections)
+```
+
+Each plan produces 3-5 commits (tasks + metadata). Clear, granular, recoverable.
+
+</example_log>
+
+<anti_patterns>
+
+**Still don't commit (intermediate artifacts):**
+- PLAN.md creation (commit with plan completion)
+- RESEARCH.md (intermediate)
+- CONTEXT.md (intermediate)
+- Minor planning tweaks
+- "Fixed typo in outline"
+
+**Do commit (outcomes):**
+- Each writing task completion (write/revise/cite/polish)
+- Plan completion metadata (docs)
+- Paper initialization (docs)
+
+**Key principle:** Commit written content and shipped outcomes, not planning process.
+
+</anti_patterns>
+
+<commit_strategy_rationale>
+
+## Why Per-Task Commits?
+
+**Context engineering for AI:**
+- Git history becomes primary context source for future Claude sessions
+- `git log --grep="{section}-{plan}"` shows all work for a plan
+- `git diff <hash>^..<hash>` shows exact changes per task
+- Less reliance on parsing SUMMARY.md = more context for actual writing
+
+**Failure recovery:**
+- Task 1 committed ✅, Task 2 failed ❌
+- Claude in next session: sees task 1 complete, can retry task 2
+- Can `git reset --hard` to last successful task
+
+**Revision tracking:**
+- Clear record of when each part was written
+- Easy to see evolution of arguments
+- Each commit is independently revertable
+
+**Observability:**
+- Solo writer + Claude workflow benefits from granular attribution
+- Atomic commits are git best practice
+- Writing evolution is clear
+
+</commit_strategy_rationale>

package/write-the-f-paper/references/imrad-structure.md

@@ -0,0 +1,212 @@
+<imrad_structure>
+Standard academic paper structure for research articles. IMRaD = Introduction, Methods, Results, and Discussion.
+
+<overview>
+IMRaD is the dominant structure for empirical research papers in sciences, social sciences, and many other fields. Understanding this structure helps plan writing efficiently.
+</overview>
+
+<sections>
+
+<section name="abstract">
+## Abstract (150-300 words)
+
+**Purpose:** Standalone summary of the entire paper.
+
+**Components:**
+1. **Background/Context** (1-2 sentences): Why this research matters
+2. **Objective/Question** (1 sentence): What you investigated
+3. **Methods** (1-2 sentences): How you did it
+4. **Results** (2-3 sentences): What you found
+5. **Conclusions** (1-2 sentences): What it means
+
+**Writing mode:** Reviewer (user writes, Claude critiques)
+**When to write:** LAST - after all other sections
+
+**Common mistakes:**
+- Too long (>300 words for most venues)
+- Vague results ("significant findings were observed")
+- Missing methods
+- Conclusions that go beyond findings
+</section>
+
+<section name="introduction">
+## Introduction (10-15% of paper)
+
+**Purpose:** Establish context, identify gap, state contribution.
+
+**Structure (the "funnel"):**
+1. **Hook** (1-2 paragraphs): Why this topic matters, broad context
+2. **Literature context** (2-4 paragraphs): What's known, key prior work
+3. **Gap identification** (1-2 paragraphs): What's missing, the problem
+4. **Thesis/Contribution** (1 paragraph): What you did and why it matters
+5. **Roadmap** (1 paragraph, optional): Paper structure preview
+
+**Writing mode:** Co-Author → Reviewer
+**Typical plans:** 2-3
+
+**Common mistakes:**
+- Too broad opening (doesn't connect to specific research)
+- Insufficient citations for claims
+- Gap not clearly articulated
+- Thesis buried or unclear
+</section>
+
+<section name="methods">
+## Methods (20-30% of paper)
+
+**Purpose:** Enable replication, establish rigor.
+
+**Typical subsections:**
+1. **Study Design/Overview**: Type of study, overall approach
+2. **Participants/Sample**: Who/what was studied, selection criteria
+3. **Materials/Instruments**: What tools, measures, materials used
+4. **Procedure**: Step-by-step what happened
+5. **Data Analysis**: How data was analyzed
+
+**Writing mode:** Co-Author (often procedural)
+**Typical plans:** 2-3
+
+**Common mistakes:**
+- Insufficient detail for replication
+- Missing rationale for choices
+- Results in methods section
+- Vague ("standard procedures were followed")
+</section>
+
+<section name="results">
+## Results (20-30% of paper)
+
+**Purpose:** Present findings objectively, without interpretation.
+
+**Structure:**
+1. **Descriptive statistics/Overview**: Sample characteristics, basic numbers
+2. **Main findings**: Primary results addressing research question
+3. **Secondary/Supporting findings**: Additional analyses
+4. **Figures and tables**: Visual presentation of key data
+
+**Writing mode:** Scaffold (Claude structures, user fills specifics)
+**Typical plans:** 2
+
+**Common mistakes:**
+- Interpretation in results (belongs in Discussion)
+- Repeating all table/figure data in text
+- Not addressing all research questions
+- Vague statistics ("p < .05" without effect sizes)
+</section>
+
+<section name="discussion">
+## Discussion (20-30% of paper)
+
+**Purpose:** Interpret findings, connect to literature, acknowledge limitations.
+
+**Structure (the "reverse funnel"):**
+1. **Summary** (1 paragraph): Key findings recap
+2. **Interpretation** (2-4 paragraphs): What findings mean
+3. **Relation to prior work** (2-3 paragraphs): How this fits/extends literature
+4. **Implications** (1-2 paragraphs): Practical/theoretical significance
+5. **Limitations** (1-2 paragraphs): Honest acknowledgment of weaknesses
+6. **Future directions** (1 paragraph): What comes next
+7. **Conclusion** (1 paragraph): Final takeaway (may be separate section)
+
+**Writing mode:** Reviewer (user writes, Claude critiques)
+**Typical plans:** 2-3
+
+**Common mistakes:**
+- Repeating results without interpretation
+- Overstating conclusions
+- Limitations as afterthought
+- Not connecting to prior work
+</section>
+
+<section name="conclusion">
+## Conclusion (if separate, 5% of paper)
+
+**Purpose:** Final synthesis and takeaway.
+
+**Components:**
+1. Main contribution restated
+2. Key implications
+3. Final thought/call to action
+
+**Writing mode:** Reviewer
+**Typical plans:** 1
+
+**Note:** Many papers combine conclusion into Discussion. Check venue guidelines.
+</section>
+</sections>
+
+<other_sections>
+
+**References/Bibliography**
+- Not written, but cited throughout
+- Format per venue style guide
+- Track in sources/literature.md
+
+**Acknowledgments**
+- Funding sources
+- Contributors who don't meet authorship criteria
+- Write last, verify requirements
+
+**Appendices** (if needed)
+- Supplementary materials
+- Detailed methods
+- Additional analyses
+</other_sections>
+
+<section_dependencies>
+
+```
+Abstract ← (depends on all)
+         ↑
+Introduction → Methods → Results → Discussion → Conclusion
+                          ↑           ↑
+                          |-----------| (Discussion interprets Results)
+```
+
+**Recommended writing order:**
+1. Methods (most concrete)
+2. Results (report what happened)
+3. Introduction (frame the contribution)
+4. Discussion (interpret findings)
+5. Conclusion (synthesize)
+6. Abstract (summarize all)
+
+This order lets you know what you're introducing before writing the intro, and what you're discussing before the discussion.
+</section_dependencies>
+
+<word_budget_template>
+
+| Section | % of Paper | 8000-word Paper | 5000-word Paper |
+|---------|------------|-----------------|-----------------|
+| Abstract | 2-3% | 200 | 150 |
+| Introduction | 12-15% | 1000 | 650 |
+| Methods | 20-25% | 1800 | 1100 |
+| Results | 20-25% | 1800 | 1100 |
+| Discussion | 25-30% | 2200 | 1400 |
+| Conclusion | 5-8% | 500 | 350 |
+| References | N/A | N/A | N/A |
+
+Adjust based on venue requirements and content needs.
+</word_budget_template>
+
+<variations>
+
+**APA Style** (Psychology, Social Sciences)
+- Standard IMRaD with specific formatting
+- Often has separate Participants and Procedure sections
+
+**Chicago/Humanities**
+- May not follow IMRaD strictly
+- More emphasis on argument structure
+- Thematic organization possible
+
+**Grant Proposals** (not IMRaD)
+- Specific Aims, Background, Approach
+- See grant/ templates
+
+**Conference Papers**
+- Shorter, often 6-8 pages
+- Same structure, compressed
+- May omit some subsections
+</variations>
+</imrad_structure>