wtf-p 0.1.0

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

@@ -0,0 +1,384 @@
+# Research Template
+
+Template for `.planning/sections/XX-name/{section}-RESEARCH.md` - comprehensive literature research before planning.
+
+**Purpose:** Document what Claude needs to know to write a section well - not just "which approach" but "what does the field say."
+
+---
+
+## File Template
+
+```markdown
+# Section [X]: [Name] - Research
+
+**Researched:** [date]
+**Domain:** [primary topic/field]
+**Confidence:** [HIGH/MEDIUM/LOW]
+
+<research_summary>
+## Summary
+
+[2-3 paragraph executive summary]
+- What was researched
+- What the literature says
+- Key recommendations for writing
+
+**Primary recommendation:** [one-liner actionable guidance]
+</research_summary>
+
+<key_literature>
+## Key Literature
+
+The foundational works for this section:
+
+### Core Citations (Must Cite)
+| Citation | Relevance | Where to Use |
+|----------|-----------|--------------|
+| Author (Year) | [Why foundational] | [Section placement] |
+| Author (Year) | [Why foundational] | [Section placement] |
+
+### Supporting Literature
+| Citation | Relevance | When to Use |
+|----------|-----------|-------------|
+| Author (Year) | [What it contributes] | [Use case] |
+| Author (Year) | [What it contributes] | [Use case] |
+
+### Contrasting Views
+| Citation | Position | Our Response |
+|----------|----------|--------------|
+| Author (Year) | [Their argument] | [How we address it] |
+</key_literature>
+
+<field_conventions>
+## Field Conventions
+
+### Standard Approaches
+[How papers in this field typically handle this section]
+
+**Structure:**
+- [Expected elements]
+- [Typical flow]
+- [What reviewers expect]
+
+**Terminology:**
+- [Standard terms to use]
+- [Terms to avoid or define]
+
+**Evidence Standards:**
+- [What counts as sufficient evidence]
+- [Expected rigor level]
+</field_conventions>
+
+<common_arguments>
+## Common Arguments
+
+### Argument Pattern 1: [Name]
+**Structure:** [How this argument typically flows]
+**Example:** [Citation that exemplifies this]
+**Our use:** [How we can employ this]
+
+### Argument Pattern 2: [Name]
+**Structure:** [How this argument typically flows]
+**Example:** [Citation that exemplifies this]
+**Our use:** [How we can employ this]
+</common_arguments>
+
+<pitfalls_to_avoid>
+## Pitfalls to Avoid
+
+### Pitfall 1: [Name]
+**What goes wrong:** [Description]
+**Why it happens:** [Root cause]
+**How to avoid:** [Prevention strategy]
+**Example:** [Citation or description of bad example]
+
+### Pitfall 2: [Name]
+**What goes wrong:** [Description]
+**Why it happens:** [Root cause]
+**How to avoid:** [Prevention strategy]
+**Example:** [Citation or description]
+
+### Pitfall 3: [Name]
+**What goes wrong:** [Description]
+**Why it happens:** [Root cause]
+**How to avoid:** [Prevention strategy]
+**Example:** [Citation or description]
+</pitfalls_to_avoid>
+
+<quotes_to_use>
+## Key Quotes
+
+Verified quotes from sources:
+
+### [Topic 1]
+> "[Exact quote]"
+> — Author (Year, p. X)
+
+**Use for:** [Where/how to use this quote]
+
+### [Topic 2]
+> "[Exact quote]"
+> — Author (Year, p. X)
+
+**Use for:** [Where/how to use this quote]
+</quotes_to_use>
+
+<recent_developments>
+## Recent Developments (2023-2025)
+
+What's changed recently:
+
+| Old Consensus | Current Understanding | Key Citation |
+|---------------|----------------------|--------------|
+| [Old view] | [New view] | Author (Year) |
+
+**New findings to incorporate:**
+- [Finding]: [Implication for our paper]
+- [Finding]: [Implication for our paper]
+
+**Outdated views to avoid:**
+- [View]: [Why outdated, what replaced it]
+</recent_developments>
+
+<open_questions>
+## Open Questions
+
+Things that couldn't be fully resolved:
+
+1. **[Question]**
+   - What we know: [Partial info]
+   - What's unclear: [The gap]
+   - Recommendation: [How to handle during writing]
+
+2. **[Question]**
+   - What we know: [Partial info]
+   - What's unclear: [The gap]
+   - Recommendation: [How to handle]
+</open_questions>
+
+<sources>
+## Sources
+
+### Primary (HIGH confidence)
+- [Citation] - [What was learned]
+- [Citation] - [What was learned]
+
+### Secondary (MEDIUM confidence)
+- [Citation verified with primary] - [Finding + verification]
+
+### Tertiary (LOW confidence - needs validation)
+- [WebSearch only] - [Finding, marked for validation during writing]
+</sources>
+
+<metadata>
+## Metadata
+
+**Research scope:**
+- Core topic: [What]
+- Literature: [Papers explored]
+- Conventions: [Field norms researched]
+- Pitfalls: [Areas checked]
+
+**Confidence breakdown:**
+- Key literature: [HIGH/MEDIUM/LOW] - [reason]
+- Field conventions: [HIGH/MEDIUM/LOW] - [reason]
+- Recent developments: [HIGH/MEDIUM/LOW] - [reason]
+
+**Research date:** [date]
+**Valid until:** [estimate - 30 days for stable field, 7 days for fast-moving]
+</metadata>
+
+---
+
+*Section: XX-name*
+*Research completed: [date]*
+*Ready for planning: [yes/no]*
+```
+
+---
+
+## Good Example
+
+```markdown
+# Section 2: Literature Review - Research
+
+**Researched:** 2025-01-20
+**Domain:** AI-assisted academic writing
+**Confidence:** HIGH
+
+<research_summary>
+## Summary
+
+Researched the literature on AI-assisted writing tools in academic contexts. The field has grown rapidly since 2023, with three main threads: (1) tool efficacy studies, (2) ethical concerns about authorship, and (3) pedagogical integration.
+
+Key finding: Most literature focuses on undergraduate writing; PhD/researcher use is understudied. This positions our contribution clearly.
+
+**Primary recommendation:** Structure lit review around the three threads, acknowledge ethical concerns explicitly, position our work as addressing the researcher gap.
+</research_summary>
+
+<key_literature>
+## Key Literature
+
+### Core Citations (Must Cite)
+| Citation | Relevance | Where to Use |
+|----------|-----------|--------------|
+| Smith et al. (2023) | Foundational survey of AI writing tools | Opening context |
+| Jones & Chen (2024) | Ethics framework for AI authorship | Ethics paragraph |
+| Brown (2023) | Gap in researcher-focused tools | Gap statement |
+
+### Supporting Literature
+| Citation | Relevance | When to Use |
+|----------|-----------|-------------|
+| Williams (2024) | Pedagogical integration strategies | If discussing teaching |
+| Davis et al. (2023) | Productivity impacts in industry | Broader context |
+
+### Contrasting Views
+| Citation | Position | Our Response |
+|----------|----------|--------------|
+| Taylor (2024) | AI writing is plagiarism | Distinguish co-authorship from replacement |
+</key_literature>
+
+<field_conventions>
+## Field Conventions
+
+### Standard Approaches
+
+**Structure:**
+- Thematic organization (not chronological)
+- Explicit positioning statement at end
+- Critical synthesis, not just summary
+
+**Terminology:**
+- "AI-assisted" not "AI-generated"
+- "Co-authorship" for collaborative use
+- Avoid "cheating" framing - use "ethical considerations"
+
+**Evidence Standards:**
+- Empirical studies preferred over opinion pieces
+- Recent work (2022+) for rapidly evolving field
+- Acknowledge limitations of self-report studies
+</field_conventions>
+
+<common_arguments>
+## Common Arguments
+
+### Argument Pattern 1: Gap-Contribution
+**Structure:** Literature shows X, but not Y. We address Y.
+**Example:** Brown (2023) uses this effectively
+**Our use:** Position our framework after reviewing existing tools
+
+### Argument Pattern 2: Synthesis-Tension
+**Structure:** Thread A says X, Thread B says Y. We reconcile with Z.
+**Example:** Jones & Chen (2024) synthesize ethics debates
+**Our use:** Bridge productivity and ethics concerns
+</common_arguments>
+
+<pitfalls_to_avoid>
+## Pitfalls to Avoid
+
+### Pitfall 1: Uncritical Tech Enthusiasm
+**What goes wrong:** Paper reads as AI promotion
+**Why it happens:** Focus on capabilities without limitations
+**How to avoid:** Explicitly acknowledge concerns, cite critics
+**Example:** Early 2023 papers often read as promotional
+
+### Pitfall 2: Ethics Afterthought
+**What goes wrong:** Ethics section feels tacked on
+**Why it happens:** Not integrated into main argument
+**How to avoid:** Weave ethical considerations throughout
+**Example:** Taylor (2024) critique of shallow ethics coverage
+
+### Pitfall 3: Stale Literature
+**What goes wrong:** Cites outdated tools/studies
+**Why it happens:** Field moves fast, papers age quickly
+**How to avoid:** Check publication dates, prefer 2023+
+**Example:** GPT-3 studies largely superseded
+</pitfalls_to_avoid>
+
+<quotes_to_use>
+## Key Quotes
+
+### On the research gap
+> "While substantial attention has been paid to AI writing tools in educational contexts, their role in supporting professional researchers remains largely unexplored."
+> — Brown (2023, p. 12)
+
+**Use for:** Gap statement in literature review
+
+### On ethical framing
+> "The question is not whether AI should assist writing, but how to integrate it responsibly while preserving scholarly integrity."
+> — Jones & Chen (2024, p. 45)
+
+**Use for:** Ethics discussion, positioning statement
+</quotes_to_use>
+
+<sources>
+## Sources
+
+### Primary (HIGH confidence)
+- Smith et al. (2023) - Comprehensive survey, 200+ tools reviewed
+- Jones & Chen (2024) - Ethics framework, widely cited
+- Brown (2023) - Gap identification, recent and relevant
+
+### Secondary (MEDIUM confidence)
+- Williams (2024) - Preprint, verified with subsequent publication
+
+### Tertiary (LOW confidence - needs validation)
+- Conference proceedings from 2024 - Check if published in final form
+</sources>
+
+<metadata>
+## Metadata
+
+**Research scope:**
+- Core topic: AI-assisted academic writing
+- Literature: 25+ papers reviewed
+- Conventions: HCI and education publication norms
+- Pitfalls: Common reviewer complaints identified
+
+**Confidence breakdown:**
+- Key literature: HIGH - verified with Google Scholar
+- Field conventions: HIGH - from published guidelines
+- Recent developments: MEDIUM - field moving fast
+
+**Research date:** 2025-01-20
+**Valid until:** 2025-02-20 (30 days - field evolving)
+</metadata>
+
+---
+
+*Section: 02-literature*
+*Research completed: 2025-01-20*
+*Ready for planning: yes*
+```
+
+---
+
+## Guidelines
+
+**When to create:**
+- Before planning sections that require literature engagement
+- When field knowledge is needed beyond what user provides
+- When "what does the literature say" matters
+
+**Structure:**
+- Use XML tags for section markers (matches WTF-P templates)
+- Seven core sections: summary, key_literature, field_conventions, common_arguments, pitfalls_to_avoid, quotes_to_use, sources
+- All sections required (drives comprehensive research)
+
+**Content quality:**
+- Key literature: Include citation details, not just names
+- Field conventions: Be prescriptive about expectations
+- Pitfalls: Include examples of what to avoid
+- Quotes: Provide exact quotes with page numbers
+- Sources: Mark confidence levels honestly
+
+**Integration with planning:**
+- RESEARCH.md loaded as @context reference in PLAN.md
+- Key literature informs citation choices
+- Pitfalls inform what to avoid in writing
+- Quotes can be used directly in draft
+
+**After creation:**
+- File lives in section directory: `.planning/sections/XX-name/{section}-RESEARCH.md`
+- Referenced during planning workflow
+- plan-section loads it automatically when present

package/write-the-f-paper/templates/review-comments.md

@@ -0,0 +1,253 @@
+# Review Comments Template
+
+Template for `.planning/revisions/round-[N]/reviewer-comments.md` — importing reviewer feedback.
+
+**Purpose:** Capture and organize reviewer comments for systematic response.
+
+---
+
+## File Template
+
+```markdown
+# Reviewer Comments: Round [N]
+
+**Received:** [date]
+**Decision:** [Accept / Minor Revision / Major Revision / Reject with Resubmit / Reject]
+**Response deadline:** [date]
+
+## Editor Summary
+
+> [Editor's summary or cover letter text, if provided]
+
+**Editor's key points:**
+- [Point 1]
+- [Point 2]
+
+---
+
+## Reviewer 1
+
+**Expertise:** [If stated: "Expert in X" / "Familiar with Y"]
+**Recommendation:** [If stated: Accept / Minor / Major / Reject]
+**Overall tone:** [Positive / Mixed / Critical / Constructive]
+
+### Summary Comments
+
+> [Reviewer's overall assessment, quoted verbatim]
+
+### Detailed Comments
+
+#### R1.1: [Brief summary]
+
+**Type:** [Required / Suggested / Question / Minor]
+**Section:** [Which section this concerns]
+
+> "[Exact quote from reviewer]"
+
+**Our understanding:** [What they're asking for]
+**Severity:** [Critical / Major / Minor]
+
+---
+
+#### R1.2: [Brief summary]
+
+**Type:** [Required / Suggested / Question / Minor]
+**Section:** [Which section]
+
+> "[Exact quote from reviewer]"
+
+**Our understanding:** [What they're asking for]
+**Severity:** [Critical / Major / Minor]
+
+---
+
+[Continue for all comments...]
+
+---
+
+## Reviewer 2
+
+**Expertise:** [If stated]
+**Recommendation:** [If stated]
+**Overall tone:** [Assessment]
+
+### Summary Comments
+
+> [Reviewer's overall assessment]
+
+### Detailed Comments
+
+#### R2.1: [Brief summary]
+
+**Type:** [Required / Suggested / Question / Minor]
+**Section:** [Which section]
+
+> "[Exact quote]"
+
+**Our understanding:** [What they're asking for]
+**Severity:** [Critical / Major / Minor]
+
+---
+
+[Continue for all comments...]
+
+---
+
+## Reviewer 3 (if applicable)
+
+[Same structure...]
+
+---
+
+## Comment Summary
+
+### By Priority
+
+**Critical (must address):**
+- R1.2: [Summary]
+- R2.1: [Summary]
+
+**Major (should address):**
+- R1.1: [Summary]
+- R2.3: [Summary]
+
+**Minor (nice to address):**
+- R1.4: [Summary]
+- R2.5: [Summary]
+
+### By Section
+
+| Section | Comments | Critical | Major | Minor |
+|---------|----------|----------|-------|-------|
+| Introduction | R1.1, R2.2 | 0 | 1 | 1 |
+| Methods | R1.2, R2.1, R3.1 | 1 | 1 | 1 |
+| Results | R2.3 | 0 | 1 | 0 |
+| Discussion | R1.3, R2.4 | 0 | 1 | 1 |
+
+### Cross-Reviewer Themes
+
+**Multiple reviewers mentioned:**
+- [Theme 1]: R1.1, R2.2 — [Common concern]
+- [Theme 2]: R1.3, R2.4, R3.2 — [Common concern]
+
+---
+
+*Reviews imported: [date]*
+*Ready for: /wtfp:plan-revision*
+```
+
+<guidelines>
+
+**Importing reviews:**
+1. Copy exact text from review system
+2. Quote verbatim (don't paraphrase)
+3. Add your understanding beneath
+4. Classify by type and severity
+
+**Comment types:**
+- Required: Must change or address
+- Suggested: Recommended but optional
+- Question: Clarification needed
+- Minor: Typos, small fixes
+
+**Severity levels:**
+- Critical: Would cause rejection if unaddressed
+- Major: Significant weakness
+- Minor: Would improve but not required
+
+**Comment numbering:**
+- R1.1, R1.2: Reviewer 1, comments 1, 2
+- R2.1, R2.2: Reviewer 2, comments 1, 2
+- Enables precise reference in response
+
+**Cross-reviewer analysis:**
+- Identify common themes
+- Multiple mentions = higher priority
+- Consensus issues need strongest response
+
+**After import:**
+1. Run /wtfp:plan-revision to create fix plan
+2. Execute fixes
+3. Create response letter
+4. Verify all comments addressed
+</guidelines>
+
+<example>
+```markdown
+# Reviewer Comments: Round 1
+
+**Received:** 2025-04-15
+**Decision:** Major Revision
+**Response deadline:** 2025-05-15
+
+## Editor Summary
+
+> The reviewers appreciate the novel contribution but have concerns about methodology and generalizability. Please address all comments thoroughly.
+
+**Editor's key points:**
+- Strengthen methods section
+- Address generalizability concerns
+- Add statistical detail
+
+---
+
+## Reviewer 1
+
+**Expertise:** Expert in HCI research methods
+**Recommendation:** Major Revision
+**Overall tone:** Constructive
+
+### Summary Comments
+
+> "This paper addresses an important and timely topic. The framework is novel and potentially useful. However, I have concerns about the methodology and sample size that need to be addressed."
+
+### Detailed Comments
+
+#### R1.1: Sample size justification
+
+**Type:** Required
+**Section:** Methods
+
+> "The sample size of N=45 is not justified. Please provide a power analysis or cite precedent studies that support this sample size for the type of analysis conducted."
+
+**Our understanding:** Need to justify N=45 with power analysis or precedent
+**Severity:** Critical
+
+---
+
+#### R1.2: Participant demographics
+
+**Type:** Suggested
+**Section:** Methods
+
+> "Table 1 would benefit from additional demographic information including years of experience and prior AI tool usage."
+
+**Our understanding:** Expand demographics table
+**Severity:** Major
+
+---
+
+## Comment Summary
+
+### By Priority
+
+**Critical (must address):**
+- R1.1: Sample size justification
+- R2.1: Statistical test details
+
+**Major (should address):**
+- R1.2: Expand demographics
+- R2.3: Clarify framework validation
+
+### Cross-Reviewer Themes
+
+**Multiple reviewers mentioned:**
+- Methods detail: R1.1, R1.2, R2.1 — Need more methodological rigor
+- Generalizability: R1.3, R2.4 — Concern about two-discipline limitation
+
+---
+
+*Reviews imported: 2025-04-15*
+*Ready for: /wtfp:plan-revision*
+```
+</example>