wtf-p 0.3.0 → 0.5.0

package/vendors/claude/commands/wtfp/plan-milestone-gaps.md

@@ -0,0 +1,255 @@
+---
+name: wtfp:plan-milestone-gaps
+description: Create fix plans for gaps found by audit-milestone
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - AskUserQuestion
+---
+
+<objective>
+Read MILESTONE-AUDIT.md and create targeted fix plans for each gap.
+
+Each gap becomes a fix plan in the appropriate section directory.
+Plans follow the standard plan-format.md structure.
+User can execute fix plans with existing writing commands.
+</objective>
+
+<process>
+
+<step name="validate">
+**Step 1: Validate Audit Exists**
+
+```bash
+[ ! -f .planning/MILESTONE-AUDIT.md ] && echo "ERROR: No MILESTONE-AUDIT.md found. Run /wtfp:audit-milestone first." && exit 1
+```
+
+</step>
+
+<step name="banner">
+**Step 2: Display Banner**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ WTF-P ► PLANNING GAP FIXES
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Reading MILESTONE-AUDIT.md...
+```
+
+</step>
+
+<step name="parse_audit">
+**Step 3: Parse MILESTONE-AUDIT.md**
+
+Read `.planning/MILESTONE-AUDIT.md`.
+
+Extract all gaps (sections under "## Gaps" with "Status: gap"):
+- Gap name (check name)
+- Finding (what's missing)
+- Affected (sections/claims/files)
+- Recommendation (what to do)
+
+If no gaps found (Overall: PASS):
+```
+No gaps found in audit. Paper is ready for submission.
+Run /wtfp:submit-milestone {version} to archive.
+```
+Exit early.
+
+</step>
+
+<step name="classify_gaps">
+**Step 4: Classify Gaps by Fix Type**
+
+For each gap, determine fix type:
+
+| Gap Type | Fix Type | Action |
+|----------|----------|--------|
+| Section incomplete | section-write | Generate writing plan for incomplete section |
+| Argument not covered | targeted-write | Generate task to address specific claim in relevant section |
+| Word count over | revision-trim | Generate revision task to reduce word count |
+| Word count under | revision-expand | Generate revision task to expand content |
+| Citation undefined | citation-fix | Generate task to add missing citation |
+| Citation uncited | citation-fix | Generate task to cite or remove reference |
+| Section unreviewed | review-route | Route to /wtfp:review-section |
+
+</step>
+
+<step name="group_gaps">
+**Step 5: Group Related Gaps**
+
+Group gaps that affect the same section:
+- Multiple issues in Section 2 -> one fix plan for Section 2
+- Word count + argument issues in same section -> combined plan
+
+Create plan groupings:
+```
+PLAN_1: Section 02 - {word count issue, argument issue}
+PLAN_2: Section 04 - {incomplete}
+PLAN_3: Citations - {undefined citations across multiple sections}
+```
+
+</step>
+
+<step name="generate_plans">
+**Step 6: Generate Fix Plans**
+
+For each grouped plan, create a fix plan file.
+
+**Location:** `.planning/sections/XX-name/{section}-fix-{N}-PLAN.md`
+
+**Plan structure (following plan-format.md):**
+
+```markdown
+---
+section: {section-number}
+plan: fix-{N}
+type: revision
+depends_on: []
+files_modified:
+  - {paper content file}
+autonomous: true
+---
+
+<objective>
+Fix {N} gap(s) identified in milestone audit:
+- {gap 1 summary}
+- {gap 2 summary}
+
+Purpose: Address audit findings before submission.
+</objective>
+
+<context>
+@.planning/MILESTONE-AUDIT.md
+@.planning/sections/XX-name/{relevant summaries}
+@{paper content file}
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>{fix task name}</name>
+  <files>
+    {file to modify}
+  </files>
+  <action>
+{Specific fix instructions based on gap type:}
+
+**For section incomplete:**
+Complete the section draft following the outline.
+- Address all planned subsections
+- Meet word target: {X} words
+- Include required citations
+
+**For argument not covered:**
+Add content to address claim: "{claim}"
+- Insert in section: {section}
+- Location: {suggested location}
+- Approximate addition: {X} words
+
+**For word count over:**
+Reduce word count in {section} by {N} words.
+- Current: {X} words
+- Target: {Y} words
+- Suggested cuts: {areas}
+
+**For word count under:**
+Expand content in {section} by {N} words.
+- Current: {X} words
+- Target: {Y} words
+- Suggested expansions: {areas}
+
+**For citation undefined:**
+Add citation for: {key}
+- Add to bibliography file
+- Verify citation format matches style guide
+
+**For citation uncited:**
+Either cite or remove: {key}
+- If relevant: add citation in appropriate section
+- If not relevant: remove from bibliography
+  </action>
+  <verify>
+{Verification for fix type:}
+
+For section: Word count meets target, all subsections complete.
+For argument: Claim is now addressed in text.
+For word count: Section is within +/- 15% of target.
+For citation: Citation resolves correctly.
+  </verify>
+  <done>
+{Done criteria: Gap resolved per audit check}
+  </done>
+</task>
+
+</tasks>
+
+<verification>
+- Gap addressed per MILESTONE-AUDIT.md finding
+- No new issues introduced
+</verification>
+
+<success_criteria>
+- [ ] {Gap 1} resolved
+- [ ] {Gap 2} resolved
+</success_criteria>
+```
+
+**For unreviewed sections (review-route):**
+
+Don't generate a fix plan. Instead, note:
+```
+Section {X} needs review. Run: /wtfp:review-section {section}
+```
+
+</step>
+
+<step name="summary">
+**Step 7: Present Summary**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ WTF-P ► GAP PLANS CREATED ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Plans created: {N}
+
+| Plan | Section | Gaps Addressed |
+|------|---------|----------------|
+| {path} | {section} | {gap list} |
+| {path} | {section} | {gap list} |
+
+{If any review-route gaps:}
+Sections needing review (no plan created):
+- Section {X}: Run `/wtfp:review-section {section}`
+
+───────────────────────────────────────────
+
+## Next Up
+
+Execute fix plans:
+  `/wtfp:write-section {path-to-fix-plan}`
+
+Or fix one at a time:
+  Read the plan, then execute tasks manually
+
+After all fixes:
+  `/wtfp:audit-milestone` - Re-run audit to verify
+
+───────────────────────────────────────────
+```
+
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] MILESTONE-AUDIT.md parsed successfully
+- [ ] Gaps classified by fix type
+- [ ] Related gaps grouped by section
+- [ ] Fix plans created for each gap group
+- [ ] Plans follow plan-format.md structure
+- [ ] User knows which plans to execute next
+</success_criteria>

package/vendors/claude/commands/wtfp/plan-revision.md

@@ -1,6 +1,6 @@
 ---
 name: wtfp:plan-revision
-description: Create fix plan from review issues
+description: Create revision plan from review issues
 argument-hint: "[plan]"
 allowed-tools:
   - Read

package/vendors/claude/commands/wtfp/plan-section.md

@@ -1,6 +1,6 @@
 ---
 name: wtfp:plan-section
-description: Create detailed writing plan for a section (PLAN.md)
+description: Create detailed writing plan for a section
 argument-hint: "[section]"
 allowed-tools:
   - Read
@@ -8,240 +8,215 @@ allowed-tools:
   - Write
   - Glob
   - Grep
+  - Task
   - AskUserQuestion
-  - WebFetch
-  - mcp__context7__*
 ---
 
-<objective>
-Create executable writing plan with context injection and task breakdown.
-
-Purpose: Break down roadmap sections into concrete, executable PLAN.md files that Claude can execute.
-Output: One or more PLAN.md files in the section directory (.planning/sections/XX-name/{section}-{plan}-PLAN.md)
-</objective>
-
 <execution_context>
-@~/.claude/write-the-f-paper/workflows/plan-section.md
-@~/.claude/write-the-f-paper/templates/phase-prompt.md
 @~/.claude/write-the-f-paper/references/plan-format.md
 @~/.claude/write-the-f-paper/references/length-estimation.md
-@~/.claude/write-the-f-paper/references/checkpoints.md
 </execution_context>
 
+<objective>
+Create executable writing plan with context injection and task breakdown.
+
+**Orchestrator role:** Parse arguments, validate section, load context, resolve model profile, spawn section-planner agent, optionally verify plans with plan-checker, iterate until plans pass, present results.
+
+**Why subagents:** Planning and verification burn context fast. Fresh agents get peak quality. User sees flow between agents in main context.
+</objective>
+
 <context>
 Section number: $ARGUMENTS (optional - auto-detects next unplanned section if not provided)
+</context>
 
-**Load project state first:**
-@.planning/STATE.md
+<process>
 
-**Load roadmap:**
-@.planning/ROADMAP.md
+## 1. Validate Environment and Resolve Model Profile
 
-**Load structure documents:**
-@.planning/structure/argument-map.md
-@.planning/structure/outline.md
-@.planning/structure/narrative-arc.md
+```bash
+ls .planning/ 2>/dev/null
+```
 
-**Load section context if exists (created by /wtfp:discuss-section):**
-Check for and read `.planning/sections/XX-name/{section}-CONTEXT.md` - contains vision and decisions from section discussion.
+**If not found:** Error - user should run `/wtfp:new-paper` first.
 
-**Load sources if exists:**
-Check for `.planning/sources/` and load relevant documents based on section needs.
-</context>
+**Resolve model profile:**
 
-<process>
+```bash
+MODEL_PROFILE=$(cat .planning/config.json 2>/dev/null | grep -o '"model_profile"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "balanced")
+```
 
-<step name="verify">
-1. Check .planning/ directory exists (error if not - user should run /wtfp:new-paper)
-2. If section number provided via $ARGUMENTS, validate it exists in roadmap
-3. If no section number, detect next unplanned section from roadmap
-</step>
-
-<step name="load_context">
-**Load all relevant context:**
-
-- Read PROJECT.md for paper vision and core argument
-- Read ROADMAP.md for section goal and dependencies
-- Read argument-map.md for claims relevant to this section
-- Read outline.md for word budget and structure
-- Read any prior SUMMARY.md files for context from completed sections
-- Check for CONTEXT.md in section directory
-- Check for RESEARCH.md in section directory
-</step>
-
-<step name="writing_mode">
-**Determine writing mode for this section:**
-
-Based on section type and user preference, select mode:
-
-| Section Type | Recommended Mode |
-|--------------|------------------|
-| Abstract | Reviewer (user writes, Claude critiques) |
-| Introduction | Co-Author (Claude drafts, user refines) |
-| Methods | Co-Author (often procedural) |
-| Results | Scaffold (Claude outlines, user writes) |
-| Discussion | Reviewer (requires judgment) |
-| Conclusion | Reviewer (synthesis) |
-
-Use AskUserQuestion:
-- header: "Writing Mode"
-- question: "How should Claude help with [section name]?"
-- options:
-  - "Co-Author" — Claude drafts, you refine
-  - "Scaffold" — Claude outlines, you fill in
-  - "Reviewer" — You write, Claude critiques
-
-</step>
-
-<step name="break_into_tasks">
-**Break section into writing tasks:**
-
-Consider:
-- Word target for section
-- Logical subsections or paragraphs
-- Arguments that need to be made
-- Evidence that needs to be presented
-- Citations that need to be woven in
-
-For a typical section (500-1000 words):
-- Task 1: Opening hook + context setup
-- Task 2: Main argument development
-- Task 3: Evidence and support
-- Task 4: Transition to next section
-
-Keep tasks atomic (one paragraph cluster or argument each).
-</step>
-
-<step name="create_plan">
-**Create PLAN.md:**
-
-```markdown
----
-section: XX-name
-plan: YY
-mode: [co-author/scaffold/reviewer]
-word_target: [X]
----
+**Model lookup table:**
 
-<objective>
-[What this plan accomplishes - 1-2 sentences]
+| Agent | quality | balanced | budget |
+|-------|---------|----------|--------|
+| section-planner | opus | opus | sonnet |
+| plan-checker | sonnet | sonnet | haiku |
 
-Purpose: [What the reader will understand after this section]
-Output: [Word count] words of [section type] covering [topics]
-</objective>
+**Resolve gate flag:**
+```bash
+# Gate: confirm_plan — skip confirmation if false
+GATE_CONFIRM_PLAN=$(cat .planning/config.json 2>/dev/null | grep -o '"confirm_plan"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
+```
 
-<execution_context>
-@~/.claude/write-the-f-paper/workflows/execute-section.md
-@~/.claude/write-the-f-paper/templates/summary.md
-</execution_context>
+## 1b. Git Branch Setup
 
-<context>
-@.planning/PROJECT.md
-@.planning/ROADMAP.md
-@.planning/structure/argument-map.md
-@.planning/sources/literature.md (if relevant)
-@.planning/sections/[prior-section]/[prior]-SUMMARY.md (if exists)
-</context>
+```bash
+BRANCH_STRATEGY=$(cat .planning/config.json 2>/dev/null | grep -o '"branching_strategy"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "none")
+```
 
-<tasks>
-
-<task type="auto" mode="[co-author/scaffold/reviewer]">
-  <name>[Task name - what's being written]</name>
-  <target>[Word count for this task]</target>
-  <action>
-    [Specific writing instructions]
-    - Key points to make: [list]
-    - Tone: [academic/persuasive/explanatory]
-    - Citations needed: [yes/no, which]
-    - Connect to: [prior/next section]
-  </action>
-  <verify>
-    - [ ] Advances core argument
-    - [ ] Word count within range
-    - [ ] Flows from previous content
-  </verify>
-  <done>
-    [X] words written covering [topic], ready for [next task/review]
-  </done>
-</task>
-
-<task type="auto" mode="[mode]">
-  [... additional tasks ...]
-</task>
-
-</tasks>
-
-<verification>
-- [ ] Total word count: [target] ± 10%
-- [ ] All key arguments from argument-map addressed
-- [ ] Citations included where claims made
-- [ ] Logical flow maintained
-- [ ] Connects to prior section (if not first)
-- [ ] Sets up next section (if not last)
-</verification>
+**If branching_strategy = "section":**
 
-<success_criteria>
-- [ ] Section draft complete
-- [ ] Word target met
-- [ ] Core argument advanced
-- [ ] Ready for review or next section
-</success_criteria>
+1. Read section_branch_template from config (default: `wtfp/section-{section}-{slug}`)
+2. Replace `{section}` with zero-padded section number (e.g., `01`, `02`)
+3. Replace `{slug}` with slugified section name (lowercase, hyphens)
+4. Store current branch as base branch for later merge:
+   ```bash
+   BASE_BRANCH=$(git branch --show-current 2>/dev/null || echo "main")
+   echo "$BASE_BRANCH" > .planning/.section_base_branch
+   ```
+5. Create and checkout section branch:
+   ```bash
+   SECTION_BRANCH_TEMPLATE=$(cat .planning/config.json 2>/dev/null | grep -o '"section_branch_template"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "wtfp/section-{section}-{slug}")
+   BRANCH_NAME=$(echo "$SECTION_BRANCH_TEMPLATE" | sed "s/{section}/${SECTION_NUM}/" | sed "s/{slug}/${SECTION_SLUG}/")
+   git checkout -b "$BRANCH_NAME"
+   ```
+6. Log: "Created section branch: $BRANCH_NAME"
+
+**If branching_strategy = "none" or "submission":** No branch action in plan-section.
+
+## 2. Parse and Normalize Arguments
+
+Extract section number from $ARGUMENTS. If no section number, detect next unplanned section from roadmap.
+
+```bash
+ls .planning/sections/*/ 2>/dev/null | head -10
+```
+
+## 3. Validate Section
+
+```bash
+grep -A5 "Section" .planning/ROADMAP.md 2>/dev/null
+```
+
+Extract section number, name, description.
 
-<output>
-- Written section content (in paper/ directory or inline)
-- SUMMARY.md documenting what was written
-- Updated STATE.md with progress
-</output>
+## 4. Ensure Section Directory and Load CONTEXT.md
+
+```bash
+SECTION_DIR=$(ls -d .planning/sections/${SECTION}-* 2>/dev/null | head -1)
+CONTEXT_CONTENT=$(cat "${SECTION_DIR}"/*-CONTEXT.md 2>/dev/null)
 ```
 
-</step>
+**CRITICAL:** Store CONTEXT_CONTENT now. Pass to ALL downstream agents.
+
+## 5. Read Context Files
 
-<step name="commit">
 ```bash
-git add .planning/sections/XX-name/XX-YY-PLAN.md
-git commit -m "$(cat <<'EOF'
-plan(XX-YY): [section name] writing plan
+STATE_CONTENT=$(cat .planning/STATE.md)
+ROADMAP_CONTENT=$(cat .planning/ROADMAP.md)
+PROJECT_CONTENT=$(cat .planning/PROJECT.md)
+ARGMAP_CONTENT=$(cat .planning/structure/argument-map.md 2>/dev/null)
+OUTLINE_CONTENT=$(cat .planning/structure/outline.md 2>/dev/null)
+RESEARCH_CONTENT=$(cat "${SECTION_DIR}"/*-RESEARCH.md 2>/dev/null)
+PRIOR_SUMMARIES=$(cat .planning/sections/*/SUMMARY.md 2>/dev/null | head -200)
+```
+
+If RESEARCH.md missing for a literature-heavy section, suggest `/wtfp:research-gap` first.
+
+## 6. Gate Check: Confirm Before Planning
+
+**If GATE_CONFIRM_PLAN is "true" (default):**
+Present section context summary to user via AskUserQuestion and wait for confirmation before proceeding.
+
+**If GATE_CONFIRM_PLAN is "false":**
+Skip confirmation and proceed directly to planning.
 
-[One-liner objective]
+## 7. Spawn wtfp-section-planner Agent
 
-Tasks: [N], Target: [X] words, Mode: [mode]
-EOF
-)"
 ```
-</step>
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ WTF-P ► PLANNING SECTION {X}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
 
-<step name="done">
-**Present completion:**
+Fill prompt with inlined content and spawn:
 
 ```
-Plan created:
+Task(
+  prompt="First, read ~/.claude/agents/wtfp/section-planner.md for your role and instructions.\n\n" + filled_planning_prompt,
+  subagent_type="general-purpose",
+  model="{planner_model}",
+  description="Plan Section {X}"
+)
+```
 
-- Plan: .planning/sections/XX-name/XX-YY-PLAN.md
-- Tasks: [N]
-- Word target: [X]
-- Mode: [co-author/scaffold/reviewer]
+Planning prompt includes: `<planning_context>` with STATE, ROADMAP, PROJECT, argument-map, outline, RESEARCH, prior summaries. `<user_decisions>` with CONTEXT_CONTENT. `<output>` with target directory path.
 
----
+## 8. Handle Planner Return
 
-## ▶ Next Up
+**`## PLANNING COMPLETE`:** Display plan count, proceed to verification check.
 
-**[Section Name]** — execute writing plan
+**`## CHECKPOINT REACHED`:** Present to user, get response.
 
-`/wtfp:write-section .planning/sections/XX-name/XX-YY-PLAN.md`
+**`## PLANNING INCONCLUSIVE`:** Show what was attempted, offer options.
 
-<sub>`/clear` first → fresh context window</sub>
+## 8. Plan-Check-Revise Loop (if enabled)
 
----
+```bash
+WORKFLOW_PLAN_CHECK=$(cat .planning/config.json 2>/dev/null | grep -o '"plan_check"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
 ```
 
-</step>
+**If plan_check is true:**
+
+Read plans for checker:
+```bash
+PLANS_CONTENT=$(cat "${SECTION_DIR}"/*-PLAN.md 2>/dev/null)
+```
+
+Spawn `wtfp-plan-checker` with plans + ROADMAP + argument-map + CONTEXT.
+
+**If VERIFICATION PASSED:** Proceed to done.
+
+**If ISSUES FOUND and iteration < 3:** Spawn planner in revision mode with issues. Re-check. Increment iteration.
+
+**If iteration >= 3:** Present remaining issues to user with options: force proceed, provide guidance, abandon.
+
+## 9. Present Final Status
 
 </process>
 
+<offer_next>
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ WTF-P ► SECTION {X} PLANNED ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Section {X}: {Name}** — {N} plan(s), {W} words target
+
+Verification: {Passed | Passed with override | Skipped}
+
+───────────────────────────────────────────
+
+## ▶ Next Up
+
+**Execute writing** — run the plan
+
+`/wtfp:write-section .planning/sections/XX-name/XX-YY-PLAN.md`
+
+<sub>`/clear` first → fresh context window</sub>
+
+───────────────────────────────────────────
+
+</offer_next>
+
 <success_criteria>
-- One or more PLAN.md files created in .planning/sections/XX-name/
-- Each plan has: objective, execution_context, context, tasks, verification, success_criteria, output
-- Tasks are specific enough for Claude to execute
-- Writing mode selected appropriately for section type
-- User knows next steps (execute plan or review/adjust)
+- [ ] .planning/ directory validated
+- [ ] Section validated against roadmap
+- [ ] CONTEXT.md loaded early and passed to ALL agents
+- [ ] RESEARCH.md auto-loaded if exists
+- [ ] Section-planner spawned with full context
+- [ ] Plans created (PLANNING COMPLETE or CHECKPOINT handled)
+- [ ] Plan-checker spawned (if workflow.plan_check enabled)
+- [ ] Verification passed OR user override OR max iterations
+- [ ] User knows next steps
 </success_criteria>