wtf-p 0.3.0 → 0.5.0

package/core/write-the-f-paper/workflows/plan-section.wcn.md

@@ -9,15 +9,25 @@ Validation: X exists+complete, X+1 exists, X.Y doesn't exist, Y >= 1
 READ: ~/.claude/write-the-f-paper/templates/section-prompt.md
 READ: ~/.claude/write-the-f-paper/references/plan-format.md
 READ: ~/.claude/write-the-f-paper/references/verification-layers.md
+READ: ~/.claude/write-the-f-paper/references/orchestrator-pattern.md
+READ: ~/.claude/write-the-f-paper/references/context-fidelity.md
+READ: ~/.claude/write-the-f-paper/references/agent-model-matrix.md
 READ: .planning/ROADMAP.md
 READ: .planning/PROJECT.md
 LOAD: .planning/structure/argument-map.md, outline.md, narrative-arc.md
 </required_reading>
 
 <purpose>
-Create executable section prompt (PLAN.md). PLAN.md IS the prompt Claude executes - not a doc that gets transformed.
+Create executable section prompt (PLAN.md) via thin orchestrator pattern. Orchestrator validates, loads context, resolves model profile, spawns section-planner agent, then runs plan-checker for quality verification. PLAN.md IS the prompt Claude executes - not a doc that gets transformed.
 </purpose>
 
+<architecture>
+ORCHESTRATOR: /wtfp:plan-section (this command)
+AGENTS: section-planner (creates PLAN.md), plan-checker (validates PLAN.md)
+PATTERN: Orchestrator loads context → spawns planner → spawns checker → revise loop if needed
+WHY_SUBAGENTS: Fresh context windows for peak quality. Planner gets full project context without orchestrator overhead. Checker validates independently.
+</architecture>
+
 <planning_principles>
 Argument-first: Every paragraph serves core argument. Plan prose that advances thesis, not filler.
 Evidence-grounded: Plan where citations go before writing. Claims need sources identified.
@@ -26,7 +36,18 @@ Reader-aware: Plan for target audience. Technical depth, assumed knowledge, expl
 
 <process>
 
-[step:load_project_state p=1]
+[step:validate_and_resolve_model p=1]
+RUN: ls .planning/ 2>/dev/null
+RUN: MODEL_PROFILE=$(cat .planning/config.json 2>/dev/null | grep -o '"model_profile"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "balanced")
+
+MODEL_LOOKUP{agent,quality,balanced,budget}:
+  section-planner | opus | opus | sonnet
+  plan-checker | sonnet | sonnet | haiku
+
+RESOLVE: planner_model, checker_model from MODEL_PROFILE
+[/step]
+
+[step:load_project_state]
 READ: .planning/STATE.md
 PARSE: current_position, accumulated_decisions, open_questions, argument_strength
 IF missing+.planning_exists → OFFER reconstruct|continue
@@ -56,14 +77,27 @@ IF decimal → validate: X complete, X+1 exists, X.Y doesn't exist, Y >= 1
 READ: existing PLAN.md or RESEARCH.md in section dir
 [/step]
 
+[step:load_context_md]
+CRITICAL: Load CONTEXT.md early, pass to ALL agents.
+
+RUN: SECTION_DIR=$(ls -d .planning/sections/${SECTION}-* 2>/dev/null | head -1)
+RUN: CONTEXT_CONTENT=$(cat "${SECTION_DIR}"/*-CONTEXT.md 2>/dev/null)
+
+IF CONTEXT.md exists → store for injection into planner prompt as <user_decisions>
+  HONOR: locked decisions, boundaries, vision
+  EXCLUDE: deferred ideas
+  ALLOW: discretion areas
+IF missing → SUGGEST: /wtfp:discuss-section (simpler) or proceed without
+[/step]
+
 [step:mandatory_literature_check]
 MANDATORY for sections flagged Research: Likely
 
 LIT_LEVEL{level,desc,action}:
   0-skip | internal content only, no external evidence | skip
-  1-quick | single source verify, 2-5 min | quick check, no RESEARCH.md
-  2-standard | multiple sources, positioning, 15-30 min | /wtfp:research-gap → RESEARCH.md
-  3-deep | core lit review, theoretical framework, 1+ hr | /wtfp:research-gap depth=deep → full RESEARCH.md
+  1-quick | single source verify | quick check, no RESEARCH.md
+  2-standard | multiple sources, positioning | /wtfp:research-gap → RESEARCH.md
+  3-deep | core lit review, theoretical framework | /wtfp:research-gap depth=deep → full RESEARCH.md
 
 IF roadmap=Research:Likely → Level 0 not available
 [/step]
@@ -72,112 +106,70 @@ IF roadmap=Research:Likely → Level 0 not available
 RUN: for f in .planning/sections/*/*-SUMMARY.md; do sed -n '1,/^---$/p' "$f" | head -30; done
 PARSE: section, subsection, key-claims, evidence-used, decisions
 
-BUILD context:
-- Check logical flow (what claims does this section build on?)
-- Check evidence used (what sources already cited?)
-- Check decisions (stylistic/structural constraints?)
-
 AUTO-SELECT sections matching:
 - Immediate prior section
 - Same argumentative thread
 - Mentioned in STATE.md as affecting current
 
-EXTRACT from selected:
-- Claims established
-- Evidence cited (avoid over-citation)
-- Patterns established (style, terminology)
-- Decisions
-
-ANSWER before proceeding:
-Q1: What claims from previous sections does this build on?
-Q2: What sources already cited might be relevant?
-Q3: What writing patterns to maintain?
-Q4: Does roadmap goal still make sense given context?
+EXTRACT: claims established, evidence cited, patterns, decisions
 [/step]
 
-[step:gather_section_context]
-UNDERSTAND: section_goal, word_budget, existing_drafts, dependencies_met
-
-RUN: cat .planning/sections/XX-name/${SECTION}-RESEARCH.md 2>/dev/null
-RUN: cat .planning/sections/XX-name/${SECTION}-CONTEXT.md 2>/dev/null
-RUN: cat .planning/sources/prior-drafts.md 2>/dev/null
-
-IF RESEARCH.md → USE: sources (cite), key_findings (incorporate), gaps (address), positioning
-IF CONTEXT.md → HONOR: vision, essential content, boundaries, user specifics
-IF neither → SUGGEST: /wtfp:research-gap (lit-heavy) or /wtfp:discuss-section (simpler)
-[/step]
-
-[step:break_into_tasks]
-Decompose section into writing tasks.
-
-TASK_FIELDS:
-- Type: auto | checkpoint:human-verify | checkpoint:decision
-- Name: clear, action-oriented
-- Paragraphs/Subsections: which part
-- Action: draft | revise | cite | strengthen
-- Mode: co-author (Claude drafts) | scaffold (Claude outlines) | reviewer (Claude critiques)
-- Verify: how to prove done well
-- Done: acceptance criteria
-
-TASKS_BY_SECTION{section → typical_tasks}:
-  abstract | draft complete, verify elements
-  intro | hook, context, gap, thesis, roadmap
-  methods | protocol, measures, analysis approach
-  results | finding narratives, supporting analyses
-  discussion | summary, interpretation, limitations, future work, conclusion
-  related_work | theme syntheses, positioning statement
-
-MODE_SELECT:
-- Procedural content (methods, data) → co-author
-- Argument-heavy (discussion, intro) → scaffold | reviewer
-- Personal voice (abstract conclusion, thesis) → scaffold + user writing
-
-CHECKPOINTS: visual/prose verify → human-verify. Voice/framing choices → decision.
+[step:spawn_section_planner]
+EMIT:
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   WTF-P ► PLANNING SECTION {X}
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+BUILD planner_prompt with inlined content:
+- <planning_context> STATE, ROADMAP, PROJECT, argument-map, outline, RESEARCH, prior summaries
+- <user_decisions> CONTEXT_CONTENT (from CONTEXT.md)
+- <output> target directory path
+
+SPAWN:
+  Task(
+    prompt="First, read ~/.claude/agents/wtfp/section-planner.md for your role and instructions.\n\n" + planner_prompt,
+    subagent_type="general-purpose",
+    model="{planner_model}",
+    description="Plan Section {X}"
+  )
+
+HANDLE returns:
+  "## PLANNING COMPLETE" → proceed to plan-checker
+  "## CHECKPOINT REACHED" → present to user, wait
+  "## PLANNING BLOCKED" → present blocker, ask user
 [/step]
 
-[step:estimate_scope]
-RUN: cat .planning/config.json 2>/dev/null | grep depth
+[step:spawn_plan_checker]
+IF config.workflow.plan_check=false → SKIP to git_commit
 
-DEPTH{level,plans_per,tasks_per}:
-  quick | 1-2 | 2-3
-  standard | 2-4 | 2-3
-  comprehensive | 3-6 | 2-3
+SPAWN:
+  Task(
+    prompt="First, read ~/.claude/agents/wtfp/plan-checker.md for your role and instructions.\n\n" + checker_prompt_with_PLAN_content,
+    subagent_type="general-purpose",
+    model="{checker_model}",
+    description="Check Plan {section}-01"
+  )
 
-PRINCIPLE: Derive plans from actual writing needs. Depth = how carefully to break down complex sections.
-- Comprehensive Discussion = 4 plans (interpretation, limitations, future work, conclusion)
-- Comprehensive Abstract = 1 plan (one paragraph)
-
-ALWAYS_SPLIT if: >3 tasks, multiple threads, complex lit integration
-EACH_PLAN must be: 2-3 tasks max, focused on one aspect, independently verifiable
-[/step]
-
-[step:confirm_breakdown]
-IF mode=yolo → auto-approve, proceed
-IF mode=interactive → present breakdown:
-  "Section [X] breakdown:
-   ### Tasks ({section}-01-PLAN.md)
-   1. [Task] - [brief] [type] [mode]
-   2. [Task] - [brief] [type] [mode]
-   Does this look right? (yes/adjust/start over)"
-
-IF adjust → revise
-IF start_over → return to gather_section_context
+HANDLE returns:
+  "## CHECK PASSED" → proceed to git_commit
+  "## ISSUES FOUND" → enter revise loop
 [/step]
 
-[step:write_section_prompt]
-READ: ~/.claude/write-the-f-paper/templates/section-prompt.md
-
-SINGLE_PLAN → .planning/sections/XX-name/{section}-01-PLAN.md
-MULTI_PLAN → {section}-01-PLAN.md, {section}-02-PLAN.md, etc.
-
-EACH_PLAN includes:
-- Frontmatter (section, plan, type, mode)
-- Objective (goal, word target, output)
-- Execution context (write-section.md, summary template, verification-layers.md)
-- Context (@refs: PROJECT, ROADMAP, STATE, structure docs, RESEARCH/CONTEXT, prior summaries, sources)
-- Tasks (XML format with types/modes)
-- Verification (citation, coherence, rubric checks)
-- Success criteria, Output specification
+[step:plan_check_revise_loop]
+IF checker returns ISSUES:
+  MAX_REVISIONS: 2
+
+  LOOP:
+    1. Present issues to user (or auto-fix if minor)
+    2. Re-spawn section-planner with issues as feedback
+    3. Re-spawn plan-checker on revised plan
+    4. IF passed → proceed
+    5. IF max_revisions reached → present remaining issues, ask user
+
+ISSUE_CATEGORIES:
+  auto-fix | missing citation placeholder, word budget off | planner revises
+  user-decision | structural concern, scope question | present to user
+  acceptable | style preference, minor suggestion | log and proceed
 [/step]
 
 [step:git_commit]
@@ -190,7 +182,7 @@ EMIT: "Committed: docs(${SECTION}): create section plan"
 [step:offer_next]
 EMIT:
   Section plan created: .planning/sections/XX-name/{section}-01-PLAN.md
-  [X] tasks defined.
+  [X] tasks defined. Plan check: [PASSED/SKIPPED]
 
   Next: {section}-01: [Plan Name] - [objective]
   → /wtfp:write-section .planning/sections/XX-name/{section}-01-PLAN.md
@@ -221,16 +213,17 @@ Tasks = instructions for Claude writing, not editorial board requirements.
 </anti_patterns>
 
 <success_criteria>
+- [ ] Model profile resolved, agent models determined
 - [ ] STATE.md read, project context absorbed
+- [ ] CONTEXT.md loaded early and passed to ALL agents
 - [ ] Mandatory literature check completed (Level 0-3)
 - [ ] Prior sections, sources, structure synthesized
+- [ ] Section-planner agent spawned with full context
 - [ ] PLAN file(s) exist with XML structure
-- [ ] Each plan: Objective, context, tasks, verification, success criteria, output
-- [ ] @context references included (STATE, RESEARCH if exist, relevant summaries)
+- [ ] Plan-checker agent validated plan (or skipped per config)
+- [ ] Plan-check-revise loop completed if issues found
 - [ ] Each plan: 2-3 tasks (~focused scope)
 - [ ] Each task: Type, Mode, Paragraphs (if applicable), Action, Verify, Done
-- [ ] Checkpoints properly structured
-- [ ] If RESEARCH.md exists: sources cited in plan, positioning clear
 - [ ] PLAN file(s) committed to git
 - [ ] User knows next steps
 </success_criteria>

package/core/write-the-f-paper/workflows/research-gap.md

@@ -188,17 +188,21 @@ Execute research systematically.
 
 **CRITICAL: Source hierarchy**
 
-1. **User's own sources first:**
+1. **Context7 MCP first (if available):**
+   - Query Context7 for relevant documentation and sources
+   - Highest quality, most relevant results
+
+2. **User's own sources second:**
    - Check .planning/sources/literature.md
    - Check .planning/sources/prior-drafts.md for cited works
    - User may have PDFs or notes to reference
 
-2. **Database search (conceptual):**
+3. **Official sources/databases third:**
    - Google Scholar for academic sources
    - Field-specific databases (PubMed, IEEE, ACL, etc.)
    - Preprint servers (arXiv, SSRN, bioRxiv)
 
-3. **WebSearch for recent/emerging work:**
+4. **WebSearch last (for recent/emerging work):**
    ```
    "[topic] research [current_year]"
    "[topic] systematic review"
@@ -206,6 +210,19 @@ Execute research systematically.
    "[author name] [topic]" for known experts
    ```
 
+**Depth-conditional instructions:**
+
+**If depth is "standard":**
+- Target 10-20 relevant sources across categories
+- Focus on most impactful papers for each category
+- Categories are recommended but not all mandatory
+
+**If depth is "deep":**
+- Target 20-50 sources
+- Systematically map the field: research groups, venues, citation networks, methodology variants
+- Every category (foundational, recent, competing, gap, methods) is MANDATORY
+- Include intellectual lineage and funding landscape
+
 <research_protocol>
 
 **For each research category:**
@@ -290,6 +307,13 @@ Create it: `.planning/sections/${SECTION}-${SLUG}/`
 **Structure:**
 
 ```markdown
+---
+depth: {quick|standard|deep}
+confidence: {HIGH|MEDIUM|LOW}
+sources_count: {N}
+researched: {YYYY-MM-DD}
+---
+
 # Literature Research: [Topic/Section]
 
 ## Research Summary

package/core/write-the-f-paper/workflows/research-gap.wcn.md

@@ -62,13 +62,30 @@ RUN: cat .planning/sections/${SECTION}-*/${SECTION}-CONTEXT.md 2>/dev/null
 [/step]
 
 [step:execute_research]
+**CRITICAL: Source hierarchy**
+1. Context7 MCP first (if available) → highest quality, most relevant
+2. User's own sources → .planning/sources/literature.md, prior-drafts.md, PDFs
+3. Official sources/databases → Google Scholar, PubMed, IEEE, ACL, arXiv, SSRN
+4. WebSearch last → "[topic] research [year]", "[topic] systematic review"
+
+MODE{depth}:
+| standard | 10-20 sources, focus most impactful, categories recommended not mandatory |
+| deep | 20-50 sources, map field systematically, ALL categories MANDATORY, include lineage+funding |
+
+Per category: identify 3-5 foundational + 5-10 recent + 2-3 competing + gap evidence.
+Per source: full citation, key findings, relation to work, where to cite.
+Synthesize: group by argument, consensus vs controversy, methodological trends, gap.
+Cross-verify: legitimate academic work, citation counts, recency, confidence level.
 [/step]
 
 [step:quality_check]
 [/step]
 
 [step:write_research]
-IF section_directory_doesnt_exist → Create it: `.planning/sections/${SECTION}-${SLU...
+IF section_directory_doesnt_exist → Create it: `.planning/sections/${SECTION}-${SLUG}/`
+Output: `.planning/sections/${SECTION}-${SLUG}/${SECTION}-RESEARCH.md`
+Frontmatter: depth, confidence (HIGH/MEDIUM/LOW), sources_count, researched (YYYY-MM-DD)
+Sections: Research Summary, Key Findings (Foundational/Recent/Competing/Gap/Methods), Synthesis for Writing (Intro/Related Work/Discussion), Full Bibliography, Confidence Assessment.
 [/step]
 
 [step:update_literature_index]

package/core/write-the-f-paper/workflows/verify-work.md

@@ -0,0 +1,251 @@
+<purpose>
+Conversational section acceptance testing. Present tests one at a time derived from
+PLAN.md success criteria and argument-map.md claims. Persist state in UAT.md that
+survives /clear. Route to plan-revision when issues are found.
+
+The USER evaluates each test — Claude presents, records, and routes.
+</purpose>
+
+<process>
+
+<step name="load_state">
+**Load project state and config:**
+
+```bash
+cat .planning/STATE.md 2>/dev/null
+cat .planning/config.json 2>/dev/null
+```
+
+Parse current position, accumulated decisions. Load planning config for commit_docs flag.
+
+```bash
+COMMIT_DOCS=$(cat .planning/config.json 2>/dev/null | grep -o '"commit_docs"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
+```
+</step>
+
+<step name="find_section">
+**Resolve section from arguments:**
+
+Parse $ARGUMENTS as section number (e.g., "3") or section name (e.g., "methods").
+
+```bash
+# Find section directory
+SECTION_DIR=$(ls -d .planning/sections/${SECTION}-* 2>/dev/null | head -1)
+[ -z "$SECTION_DIR" ] && echo "ERROR: Section not found" && exit 1
+```
+
+**Validate section was written:**
+
+```bash
+ls "$SECTION_DIR"/*-SUMMARY.md 2>/dev/null
+```
+
+If no SUMMARY.md exists, the section has not been written yet. Cannot verify unwritten content.
+
+Present error:
+```
+Section [X] has not been written yet.
+
+Write it first: /wtfp:write-section [plan-path]
+```
+</step>
+
+<step name="load_or_create_uat">
+**Check for existing UAT.md:**
+
+```bash
+UAT_PATH="$SECTION_DIR/UAT.md"
+[ -f "$UAT_PATH" ] && echo "EXISTING" || echo "NEW"
+```
+
+**If UAT.md exists (resuming):**
+- Read UAT.md
+- Count total tests, completed tests, pending tests
+- Find next test with `result: pending`
+- Report: "Resuming verification (N/M tests complete)"
+
+**If UAT.md does not exist (new verification):**
+
+Derive tests from two sources:
+
+1. **PLAN.md success criteria:**
+   ```bash
+   cat "$SECTION_DIR"/*-PLAN.md
+   ```
+   Extract each item from `<success_criteria>` section. Each `- [ ]` item becomes a test.
+
+2. **Argument-map claims for this section:**
+   ```bash
+   cat .planning/structure/argument-map.md 2>/dev/null
+   ```
+   Find claims mapped to this section number. Each claim becomes a test.
+
+**Generate test list:** Combine both sources. Each test gets:
+- Sequential number
+- Source label: `[plan]` or `[argument-map]`
+- The criterion or claim text
+- `result: pending`
+- `reason: ""`
+
+**Write UAT.md** using template format:
+```yaml
+---
+status: testing
+section: XX-name
+started: [ISO timestamp]
+last_test: 0
+---
+```
+
+Followed by `## Tests` section with all derived tests, `## Summary` with initial counts, empty `## Gaps` section.
+
+Report: "Starting verification (M tests)"
+</step>
+
+<step name="present_test">
+**Display current test:**
+
+Find next test with `result: pending`.
+
+Present using branded checkpoint box:
+
+```
+════════════════════════════════════════
+VERIFICATION: Test {N} of {total}
+════════════════════════════════════════
+
+Source: {[plan] or [argument-map]}
+
+  {The criterion or claim being verified}
+
+Check: Does this section satisfy the above?
+════════════════════════════════════════
+```
+
+Use AskUserQuestion:
+- header: "Verification"
+- question: The criterion or claim text
+- options:
+  - "Pass - meets criteria"
+  - "Skip - not applicable"
+  - "Issue - describe the problem"
+</step>
+
+<step name="record_result">
+**Write result back to UAT.md:**
+
+Update the test entry:
+- Set `result:` to pass, skip, or issue
+- Set `reason:` to user's explanation (if provided)
+- Increment `last_test` in frontmatter
+
+**If result is "issue":**
+
+Ask follow-up for severity classification:
+
+Use AskUserQuestion:
+- header: "Severity"
+- question: "How severe is this issue?"
+- options:
+  - "Major - undermines argument, must fix"
+  - "Minor - weakens but doesn't invalidate"
+  - "Cosmetic - polish issue, fix during final pass"
+
+Add entry to `## Gaps` section:
+```markdown
+- claim: "[criterion or claim text]"
+  status: issue
+  reason: "[user's description]"
+  severity: [major|minor|cosmetic]
+```
+
+Update UAT.md on disk after each result.
+</step>
+
+<step name="check_completion">
+**Check if more tests remain:**
+
+Count tests with `result: pending`.
+
+**If pending > 0:** Loop back to `present_test` step.
+
+**If pending == 0:** All tests evaluated.
+- Set `status: complete` in frontmatter
+- Calculate summary counts:
+  - total: [count of all tests]
+  - passed: [count with result: pass]
+  - issues: [count with result: issue]
+  - skipped: [count with result: skip]
+- Update `## Summary` section in UAT.md
+</step>
+
+<step name="route_on_completion">
+**Route based on results:**
+
+**If no issues found (all pass or skip):**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ WTF-P ► VERIFICATION PASSED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Section [X]: [Name]
+Tests: [passed] passed, [skipped] skipped, 0 issues
+
+───────────────────────────────────────────
+
+## ▶ Next Up
+
+**Check progress** — see overall paper status
+
+`/wtfp:progress`
+
+<sub>`/clear` first → fresh context window</sub>
+
+───────────────────────────────────────────
+```
+
+**If issues found:**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ WTF-P ► VERIFICATION: ISSUES FOUND
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Section [X]: [Name]
+Tests: [passed] passed, [issues] issues, [skipped] skipped
+
+## Gap Summary
+
+| # | Claim/Criterion | Severity | Reason |
+|---|-----------------|----------|--------|
+| 1 | [text]          | major    | [reason] |
+| 2 | [text]          | minor    | [reason] |
+
+───────────────────────────────────────────
+
+## ▶ Next Up
+
+**Plan revision** — create fix plan for identified issues
+
+`/wtfp:plan-revision [section]`
+
+<sub>`/clear` first → fresh context window</sub>
+
+───────────────────────────────────────────
+```
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] Section resolved from arguments
+- [ ] SUMMARY.md existence validated (section was written)
+- [ ] Tests derived from BOTH PLAN.md success_criteria AND argument-map.md claims
+- [ ] UAT.md created or resumed with correct state
+- [ ] Each test presented one at a time with branded checkpoint box
+- [ ] User response recorded (pass/skip/issue) with persistence
+- [ ] Issues get severity classification and are added to Gaps
+- [ ] UAT.md updated on disk after each result (survives /clear)
+- [ ] Completion routes to progress (clean) or plan-revision (issues found)
+</success_criteria>