wtf-p 0.1.0

package/write-the-f-paper/templates/project-context/argument-structure.md

@@ -0,0 +1,267 @@
+# Argument Structure Template
+
+Template for `.planning/structure/argument-map.md` — the logical structure of your paper.
+
+**Purpose:** Map the logical flow from claims to evidence to conclusions. This is the "skeleton" of your argument that all writing builds upon.
+
+---
+
+## File Template
+
+```markdown
+# Argument Map
+
+**Created:** [date]
+**Last updated:** [date]
+
+## Central Thesis
+
+[The main claim of the paper in one sentence. This is what the entire paper argues for.]
+
+## Supporting Claims
+
+### Claim 1: [Statement]
+
+**What we assert:** [Clear statement of the claim]
+**Evidence:**
+- [Evidence type: empirical/theoretical/logical]
+- [Specific evidence: data, citation, reasoning]
+**Source:** [Citation or "our data/analysis"]
+**Strength:** [Strong / Moderate / Weak]
+**Location:** [Which section presents this]
+
+### Claim 2: [Statement]
+
+**What we assert:** [Clear statement of the claim]
+**Evidence:**
+- [Evidence type]
+- [Specific evidence]
+**Source:** [Citation or source]
+**Strength:** [Strong / Moderate / Weak]
+**Location:** [Which section presents this]
+
+### Claim 3: [Statement]
+
+**What we assert:** [Clear statement of the claim]
+**Evidence:**
+- [Evidence type]
+- [Specific evidence]
+**Source:** [Citation or source]
+**Strength:** [Strong / Moderate / Weak]
+**Location:** [Which section presents this]
+
+[Continue for all major claims...]
+
+## Logical Flow
+
+```
+Claim 1 + Claim 2
+       ↓
+[Intermediate Conclusion 1]
+       +
+    Claim 3
+       ↓
+[Intermediate Conclusion 2]
+       +
+    Claim 4
+       ↓
+[Central Thesis]
+```
+
+## Counterarguments
+
+### Objection 1: [Statement]
+
+**What critics might say:** [The objection]
+**Why it matters:** [Why we need to address it]
+**Our response:** [How we address it]
+**Placement:** [Where in paper we handle this]
+
+### Objection 2: [Statement]
+
+**What critics might say:** [The objection]
+**Why it matters:** [Why we need to address it]
+**Our response:** [How we address it]
+**Placement:** [Where in paper we handle this]
+
+## Gaps and Weaknesses
+
+### Identified Gaps
+
+[Claims that need stronger evidence or acknowledgment as limitations]
+
+- **Gap 1:** [Claim X lacks sufficient evidence]
+  - Current state: [What we have]
+  - Needed: [What would strengthen it]
+  - Plan: [How to address or acknowledge]
+
+- **Gap 2:** [Logical leap between X and Y]
+  - Current state: [The jump we're making]
+  - Needed: [Bridging argument or evidence]
+  - Plan: [How to address]
+
+### Acknowledged Limitations
+
+[Things we're explicitly acknowledging as limitations rather than fixing]
+
+- [Limitation 1]: Acknowledged in [section]
+- [Limitation 2]: Acknowledged in [section]
+
+## Claim-Section Mapping
+
+| Claim | Primary Section | Supporting Sections |
+|-------|-----------------|---------------------|
+| Claim 1 | Introduction | Methods |
+| Claim 2 | Results | Discussion |
+| Claim 3 | Discussion | Conclusion |
+| Thesis | Abstract, Conclusion | Throughout |
+
+---
+
+*Argument map for: [Paper title]*
+*Update when argument structure changes*
+```
+
+<guidelines>
+
+**What belongs in argument-map.md:**
+- The central thesis statement
+- All major claims that support the thesis
+- Evidence for each claim (type and specifics)
+- Logical flow connecting claims to thesis
+- Counterarguments and how you address them
+- Gaps that need attention
+
+**What does NOT belong here:**
+- Full prose (that's the paper itself)
+- Detailed citations (just key references)
+- Section outlines (that's outline.md)
+- Narrative structure (that's narrative-arc.md)
+
+**When to create:**
+- During project initialization
+- After initial literature review
+- Before detailed section planning
+
+**When to update:**
+- When claims change during writing
+- When new evidence is added
+- When counterarguments are identified
+- After major revision
+
+**Claim strength assessment:**
+- Strong: Multiple independent sources, robust evidence
+- Moderate: Good evidence but could be challenged
+- Weak: Needs more support, acknowledged as limitation
+
+**Usage in workflows:**
+- plan-section loads this for context
+- write-section checks claims against this
+- review-section verifies coherence with this
+</guidelines>
+
+<example>
+```markdown
+# Argument Map
+
+**Created:** 2025-01-15
+**Last updated:** 2025-01-20
+
+## Central Thesis
+
+AI-assisted writing tools require discipline-specific frameworks to be effectively adopted in academic research contexts.
+
+## Supporting Claims
+
+### Claim 1: AI writing tools are proliferating rapidly
+
+**What we assert:** The number and sophistication of AI writing tools has grown exponentially since 2022
+**Evidence:**
+- Empirical: Survey data showing 300% increase in tool availability (Smith, 2023)
+- Empirical: Usage statistics from major platforms (Jones, 2024)
+**Source:** Smith (2023), Jones (2024)
+**Strength:** Strong
+**Location:** Introduction (context)
+
+### Claim 2: Current adoption in academia is ad hoc
+
+**What we assert:** Researchers use AI tools inconsistently and without systematic guidance
+**Evidence:**
+- Empirical: Interview data with 45 researchers
+- Empirical: Survey showing 78% report "trial and error" approach
+**Source:** Our study
+**Strength:** Moderate (single study)
+**Location:** Results
+
+### Claim 3: Academic writing has unique constraints not addressed by general tools
+
+**What we assert:** Academic writing requires citation integration, argument rigor, and disciplinary conventions that general AI tools don't support
+**Evidence:**
+- Theoretical: Analysis of academic writing requirements (Author, 2022)
+- Logical: Comparison of tool features vs. academic needs
+**Source:** Author (2022), our analysis
+**Strength:** Strong
+**Location:** Literature Review, Discussion
+
+### Claim 4: A framework improves adoption and outcomes
+
+**What we assert:** Structured guidance leads to more effective and ethical AI tool use
+**Evidence:**
+- Empirical: Pilot study with framework (N=20) vs. control
+- Theoretical: Draws on pedagogical framework literature
+**Source:** Our pilot data
+**Strength:** Moderate (small pilot)
+**Location:** Results, Discussion
+
+## Logical Flow
+
+```
+Claim 1 (tools proliferating) + Claim 2 (adoption is ad hoc)
+       ↓
+[Current state is suboptimal]
+       +
+Claim 3 (academic writing has unique needs)
+       ↓
+[General tools don't meet academic needs]
+       +
+Claim 4 (framework improves outcomes)
+       ↓
+[THESIS: Discipline-specific frameworks needed]
+```
+
+## Counterarguments
+
+### Objection 1: AI writing is cheating
+
+**What critics might say:** Using AI tools in academic writing constitutes plagiarism or academic dishonesty
+**Why it matters:** Common concern that blocks adoption
+**Our response:** Distinguish co-authorship from replacement; framework emphasizes transparency
+**Placement:** Discussion (Ethics subsection)
+
+### Objection 2: One framework can't fit all disciplines
+
+**What critics might say:** Different fields have such different norms that a single framework is too general
+**Why it matters:** Threatens generalizability of contribution
+**Our response:** Framework is adaptable; we demonstrate with two disciplines
+**Placement:** Discussion (Limitations)
+
+## Gaps and Weaknesses
+
+### Identified Gaps
+
+- **Gap 1:** Claim 4 rests on small pilot (N=20)
+  - Current state: Promising but preliminary results
+  - Needed: Larger validation study
+  - Plan: Acknowledge as limitation, note as future work
+
+### Acknowledged Limitations
+
+- Sample size for pilot: Acknowledged in Discussion
+- Two disciplines only: Acknowledged in Limitations
+
+---
+
+*Argument map for: AI-Assisted Writing Framework*
+*Update when argument structure changes*
+```
+</example>

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

@@ -0,0 +1,152 @@
+# Bibliography Template
+
+Template for `.planning/sources/literature.md` — the literature index for your paper.
+
+**Purpose:** Track all sources: what you must cite, what informed your thinking, and what you still need to find.
+
+---
+
+## File Template
+
+```markdown
+# Literature Index
+
+**Created:** [date]
+**Last updated:** [date]
+**Total citations:** [N] core + [M] supporting
+
+## Core References (Must Cite)
+
+These are foundational works that must appear in the paper.
+
+| Key | Citation | Relevance | Section | Status |
+|-----|----------|-----------|---------|--------|
+| smith2023 | Smith, J., et al. (2023). Title. *Journal*, Vol(Issue), pp. DOI | [Why foundational] | Intro | ✓ cited |
+| jones2024 | Jones, A. (2024). Title. *Journal*, Vol(Issue), pp. DOI | [Why foundational] | Methods | ✓ cited |
+| author2022 | Author, B. (2022). Title. *Journal*, Vol(Issue), pp. DOI | [Why foundational] | Lit Review | pending |
+
+## Supporting References
+
+These provide additional support or context.
+
+| Key | Citation | Relevance | Section | Status |
+|-----|----------|-----------|---------|--------|
+| davis2023 | Davis, C., et al. (2023). Title. *Conference Proceedings*. | [What it contributes] | Discussion | optional |
+| miller2024 | Miller, D. (2024). Title. *Journal*. | [What it contributes] | Background | pending |
+
+## Background Reading
+
+Informed your thinking but may not be directly cited.
+
+| Key | Citation | Notes |
+|-----|----------|-------|
+| textbook2020 | Author (2020). *Textbook Title*. Publisher. | Foundational concepts |
+| review2023 | Author (2023). Review article title. | Field overview |
+
+## To Find
+
+Citations you need but haven't located yet.
+
+- [ ] [Description of needed citation] — for [which claim/section]
+- [ ] [Description of needed citation] — for [which claim/section]
+- [ ] [Description of needed citation] — for [which claim/section]
+
+## By Section
+
+Quick reference for which citations go where.
+
+### Introduction
+- smith2023: Context on AI tool proliferation
+- jones2024: Current usage patterns
+
+### Literature Review
+- author2022: Academic writing constraints
+- [...]
+
+### Methods
+- framework2021: Methodological foundation
+- [...]
+
+### Discussion
+- critic2023: Contrasting view we address
+- [...]
+
+## Citation Notes
+
+Key quotes or specific points to reference:
+
+### smith2023
+- p. 12: "[Exact quote that's useful]"
+- p. 45: Data on adoption rates (Table 3)
+
+### jones2024
+- p. 7: "[Exact quote]"
+- Key finding: 78% of researchers report ad hoc usage
+
+---
+
+*Literature index for: [Paper title]*
+*Update as citations are added*
+```
+
+<guidelines>
+
+**Status values:**
+- `✓ cited` — Already in paper
+- `pending` — Need to add
+- `optional` — Use if space/relevance
+
+**Core vs Supporting:**
+- Core: Paper would be incomplete without these
+- Supporting: Strengthen but not essential
+- Background: Informed thinking, may not cite
+
+**To Find section:**
+- Captures citation gaps
+- Be specific about what you need
+- Link to the claim/section requiring it
+
+**By Section view:**
+- Quick reference during writing
+- Shows citation distribution
+- Helps avoid over/under-citing sections
+
+**Citation Notes:**
+- Capture key quotes with page numbers
+- Note specific data or tables to reference
+- Saves time during writing
+
+**When to update:**
+- After literature search
+- When adding citations during writing
+- After identifying gaps in argument
+</guidelines>
+
+<example>
+```markdown
+# Literature Index
+
+**Created:** 2025-01-10
+**Last updated:** 2025-01-20
+**Total citations:** 8 core + 12 supporting
+
+## Core References (Must Cite)
+
+| Key | Citation | Relevance | Section | Status |
+|-----|----------|-----------|---------|--------|
+| smith2023 | Smith, J., Chen, L., & Davis, M. (2023). The proliferation of AI writing assistants: A systematic review. *Computers & Education*, 195, 104723. | Foundational survey | Intro | ✓ cited |
+| jones2024 | Jones, A. (2024). How researchers use AI: A mixed-methods study. *Research Policy*, 53(2), 104891. | Usage patterns data | Intro, Results | ✓ cited |
+| author2022 | Author, B. (2022). Academic writing in the digital age. *Written Communication*, 39(4), 567-592. | Academic constraints | Lit Review | pending |
+| ethics2024 | Jones, A., & Chen, L. (2024). Ethics of AI co-authorship. *Science and Engineering Ethics*, 30(1), 1-18. | Ethics framework | Discussion | pending |
+
+[...]
+
+## To Find
+
+- [ ] Power analysis citation for N=45 — for Methods sample size justification
+- [ ] Comparable study with similar N — for Methods precedent
+- [ ] Recent CHI paper on AI writing tools — for Lit Review currency
+
+[...]
+```
+</example>

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

@@ -0,0 +1,122 @@
+# Research Gaps Template
+
+Template for `.planning/structure/gaps.md` — tracking research and evidence gaps.
+
+**Purpose:** Identify and track gaps in your argument that need addressing before submission.
+
+---
+
+## File Template
+
+```markdown
+# Research & Evidence Gaps
+
+**Created:** [date]
+**Last updated:** [date]
+**Status:** [X] open / [Y] resolved
+
+## Critical Gaps (Must Address)
+
+These gaps would cause rejection if not addressed.
+
+### GAP-001: [Brief description]
+
+**Type:** [Evidence / Citation / Logic / Data]
+**Location:** [Section where gap appears]
+**The gap:** [What's missing or weak]
+**Impact:** [Why this matters for the argument]
+**Status:** [Open / In progress / Resolved]
+
+**Potential solutions:**
+1. [Option 1]
+2. [Option 2]
+
+**Chosen approach:** [How we're addressing it]
+**Resolution notes:** [What was done, if resolved]
+
+### GAP-002: [Brief description]
+
+[Same structure...]
+
+## Major Gaps (Should Address)
+
+These weaken the paper but may not cause rejection.
+
+### GAP-003: [Brief description]
+
+**Type:** [Evidence / Citation / Logic / Data]
+**Location:** [Section]
+**The gap:** [What's missing]
+**Impact:** [How it weakens the argument]
+**Status:** [Open / In progress / Resolved / Acknowledged as limitation]
+
+**Potential solutions:**
+1. [Option 1]
+2. [Option 2]
+
+**Chosen approach:** [How we're addressing it or acknowledging it]
+
+## Minor Gaps (Nice to Address)
+
+These are minor weaknesses reviewers might note.
+
+### GAP-004: [Brief description]
+
+**Type:** [Evidence / Citation / Logic / Data]
+**Location:** [Section]
+**The gap:** [What's missing]
+**Status:** [Open / Deferred]
+**Notes:** [Brief notes]
+
+## Acknowledged Limitations
+
+Gaps we're explicitly calling out rather than fixing.
+
+| Gap | Acknowledgment Location | Rationale for Not Fixing |
+|-----|------------------------|-------------------------|
+| GAP-003 | Discussion, para 5 | Would require additional study |
+| [ID] | [Location] | [Why not fixed] |
+
+## Gap Summary
+
+| Priority | Total | Open | Resolved | Acknowledged |
+|----------|-------|------|----------|--------------|
+| Critical | X | Y | Z | - |
+| Major | X | Y | Z | A |
+| Minor | X | Y | Z | A |
+
+---
+
+*Gap tracking for: [Paper title]*
+*Review before submission*
+```
+
+<guidelines>
+
+**Gap types:**
+- Evidence: Need more data/examples
+- Citation: Need supporting literature
+- Logic: Argument leap without justification
+- Data: Missing statistics or analysis
+
+**Priority levels:**
+- Critical: Reviewers will reject without this
+- Major: Weakens paper significantly
+- Minor: Would be nice to have
+
+**Status values:**
+- Open: Not yet addressed
+- In progress: Working on it
+- Resolved: Fixed
+- Acknowledged: Noted as limitation
+
+**When to update:**
+- After writing each section
+- After review/verification
+- After getting feedback
+
+**Integration:**
+- Link to argument-map.md gaps section
+- Reference in STATE.md
+- Check during review-section
+</guidelines>

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

@@ -0,0 +1,140 @@
+# IMRaD Structure Reference
+
+Reference document for IMRaD (Introduction, Methods, Results, and Discussion) paper structure.
+
+**Purpose:** Quick reference for standard academic paper organization.
+
+---
+
+## IMRaD Overview
+
+```
+┌─────────────────────────────────────────┐
+│ ABSTRACT (summary of all sections)      │
+├─────────────────────────────────────────┤
+│ INTRODUCTION                            │
+│ • What is the problem?                  │
+│ • Why does it matter?                   │
+│ • What is our contribution?             │
+├─────────────────────────────────────────┤
+│ METHODS                                 │
+│ • How did we investigate?               │
+│ • What did we do?                       │
+│ • How can it be reproduced?             │
+├─────────────────────────────────────────┤
+│ RESULTS                                 │
+│ • What did we find?                     │
+│ • What does the data show?              │
+├─────────────────────────────────────────┤
+│ DISCUSSION                              │
+│ • What does it mean?                    │
+│ • How does it relate to prior work?     │
+│ • What are the limitations?             │
+│ • What comes next?                      │
+├─────────────────────────────────────────┤
+│ CONCLUSION (optional, may be in Disc.)  │
+│ • What should readers remember?         │
+└─────────────────────────────────────────┘
+```
+
+## Section Details
+
+### Abstract
+**Purpose:** Summarize the entire paper in one paragraph
+**Length:** 150-300 words (venue-specific)
+**Structure:**
+- Background/Context (1-2 sentences)
+- Gap/Problem (1 sentence)
+- Approach/Methods (1-2 sentences)
+- Key Results (2-3 sentences)
+- Implications (1-2 sentences)
+
+**Write:** Last, after all other sections complete
+
+### Introduction
+**Purpose:** Establish context, gap, and contribution
+**Length:** ~10% of paper
+**Structure:**
+1. Hook: Open with compelling context
+2. Background: What's known, what exists
+3. Gap: What's missing or problematic
+4. Contribution: What this paper provides
+5. Roadmap: Preview of paper structure (optional)
+
+**The "funnel":** Start broad, narrow to your specific contribution
+
+### Methods
+**Purpose:** Enable reproduction and establish validity
+**Length:** 15-25% of paper (varies by field)
+**Structure:**
+- Participants/Sample/Materials
+- Procedure/Protocol
+- Measures/Instruments
+- Analysis approach
+- Ethical considerations (if applicable)
+
+**Key principle:** Someone should be able to replicate from this section alone
+
+### Results
+**Purpose:** Present findings without interpretation
+**Length:** 20-30% of paper
+**Structure:**
+- Organized by research question or hypothesis
+- Present findings with supporting data
+- Include statistics, figures, tables as needed
+- Describe what you found, not what it means
+
+**Key principle:** Facts only; interpretation comes in Discussion
+
+### Discussion
+**Purpose:** Interpret findings and situate in literature
+**Length:** 20-25% of paper
+**Structure:**
+1. Summary: Brief recap of key findings
+2. Interpretation: What the findings mean
+3. Integration: How findings relate to prior work
+4. Implications: What this means for theory/practice
+5. Limitations: Honest assessment of weaknesses
+6. Future work: Where to go from here
+7. Conclusion: Final takeaway (if no separate section)
+
+**Key principle:** Connect your dots; help readers understand significance
+
+### Conclusion (if separate)
+**Purpose:** Leave readers with key takeaway
+**Length:** ~5% of paper
+**Structure:**
+- Restate main contribution
+- Key implications
+- Forward-looking statement
+
+## Common Variations
+
+### Literature Review Section
+Some fields include a separate "Related Work" or "Background" section between Introduction and Methods.
+
+### Combined Results and Discussion
+Some venues allow or prefer combined "Results and Discussion" sections.
+
+### Structured Abstracts
+Some journals require structured abstracts with explicit headings (Background, Methods, Results, Conclusions).
+
+### Grant-Specific Structures
+Grants often use different structures (Specific Aims, Significance, Innovation, Approach).
+
+## Word Budget Template
+
+| Section | % of Paper | 8000-word paper | 5000-word paper |
+|---------|------------|-----------------|-----------------|
+| Abstract | - | 200-300 | 150-200 |
+| Introduction | 10-15% | 800-1200 | 500-750 |
+| Methods | 15-25% | 1200-2000 | 750-1250 |
+| Results | 20-30% | 1600-2400 | 1000-1500 |
+| Discussion | 20-25% | 1600-2000 | 1000-1250 |
+| Conclusion | 5% | 400 | 250 |
+| **Total** | - | **~8000** | **~5000** |
+
+---
+
+*IMRaD reference document*
+*Adapt percentages to venue requirements*