wtf-p 0.3.0 → 0.5.0

package/vendors/claude/commands/wtfp/analyze-bib.md

@@ -1,6 +1,6 @@
 ---
 name: wtfp:analyze-bib
-description: Analyze BibTeX file and suggest citation placement by section
+description: Analyze bibliography and map citations to sections
 argument-hint: "[bib-file]"
 allowed-tools:
   - Read
@@ -8,24 +8,25 @@ allowed-tools:
   - Write
   - Glob
   - Grep
+  - Task
   - AskUserQuestion
   - WebFetch
 ---
 
+<execution_context>
+@~/.claude/write-the-f-paper/templates/project-context/bibliography.md
+</execution_context>
+
 <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>
+**Orchestrator role:** Locate bib file, run deterministic indexing/impact tools, resolve model profile, spawn citation-expert agent for analysis, present results.
 
-<execution_context>
-@~/.claude/write-the-f-paper/references/citation-formats.md
-@~/.claude/write-the-f-paper/templates/project-context/bibliography.md
-</execution_context>
+Output: REFS.md with citation strategy mapped to paper sections.
+</objective>
 
 <context>
-BibTeX file: $ARGUMENTS (optional - auto-detects .bib files if not provided)
+BibTeX file: $ARGUMENTS (optional — auto-detects .bib files if not provided)
 
 **Load project context:**
 @.planning/PROJECT.md
@@ -35,292 +36,102 @@ BibTeX file: $ARGUMENTS (optional - auto-detects .bib files if not provided)
 
 <process>
 
-<step name="locate_bib">
-**Find BibTeX file:**
+## 1. Validate Environment and Resolve Model Profile
 
 ```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 multiple found, ask via AskUserQuestion. If none found, exit with error.
 
-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
+```bash
+MODEL_PROFILE=$(cat .planning/config.json 2>/dev/null | grep -o '"model_profile"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "balanced")
 ```
-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:**
+| Agent | quality | balanced | budget |
+|-------|---------|----------|--------|
+| citation-expert | opus | sonnet | haiku |
 
-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
+## 2. Run Deterministic Tools
 
-```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] |
+```bash
+node ~/.claude/bin/bib-index.js index "$BIB_FILE"
+node ~/.claude/bin/analyze-impact.js "$BIB_FILE"
 ```
 
-</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
+Capture JSON output from indexer and impact analysis results.
 
-```markdown
-## Topic Clusters
+## 3. Read Context Files
 
-### 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]
+```bash
+PROJECT_CONTENT=$(cat .planning/PROJECT.md)
+OUTLINE_CONTENT=$(cat .planning/structure/outline.md 2>/dev/null)
 ```
 
-</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
+## 4. Spawn citation-expert Agent
 
-```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
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ WTF-P ► ANALYZING BIBLIOGRAPHY
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
-</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] |
+```
+Task(
+  prompt="First, read ~/.claude/agents/wtfp/citation-expert.md for your role.\n\n" + analysis_prompt,
+  subagent_type="general-purpose",
+  model="{expert_model}",
+  description="Analyze bibliography"
+)
 ```
 
-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]
+Analysis prompt includes: `<bib_index>` with parsed entries, `<impact_analysis>` with metrics, `<project_context>` with PROJECT + outline, `<output>` targeting `.planning/sources/REFS.md`.
 
-## Quick Reference
+Agent performs: temporal analysis, topic clustering, seminal work identification, section mapping, gap identification.
 
-### High-Priority Citations (use frequently)
-- [key1] — [one-liner why]
-- [key2] — [one-liner why]
+## 5. Handle Expert Return
 
-### Context Citations (use once for background)
-- [key3] — [one-liner why]
+**`## ANALYSIS COMPLETE`:** Present summary, ask user to confirm seminal works via AskUserQuestion.
 
-### Comparison Citations (evaluation section)
-- [key4] — [one-liner why]
+**`## ANALYSIS BLOCKED`:** Present blocker (missing .bib, empty file, etc.), ask user how to proceed.
 
----
-*Generated by /wtfp:analyze-bib*
-*Review and adjust as you write*
-```
+## 6. Commit
 
-</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
-)"
+git commit -m "refs: analyze bibliography for citation strategy"
 ```
 
-</step>
+</process>
+
+<offer_next>
 
-<step name="done">
-```
-Bibliography analyzed:
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ WTF-P ► 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
 
----
-
-## Next Up
-
-**Create outline** — use citation map to inform section planning
-
-`/wtfp:create-outline`
+`/wtfp:create-outline` — use citation map to inform section planning
 
-Or review REFS.md and adjust before proceeding.
+<sub>`/clear` first → fresh context window</sub>
 
----
-```
+───────────────────────────────────────────
 
-</step>
-
-</process>
+</offer_next>
 
 <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/
+- [ ] Impact analysis run
+- [ ] Citation-expert spawned with full context
+- [ ] REFS.md created with citation strategy
+- [ ] Seminal works confirmed with user
 - [ ] Committed to git
 </success_criteria>

package/vendors/claude/commands/wtfp/audit-milestone.md

@@ -0,0 +1,286 @@
+---
+name: wtfp:audit-milestone
+description: Run pre-submission checks on sections, citations, and word counts
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+
+<objective>
+Check paper readiness before submission.
+
+Runs 5 audit checks:
+1. Section completion status
+2. Argument coverage (all claims addressed)
+3. Word targets (within tolerance)
+4. Citation completeness (all resolved)
+5. Review status (all sections reviewed)
+
+Produces MILESTONE-AUDIT.md with pass/gap for each criterion.
+</objective>
+
+<process>
+
+<step name="validate">
+**Step 1: Validate Environment**
+
+```bash
+[ ! -f .planning/PROJECT.md ] && echo "ERROR: No PROJECT.md found" && exit 1
+[ ! -f .planning/ROADMAP.md ] && echo "ERROR: No ROADMAP.md found" && exit 1
+[ ! -f .planning/STATE.md ] && echo "ERROR: No STATE.md found" && exit 1
+```
+
+</step>
+
+<step name="banner">
+**Step 2: Display Banner**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ WTF-P ► AUDITING MILESTONE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Running 5 pre-submission checks...
+```
+
+</step>
+
+<step name="check_sections">
+**Check 1: Section Completion**
+
+Read ROADMAP.md. For each section entry:
+- Is it marked `[x]` complete?
+- Extract section name and completion status
+
+Count:
+- `TOTAL_SECTIONS`: Number of section entries
+- `COMPLETE_SECTIONS`: Number with `[x]`
+- `INCOMPLETE_SECTIONS`: Number with `[ ]`
+
+**Result:**
+- PASS if `COMPLETE_SECTIONS == TOTAL_SECTIONS`
+- GAP if any sections incomplete
+
+Store result:
+```
+CHECK_1_STATUS="{PASS|GAP}"
+CHECK_1_DETAIL="{M}/{N} complete"
+CHECK_1_GAPS="{list of incomplete section names, if any}"
+```
+
+</step>
+
+<step name="check_arguments">
+**Check 2: Argument Coverage**
+
+Read `.planning/structure/argument-map.md` if it exists.
+
+Extract all claims (lines starting with `- **Claim**:` or numbered claims).
+
+For each claim:
+- Search paper content files (`paper/` directory or equivalent)
+- Check if evidence of the claim being addressed exists
+
+**Result:**
+- PASS if all claims addressed
+- GAP listing unaddressed claims
+
+Store result:
+```
+CHECK_2_STATUS="{PASS|GAP}"
+CHECK_2_DETAIL="{M}/{N} claims addressed"
+CHECK_2_GAPS="{list of unaddressed claims, if any}"
+```
+
+If argument-map.md doesn't exist:
+```
+CHECK_2_STATUS="SKIP"
+CHECK_2_DETAIL="No argument-map.md found"
+```
+
+</step>
+
+<step name="check_words">
+**Check 3: Word Targets**
+
+Read `.planning/structure/outline.md` for word budget per section.
+
+For each section:
+- Count actual words in the paper content file
+- Compare to target from outline
+
+**Tolerance:** +/- 15% of target per section
+
+**Result:**
+- PASS if all sections within range
+- GAP listing sections outside range (with actual vs target)
+
+Store result:
+```
+CHECK_3_STATUS="{PASS|GAP}"
+CHECK_3_DETAIL="{N}/{M} sections within range"
+CHECK_3_GAPS="{list of sections outside range: 'Section X: Y words (target: Z, variance: +/-W%)'}"
+```
+
+If outline.md doesn't exist or has no word targets:
+```
+CHECK_3_STATUS="SKIP"
+CHECK_3_DETAIL="No word targets defined in outline.md"
+```
+
+</step>
+
+<step name="check_citations">
+**Check 4: Citation Completeness**
+
+Scan all paper content files for citation patterns:
+- `(Author, Year)` - APA style
+- `\cite{key}` - LaTeX style
+- `[@key]` - Pandoc/markdown style
+- `[N]` - IEEE style
+
+Cross-reference with bibliography file:
+- `references.bib` (BibTeX)
+- `.planning/sources/bibliography.md`
+- Any `.bib` files in project
+
+Check for:
+1. **Uncited references**: Entries in bibliography not cited in text
+2. **Undefined citations**: Citations in text not in bibliography
+
+**Result:**
+- PASS if all citations resolved
+- GAP listing issues
+
+Store result:
+```
+CHECK_4_STATUS="{PASS|GAP}"
+CHECK_4_DETAIL="{N} issues found"
+CHECK_4_GAPS="{list: 'Uncited: [keys]', 'Undefined: [keys]'}"
+```
+
+If no bibliography file found:
+```
+CHECK_4_STATUS="SKIP"
+CHECK_4_DETAIL="No bibliography file found"
+```
+
+</step>
+
+<step name="check_reviews">
+**Check 5: Review Status**
+
+For each section:
+- Check if review SUMMARY.md exists in `.planning/sections/{section}/`
+- Or check if "review: pass" noted in section summary
+
+**Result:**
+- PASS if all sections reviewed
+- GAP listing unreviewed sections
+
+Store result:
+```
+CHECK_5_STATUS="{PASS|GAP}"
+CHECK_5_DETAIL="{M}/{N} sections reviewed"
+CHECK_5_GAPS="{list of unreviewed sections}"
+```
+
+</step>
+
+<step name="write_audit">
+**Step 3: Write MILESTONE-AUDIT.md**
+
+Determine overall status:
+- `OVERALL="PASS"` if all checks pass or skip
+- `OVERALL="GAPS FOUND"` if any check has GAP status
+
+Write `.planning/MILESTONE-AUDIT.md`:
+
+```markdown
+# Milestone Audit
+
+**Date:** {YYYY-MM-DD}
+**Overall:** {PASS | GAPS FOUND}
+
+## Results
+
+| Check | Status | Details |
+|-------|--------|---------|
+| Section Completion | {PASS/GAP/SKIP} | {CHECK_1_DETAIL} |
+| Argument Coverage | {PASS/GAP/SKIP} | {CHECK_2_DETAIL} |
+| Word Targets | {PASS/GAP/SKIP} | {CHECK_3_DETAIL} |
+| Citation Completeness | {PASS/GAP/SKIP} | {CHECK_4_DETAIL} |
+| Review Status | {PASS/GAP/SKIP} | {CHECK_5_DETAIL} |
+
+## Gaps
+
+{For each GAP status, create a subsection:}
+
+### {Check Name}
+- **Status:** gap
+- **Finding:** {what's missing}
+- **Affected:** {sections/claims/files}
+- **Recommendation:** {what to do}
+
+{If no gaps:}
+No gaps found. Paper is ready for submission.
+
+## Summary
+
+{If PASS: "Paper is ready for submission. Run `/wtfp:submit-milestone {version}` to archive."}
+{If GAPS: "Found {N} gaps requiring attention. Run `/wtfp:plan-milestone-gaps` to create fix plans."}
+```
+
+</step>
+
+<step name="present_results">
+**Step 4: Present Results**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ WTF-P ► AUDIT COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Overall: {PASS | GAPS FOUND}
+
+Results:
+  ✓ Section Completion: {details}
+  ✓ Argument Coverage: {details}
+  ✓ Word Targets: {details}
+  ✓ Citation Completeness: {details}
+  ✓ Review Status: {details}
+
+{Use ✓ for PASS, ✗ for GAP, — for SKIP}
+
+Audit saved to: .planning/MILESTONE-AUDIT.md
+
+───────────────────────────────────────────
+
+## Next Up
+
+{If PASS:}
+**Ready to submit:**
+  `/wtfp:submit-milestone {version}`
+
+{If GAPS:}
+**Fix gaps first:**
+  `/wtfp:plan-milestone-gaps` - Create fix plans from audit
+
+───────────────────────────────────────────
+```
+
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] Environment validated
+- [ ] 5 audit checks run (section, argument, word, citation, review)
+- [ ] MILESTONE-AUDIT.md created with pass/gap per check
+- [ ] Gaps include actionable recommendations
+- [ ] Next steps offered based on result
+</success_criteria>