wtf-p 0.1.0

package/commands/wtfp/analyze-bib.md

@@ -0,0 +1,326 @@
+---
+name: wtfp:analyze-bib
+description: Analyze BibTeX file and suggest citation placement by section
+argument-hint: "[bib-file]"
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - Glob
+  - Grep
+  - AskUserQuestion
+  - WebFetch
+---
+
+<objective>
+Deep analysis of BibTeX bibliography to inform writing strategy.
+
+Purpose: Understand your literature landscape before writing. Cluster papers by topic, identify seminal vs recent work, and pre-populate citation suggestions per section.
+Output: REFS.md with citation strategy mapped to your paper's sections.
+</objective>
+
+<execution_context>
+@~/.claude/write-the-f-paper/references/citation-formats.md
+@~/.claude/write-the-f-paper/templates/project-context/bibliography.md
+</execution_context>
+
+<context>
+BibTeX file: $ARGUMENTS (optional - auto-detects .bib files if not provided)
+
+**Load project context:**
+@.planning/PROJECT.md
+@.planning/config.json
+@.planning/structure/outline.md
+</context>
+
+<process>
+
+<step name="locate_bib">
+**Find BibTeX file:**
+
+```bash
+# Find .bib files
+find . -name "*.bib" -type f 2>/dev/null | grep -v node_modules | grep -v .git | head -10
+```
+
+If multiple found, use AskUserQuestion:
+- header: "BibTeX"
+- question: "Which bibliography file should I analyze?"
+- options: [list found files] + "Analyze all"
+
+If none found:
+```
+No .bib file found.
+
+Either:
+1. Add your .bib file to the project
+2. Specify path: /wtfp:analyze-bib path/to/refs.bib
+```
+Exit command.
+
+</step>
+
+<step name="parse_entries">
+**Parse all BibTeX entries:**
+
+Extract from each entry:
+- Citation key
+- Type (@article, @inproceedings, @book, etc.)
+- Authors
+- Title
+- Year
+- Venue (journal/booktitle)
+- Abstract (if present)
+- Keywords (if present)
+
+Build structured inventory of all references.
+
+</step>
+
+<step name="temporal_analysis">
+**Temporal Analysis:**
+
+Categorize by publication year:
+- **Foundational** (10+ years old): Seminal works, established theory
+- **Established** (5-10 years): Mature approaches, proven methods
+- **Recent** (2-5 years): Current state of the art
+- **Cutting edge** (<2 years): Latest developments, concurrent work
+
+```markdown
+## Temporal Distribution
+
+| Era | Count | Examples |
+|-----|-------|----------|
+| Foundational (pre-2015) | [N] | [key1], [key2] |
+| Established (2015-2019) | [N] | [key3], [key4] |
+| Recent (2020-2023) | [N] | [key5], [key6] |
+| Cutting edge (2024+) | [N] | [key7], [key8] |
+```
+
+</step>
+
+<step name="cluster_topics">
+**Topic Clustering:**
+
+Analyze titles, abstracts, and keywords to cluster papers by theme:
+
+1. Extract key terms from titles/abstracts
+2. Group papers with overlapping terminology
+3. Label clusters with descriptive names
+
+```markdown
+## Topic Clusters
+
+### Cluster 1: [Theme Name]
+**Papers:** [key1], [key2], [key3]
+**Common themes:** [extracted keywords]
+**Use for:** [which section this supports]
+
+### Cluster 2: [Theme Name]
+**Papers:** [key4], [key5]
+**Common themes:** [extracted keywords]
+**Use for:** [which section this supports]
+```
+
+</step>
+
+<step name="identify_seminal">
+**Identify Seminal Works:**
+
+Flag likely seminal papers based on:
+- High citation count (if DOI available, could fetch)
+- Foundational publication year
+- Appears in prestigious venue
+- Authors are field leaders
+- Title suggests foundational contribution
+
+```markdown
+## Seminal Works (Must Cite)
+
+| Key | Title | Why Seminal |
+|-----|-------|-------------|
+| [key] | [title] | [reason: foundational method, influential framework, etc.] |
+```
+
+Use AskUserQuestion:
+- header: "Seminal"
+- question: "Which of these are definitely seminal works in your field?"
+- multiSelect: true
+- options: [top candidates] + "None of these" + "Let me add others"
+
+</step>
+
+<step name="map_to_sections">
+**Map Citations to Sections:**
+
+Based on venue template and topic clusters, suggest where each citation belongs:
+
+Read outline.md to get section structure.
+
+For each section, identify relevant citations:
+
+```markdown
+## Citation Map
+
+### Section 1: Introduction
+**Purpose:** Establish problem importance, cite motivation
+**Suggested citations:**
+- [key1] — establishes the problem exists
+- [key2] — shows prior failed attempts
+- [key3] — motivates urgency
+
+### Section 2: Background
+**Purpose:** Technical foundations
+**Suggested citations:**
+- [key4] — defines key concept X
+- [key5] — introduces method Y
+
+### Section 3: Approach
+**Purpose:** Your contribution (cite sparingly)
+**Suggested citations:**
+- [key6] — technique you build on
+
+### Section 4: Evaluation
+**Purpose:** Comparison baselines
+**Suggested citations:**
+- [key7] — baseline method 1
+- [key8] — baseline method 2
+
+### Section 5: Related Work
+**Purpose:** Position in literature (cite heavily)
+**Suggested citations:**
+- [key9], [key10] — similar approaches
+- [key11], [key12] — alternative methods
+- [key13] — concurrent work
+```
+
+</step>
+
+<step name="identify_gaps">
+**Identify Citation Gaps:**
+
+Based on topic clusters and section needs, flag potential missing references:
+
+```markdown
+## Potential Gaps
+
+| Section | Gap | Suggestion |
+|---------|-----|------------|
+| Background | No citation for [concept] | Search for foundational paper on X |
+| Related Work | Missing [approach type] | Add recent work on Y |
+| Evaluation | Only [N] baselines | Consider adding [method] |
+```
+
+Use AskUserQuestion:
+- header: "Gaps"
+- question: "Any topics you know you need to cite but don't have in your .bib yet?"
+- options:
+  - "No gaps" — Coverage looks good
+  - "Missing some" — I'll list what I need
+  - "Not sure" — Help me identify gaps
+
+</step>
+
+<step name="write_refs">
+**Create REFS.md:**
+
+Write to `.planning/sources/REFS.md`:
+
+```markdown
+# Citation Strategy
+
+## Bibliography: [filename.bib]
+**Total entries:** [N]
+**Analysis date:** [date]
+
+## Temporal Distribution
+[From temporal_analysis step]
+
+## Topic Clusters
+[From cluster_topics step]
+
+## Seminal Works
+[From identify_seminal step]
+
+## Citation Map by Section
+[From map_to_sections step]
+
+## Potential Gaps
+[From identify_gaps step]
+
+## Quick Reference
+
+### High-Priority Citations (use frequently)
+- [key1] — [one-liner why]
+- [key2] — [one-liner why]
+
+### Context Citations (use once for background)
+- [key3] — [one-liner why]
+
+### Comparison Citations (evaluation section)
+- [key4] — [one-liner why]
+
+---
+*Generated by /wtfp:analyze-bib*
+*Review and adjust as you write*
+```
+
+</step>
+
+<step name="commit">
+```bash
+git add .planning/sources/REFS.md
+git commit -m "$(cat <<'EOF'
+refs: analyze bibliography for citation strategy
+
+- Entries: [N] total
+- Clusters: [N] topic groups
+- Seminal works: [N] identified
+- Citation map: all sections covered
+EOF
+)"
+```
+
+</step>
+
+<step name="done">
+```
+Bibliography analyzed:
+
+- Source: [filename.bib]
+- Entries: [N]
+- Topic clusters: [N]
+- Seminal works: [N]
+- Citation map: .planning/sources/REFS.md
+
+## Key Insights
+
+[2-3 bullet observations about the bibliography]
+
+---
+
+## Next Up
+
+**Create outline** — use citation map to inform section planning
+
+`/wtfp:create-outline`
+
+Or review REFS.md and adjust before proceeding.
+
+---
+```
+
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] BibTeX file parsed completely
+- [ ] Temporal distribution analyzed
+- [ ] Topic clusters identified
+- [ ] Seminal works flagged (with user confirmation)
+- [ ] Citations mapped to paper sections
+- [ ] Gaps identified
+- [ ] REFS.md created in .planning/sources/
+- [ ] Committed to git
+</success_criteria>

package/commands/wtfp/check-refs.md

@@ -0,0 +1,205 @@
+---
+name: wtfp:check-refs
+description: BibTeX audit - verify citations are complete and consistent
+argument-hint: "[bib-file]"
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - Edit
+  - Glob
+  - Grep
+---
+
+<objective>
+Audit citations for completeness and consistency.
+
+Purpose: Ensure all in-text citations have BibTeX entries, all BibTeX entries are cited, and references are properly formatted.
+Output: Report of citation issues with fixes applied or flagged for user action.
+</objective>
+
+<execution_context>
+@~/.claude/write-the-f-paper/references/citation-formats.md
+</execution_context>
+
+<context>
+BibTeX file: $ARGUMENTS (optional - auto-detects .bib files if not provided)
+
+**Load project state:**
+@.planning/STATE.md
+
+**Scan for:**
+- .bib files in project root and common locations
+- Draft files with citations (\cite{}, [@...], etc.)
+</context>
+
+<process>
+
+<step name="locate_files">
+1. Find BibTeX file(s):
+```bash
+find . -name "*.bib" -type f 2>/dev/null | head -20
+```
+
+2. Find files with citations:
+```bash
+grep -rl "\\\\cite\|\\[@\|\\[.*\\]" --include="*.tex" --include="*.md" . 2>/dev/null
+```
+
+3. If no .bib found, error:
+```
+No .bib file found.
+
+Create one or specify path: /wtfp:check-refs path/to/refs.bib
+```
+</step>
+
+<step name="parse_bib">
+**Extract all BibTeX keys:**
+
+```bash
+grep -E "^@[a-zA-Z]+\{" *.bib | sed 's/.*{\([^,]*\),.*/\1/'
+```
+
+Build inventory:
+- Entry key
+- Entry type (@article, @inproceedings, etc.)
+- Required fields present/missing
+- Year
+</step>
+
+<step name="parse_citations">
+**Extract all in-text citations:**
+
+LaTeX style: `\cite{key}`, `\citep{key}`, `\citet{key}`, `\cite{key1,key2}`
+Markdown style: `[@key]`, `[@key1; @key2]`
+
+Build list of all citation keys used in text.
+</step>
+
+<step name="cross_reference">
+**Compare citations vs BibTeX:**
+
+| Check | Status |
+|-------|--------|
+| Cited but no BibTeX entry | ❌ MISSING |
+| BibTeX entry but never cited | ⚠️ UNUSED |
+| Entry missing required fields | ⚠️ INCOMPLETE |
+| Duplicate keys | ❌ DUPLICATE |
+| Year out of range (< 1900 or > current) | ⚠️ SUSPICIOUS |
+
+**Required fields by type:**
+
+| Type | Required |
+|------|----------|
+| @article | author, title, journal, year |
+| @inproceedings | author, title, booktitle, year |
+| @book | author/editor, title, publisher, year |
+| @phdthesis | author, title, school, year |
+| @misc | author, title, year, howpublished/url |
+</step>
+
+<step name="report">
+**Present findings:**
+
+```
+## Citation Audit
+
+### ❌ Missing BibTeX Entries (cited but not in .bib)
+- `smith2023` — cited in intro.tex:45
+- `jones2022deep` — cited in methods.md:112
+
+### ⚠️ Unused References (in .bib but never cited)
+- `oldpaper1999` — consider removing or citing
+- `tangential2020` — consider removing or citing
+
+### ⚠️ Incomplete Entries (missing required fields)
+- `chen2021` — missing: journal
+- `kumar2022` — missing: booktitle
+
+### ✓ Valid Citations: [N]
+### ✓ Valid BibTeX Entries: [N]
+```
+</step>
+
+<step name="offer_fixes">
+**For fixable issues:**
+
+Use AskUserQuestion:
+- header: "Fixes"
+- question: "How should I handle unused references?"
+- options:
+  - "Remove unused" — Delete entries not cited in text
+  - "Keep all" — Leave .bib unchanged
+  - "Comment out" — Keep but mark as unused
+
+For missing entries, offer to:
+- Search for DOI/metadata (if WebFetch available)
+- Create skeleton entry for user to complete
+- Flag for manual resolution
+</step>
+
+<step name="apply_fixes">
+Apply approved fixes to .bib file.
+
+If removing unused:
+```bash
+# Backup first
+cp references.bib references.bib.backup
+```
+
+Apply edits.
+</step>
+
+<step name="commit">
+```bash
+git add *.bib
+git commit -m "$(cat <<'EOF'
+refs: audit and clean bibliography
+
+- Verified [N] citations against BibTeX
+- Removed [N] unused entries (if applicable)
+- Fixed [N] incomplete entries (if applicable)
+- [N] issues flagged for manual review
+EOF
+)"
+```
+</step>
+
+<step name="done">
+```
+Citation audit complete:
+
+- Citations in text: [N]
+- BibTeX entries: [N]
+- Issues fixed: [N]
+- Issues flagged: [N]
+
+---
+
+## Manual Action Required (if any)
+
+[List of issues requiring user intervention]
+
+---
+
+## Next Up
+
+- `/wtfp:polish-prose` — Refine writing
+- `/wtfp:export-latex` — Generate LaTeX
+- `/wtfp:review-section` — Get reviewer feedback
+
+---
+```
+</step>
+
+</process>
+
+<success_criteria>
+- All in-text citations have corresponding BibTeX entries
+- All BibTeX entries have required fields
+- Unused references identified (removed or flagged)
+- No duplicate keys
+- Changes committed to git
+- User knows what manual fixes remain
+</success_criteria>