# 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
