wtf-p 0.1.0

package/write-the-f-paper/templates/section.md

@@ -0,0 +1,128 @@
+# Section Entry Template
+
+Add this entry to `.planning/SECTIONS.md` when completing a section:
+
+```markdown
+## Section [X]: [Name] (Completed: YYYY-MM-DD)
+
+**Delivered:** [One sentence describing what argument this section makes]
+
+**Word count:** [Actual] / [Target] ([+/-] [delta])
+
+**Plans completed:** [N] plans
+
+**Key accomplishments:**
+- [Main argument established]
+- [Supporting point 1]
+- [Supporting point 2]
+- [Evidence/citations integrated]
+
+**Claims made:**
+1. [Claim 1] — supported by [evidence]
+2. [Claim 2] — supported by [evidence]
+3. [Claim 3] — supported by [evidence]
+
+**Citations added:** [N] citations
+- [Key citation 1]: [context]
+- [Key citation 2]: [context]
+
+**What's next:** [Brief description of next section goals, or "Document complete"]
+
+---
+```
+
+<structure>
+If SECTIONS.md doesn't exist, create it with header:
+
+```markdown
+# Completed Sections: [Paper/Grant Title]
+
+[Entries in chronological order - oldest first for narrative flow]
+```
+</structure>
+
+<guidelines>
+**When to create section entries:**
+- After completing each major section
+- Provides running record of progress
+- Enables context restoration for later sessions
+
+**Don't create entries for:**
+- Individual paragraph completions (too granular)
+- Work in progress (wait until section complete)
+- Minor edits within completed sections
+
+**Content to include:**
+- Section goal and what was delivered
+- Word count vs target (with delta)
+- Key claims made and their support
+- Major citations added
+- Setup for next section
+
+**After completion:**
+- Update STATE.md word count table
+- Update ROADMAP.md progress table
+- Create SUMMARY.md for the section
+</guidelines>
+
+<example>
+```markdown
+# Completed Sections: AI-Assisted Writing Framework
+
+## Section 1: Introduction (Completed: 2025-01-15)
+
+**Delivered:** Establishes research gap in AI-assisted writing tools and positions our framework contribution
+
+**Word count:** 847 / 800 (+47)
+
+**Plans completed:** 1 plan (01-01)
+
+**Key accomplishments:**
+- Opened with compelling hook about researcher frustration
+- Established context of AI writing tool proliferation
+- Identified gap: no systematic framework for academic use
+- Stated thesis: need for discipline-specific AI integration
+- Previewed paper structure
+
+**Claims made:**
+1. AI writing tools are proliferating but usage is ad hoc — supported by Smith (2023), Jones (2024)
+2. Academic writing has unique constraints not addressed by general tools — supported by Author (2022)
+3. A framework would improve adoption and outcomes — logical argument from gaps
+
+**Citations added:** 4 citations
+- Smith (2023): Context on AI tool proliferation
+- Jones (2024): Survey of current usage patterns
+- Author (2022): Academic writing constraints
+- Brown (2023): Gap identification support
+
+**What's next:** Section 2 (Literature Review) - Comprehensive review of AI writing tool research
+
+---
+
+## Section 2: Literature Review (Completed: 2025-01-18)
+
+**Delivered:** Synthesizes three threads of AI writing research and positions our contribution
+
+**Word count:** 1523 / 1500 (+23)
+
+**Plans completed:** 2 plans (02-01, 02-02)
+
+**Key accomplishments:**
+- Organized literature into three thematic threads
+- Critically analyzed each thread with synthesis
+- Explicitly addressed ethical concerns
+- Positioned our work against existing gaps
+
+**Claims made:**
+1. Tool efficacy research shows promise but lacks researcher focus — supported by systematic review
+2. Ethics debates center on authorship, not methodology — supported by Jones & Chen (2024)
+3. Pedagogical integration models don't translate to research contexts — supported by gap analysis
+
+**Citations added:** 15 citations
+[List key citations...]
+
+**What's next:** Section 3 (Methods) - Describe framework development process
+
+---
+```
+</example>

package/write-the-f-paper/templates/state.md

@@ -0,0 +1,244 @@
+# State Template
+
+Template for `.planning/STATE.md` — the writing project's living memory.
+
+---
+
+## File Template
+
+```markdown
+# Project State
+
+## Project Reference
+
+See: .planning/PROJECT.md (updated [date])
+
+**Core argument:** [One-liner from PROJECT.md Core Argument section]
+**Current focus:** [Current section name]
+
+## Current Position
+
+Section: [X] of [Y] ([Section name])
+Plan: [A] of [B] in current section
+Status: [Ready to plan / Planning / Ready to write / Writing / Section complete]
+Last activity: [YYYY-MM-DD] — [What happened]
+
+Progress: [░░░░░░░░░░] 0%
+
+## Word Count
+
+| Section | Target | Current | % |
+|---------|--------|---------|---|
+| Abstract | 250 | 0 | 0% |
+| Introduction | 800 | 0 | 0% |
+| Methods | 1200 | 0 | 0% |
+| Results | 1500 | 0 | 0% |
+| Discussion | 1200 | 0 | 0% |
+| **Total** | **5000** | **0** | **0%** |
+
+## Argument Strength
+
+**Core thesis:** [Strong / Developing / Weak]
+**Evidence gaps:** [List gaps or "None identified"]
+**Logic flow:** [Coherent / Has jumps / Needs restructuring]
+
+**By Section:**
+
+| Section | Strength | Notes |
+|---------|----------|-------|
+| Abstract | - | Not started |
+| Introduction | - | Not started |
+| Methods | - | Not started |
+| Results | - | Not started |
+| Discussion | - | Not started |
+
+## Verification Status
+
+- Citation check: [Not run / Passing / X issues]
+- Coherence check: [Not run / Passing / X issues]
+- Rubric check: [Not run / Passing / X issues]
+
+## Accumulated Context
+
+### Decisions
+
+Decisions are logged in PROJECT.md Key Decisions table.
+Recent decisions affecting current work:
+
+- [Section X]: [Decision summary]
+- [Section Y]: [Decision summary]
+
+### Deferred Issues
+
+[From ISSUES.md — list open items with section of origin]
+
+None yet.
+
+### Blockers/Concerns
+
+[Issues that affect future writing]
+
+None yet.
+
+## Session Continuity
+
+Last session: [YYYY-MM-DD HH:MM]
+Stopped at: [Description of last completed action]
+Resume file: [Path to .continue-here*.md if exists, otherwise "None"]
+```
+
+<purpose>
+
+STATE.md is the writing project's short-term memory spanning all sections and sessions.
+
+**Problem it solves:** Information is captured in summaries, issues, and decisions but not systematically consumed. Sessions start without context.
+
+**Solution:** A single, small file that's:
+- Read first in every workflow
+- Updated after every significant action
+- Contains digest of accumulated context
+- Enables instant session restoration
+- Tracks word count and argument strength
+
+</purpose>
+
+<lifecycle>
+
+**Creation:** After ROADMAP.md is created (during init)
+- Reference PROJECT.md (read it for current context)
+- Initialize word count table from roadmap word budgets
+- Set position to "Section 1 ready to plan"
+
+**Reading:** First step of every workflow
+- progress: Present status to user
+- plan: Inform planning decisions
+- write: Know current position
+- transition: Know what's complete
+
+**Writing:** After every significant action
+- write-section: After SUMMARY.md created
+  - Update position (section, plan, status)
+  - Update word count table
+  - Note new decisions (detail in PROJECT.md)
+  - Update deferred issues list
+  - Add blockers/concerns
+- transition: After section marked complete
+  - Update progress bar
+  - Clear resolved blockers
+  - Refresh Project Reference date
+
+</lifecycle>
+
+<sections>
+
+### Project Reference
+Points to PROJECT.md for full context. Includes:
+- Core argument (the ONE thesis that matters)
+- Current focus (which section)
+- Last update date (triggers re-read if stale)
+
+Claude reads PROJECT.md directly for requirements, constraints, and decisions.
+
+### Current Position
+Where we are right now:
+- Section X of Y — which section
+- Plan A of B — which plan within section
+- Status — current state
+- Last activity — what happened most recently
+- Progress bar — visual indicator of overall completion
+
+Progress calculation: (completed plans) / (total plans across all sections) × 100%
+
+### Word Count
+Track progress toward length targets:
+- Per-section breakdown
+- Target vs current
+- Percentage complete
+- Helps identify sections that need trimming or expansion
+
+### Argument Strength
+Track the quality of the argument:
+- Core thesis strength (is it well-supported?)
+- Evidence gaps (what's missing?)
+- Logic flow (does it hang together?)
+- Per-section assessment
+
+Updated after each section completion.
+
+### Verification Status
+Track the three-layer verification:
+- Citation check (mechanical)
+- Coherence check (logical)
+- Rubric check (requirements)
+
+Updated after running verification.
+
+### Accumulated Context
+
+**Decisions:** Reference to PROJECT.md Key Decisions table, plus recent decisions summary for quick access. Full decision log lives in PROJECT.md.
+
+**Deferred Issues:** Open items from ISSUES.md
+- Brief description with ISS-XXX number
+- Section where discovered
+- Effort estimate if known
+- Helps section planning identify what to address
+
+**Blockers/Concerns:** From "Next Section Readiness" sections
+- Issues that affect future work
+- Prefix with originating section
+- Cleared when addressed
+
+### Session Continuity
+Enables instant resumption:
+- When was last session
+- What was last completed
+- Is there a .continue-here file to resume from
+
+</sections>
+
+<size_constraint>
+
+Keep STATE.md under 100 lines.
+
+It's a DIGEST, not an archive. If accumulated context grows too large:
+- Keep only 3-5 recent decisions in summary (full log in PROJECT.md)
+- Reference ISSUES.md instead of listing all: "12 open issues — see ISSUES.md"
+- Keep only active blockers, remove resolved ones
+
+The goal is "read once, know where we are" — if it's too long, that fails.
+
+</size_constraint>
+
+<guidelines>
+
+**When created:**
+- During project initialization (after ROADMAP.md)
+- Reference PROJECT.md (extract core argument and current focus)
+- Initialize word count from roadmap word budgets
+- Initialize empty sections
+
+**When read:**
+- Every workflow starts by reading STATE.md
+- Then read PROJECT.md for full context
+- Provides instant context restoration
+
+**When updated:**
+- After each plan execution (update position, word count, note decisions, update issues/blockers)
+- After section transitions (update progress bar, clear resolved blockers, refresh project reference)
+
+**Size management:**
+- Keep under 100 lines total
+- Recent decisions only in STATE.md (full log in PROJECT.md)
+- Reference ISSUES.md instead of listing all issues
+- Keep only active blockers
+
+**Sections:**
+- Project Reference: Pointer to PROJECT.md with core argument
+- Current Position: Where we are now (section, plan, status)
+- Word Count: Progress toward length targets
+- Argument Strength: Quality assessment
+- Verification Status: Three-layer check results
+- Accumulated Context: Recent decisions, deferred issues, blockers
+- Session Continuity: Resume information
+
+</guidelines>

package/write-the-f-paper/templates/summary.md

@@ -0,0 +1,277 @@
+# Summary Template
+
+Template for `.planning/sections/XX-name/{section}-{plan}-SUMMARY.md` - section completion documentation.
+
+---
+
+## File Template
+
+```markdown
+---
+section: XX-name
+plan: YY
+document-type: [paper | grant | thesis]
+tags: [searchable: methods, results, discussion, claims, evidence]
+
+# Dependency graph
+requires:
+  - section: [prior section this depends on]
+    provides: [what that section established that this uses]
+provides:
+  - [bullet list of what this section contributes to the argument]
+affects: [list of section names that will need this context]
+
+# Writing tracking
+word-count:
+  target: [planned words]
+  actual: [words written]
+  delta: [+/- difference]
+
+key-claims:
+  - "Claim 1"
+  - "Claim 2"
+
+citations-added:
+  - "author2023: context"
+  - "author2022: context"
+
+issues-created: [ISS-XXX, ISS-YYY] # From ISSUES.md if any
+
+# Metrics
+duration: Xmin
+completed: YYYY-MM-DD
+---
+
+# Section [X]: [Name] Summary
+
+**[Substantive one-liner describing what this section argues - NOT "section complete" or "writing finished"]**
+
+## Performance
+
+- **Duration:** [time] (e.g., 23 min, 1h 15m)
+- **Started:** [ISO timestamp]
+- **Completed:** [ISO timestamp]
+- **Word count:** [actual] / [target] ([+/-] [delta])
+- **Tasks:** [count completed]
+
+## Accomplishments
+- [Most important argument established]
+- [Second key accomplishment]
+- [Third if applicable]
+
+## Key Claims Made
+
+The section establishes these claims:
+
+1. **[Claim 1]** — supported by [evidence/citation]
+2. **[Claim 2]** — supported by [evidence/citation]
+3. **[Claim 3]** — supported by [evidence/citation]
+
+## Citations Added
+
+| Citation | Where Used | Purpose |
+|----------|------------|---------|
+| Author (Year) | Para X | [Why cited] |
+| Author (Year) | Para Y | [Why cited] |
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: [task name]** - `abc123f` (draft/revise/cite/polish)
+2. **Task 2: [task name]** - `def456g` (draft/revise/cite/polish)
+3. **Task 3: [task name]** - `hij789k` (draft/revise/cite/polish)
+
+**Plan metadata:** `lmn012o` (docs: complete plan)
+
+## Files Created/Modified
+- `paper/section-name.md` - What was written
+- `references.bib` - Citations added
+
+## Decisions Made
+[Key decisions with brief rationale, or "None - followed plan as specified"]
+
+## Deviations from Plan
+
+[If no deviations: "None - plan executed exactly as written"]
+
+[If deviations occurred:]
+
+### Auto-fixed Issues
+
+**1. [Rule X - Category] Brief description**
+- **Found during:** Task [N] ([task name])
+- **Issue:** [What was wrong]
+- **Fix:** [What was done]
+- **Text modified:** [paragraph/section affected]
+- **Verification:** [How it was verified]
+- **Committed in:** [hash] (part of task commit)
+
+[... repeat for each auto-fix ...]
+
+### Deferred Enhancements
+
+Logged to .planning/ISSUES.md for future consideration:
+- ISS-XXX: [Brief description] (discovered in Task [N])
+- ISS-XXX: [Brief description] (discovered in Task [N])
+
+---
+
+**Total deviations:** [N] auto-fixed ([breakdown by rule]), [N] deferred
+**Impact on plan:** [Brief assessment - e.g., "All auto-fixes necessary for accuracy. No scope creep."]
+
+## Issues Encountered
+[Problems and how they were resolved, or "None"]
+
+[Note: "Deviations from Plan" documents unplanned work that was handled automatically via deviation rules. "Issues Encountered" documents problems during planned work that required problem-solving.]
+
+## Next Section Readiness
+[What's ready for next section]
+[Any blockers or concerns]
+
+---
+*Section: XX-name*
+*Completed: [date]*
+```
+
+<frontmatter_guidance>
+**Purpose:** Enable automatic context assembly via dependency graph. Frontmatter makes summary metadata machine-readable so plan-section can scan all summaries quickly and select relevant ones based on dependencies.
+
+**Fast scanning:** Frontmatter is first ~25 lines, cheap to scan across all summaries without reading full content.
+
+**Dependency graph:** `requires`/`provides`/`affects` create explicit links between sections, enabling transitive closure for context selection.
+
+**Word count tracking:** Tracks progress against word budget.
+
+**Key claims:** The arguments this section establishes (enables coherence checking).
+
+**Citations:** What sources were added (enables citation check).
+
+**Issues:** ISS-XXX numbers for deferred items.
+
+**Population:** Frontmatter is populated during summary creation in write-section.md. See `<step name="create_summary">` for field-by-field guidance.
+</frontmatter_guidance>
+
+<one_liner_rules>
+The one-liner MUST be substantive:
+
+**Good:**
+- "Establishes three-factor model for academic writing productivity"
+- "Methods section with participant demographics, protocol, and analysis approach"
+- "Discussion synthesizes findings with prior literature, addresses limitations"
+
+**Bad:**
+- "Section complete"
+- "Introduction written"
+- "Discussion finished"
+- "All tasks done"
+
+The one-liner should tell someone what argument the section makes.
+</one_liner_rules>
+
+<example>
+```markdown
+# Section 1: Introduction Summary
+
+**Establishes research gap in AI-assisted writing tools and positions our contribution as the first systematic framework**
+
+## Performance
+
+- **Duration:** 45 min
+- **Started:** 2025-01-15T14:22:10Z
+- **Completed:** 2025-01-15T15:07:33Z
+- **Word count:** 847 / 800 (+47)
+- **Tasks:** 4
+
+## Accomplishments
+- Established context of AI writing tools proliferation
+- Identified gap: no systematic framework for academic use
+- Stated thesis: need for discipline-specific AI integration
+- Previewed paper structure
+
+## Key Claims Made
+
+1. **AI writing tools are proliferating but usage is ad hoc** — supported by Smith (2023), Jones (2024)
+2. **Academic writing has unique constraints** — supported by Author (2022) + our argument
+3. **A framework would improve adoption and outcomes** — logical argument from gaps
+
+## Citations Added
+
+| Citation | Where Used | Purpose |
+|----------|------------|---------|
+| Smith (2023) | Para 1 | Context on AI tool proliferation |
+| Jones (2024) | Para 2 | Survey of current usage patterns |
+| Author (2022) | Para 3 | Academic writing constraints |
+| Brown (2023) | Para 4 | Gap identification support |
+
+## Files Created/Modified
+- `paper/01-introduction.md` - Full introduction draft
+- `references.bib` - 4 citations added
+
+## Decisions Made
+- Used narrative hook (researcher frustration story) rather than statistics opening
+- Positioned paper as "framework" not "tool" to emphasize conceptual contribution
+
+## Deviations from Plan
+
+None - plan executed exactly as written
+
+## Issues Encountered
+- Struggled with transition between gap and contribution; resolved by adding explicit "Therefore" connector
+
+## Next Section Readiness
+- Introduction sets up methods section clearly
+- Literature review context will be expanded in Related Work
+
+---
+*Section: 01-introduction*
+*Completed: 2025-01-15*
+```
+</example>
+
+<guidelines>
+**When to create:**
+- After completing each section plan
+- Required output from write-section workflow
+- Documents what actually happened vs what was planned
+
+**Frontmatter completion:**
+- MANDATORY: Complete all frontmatter fields during summary creation
+- See <frontmatter_guidance> for field purposes
+- Frontmatter enables automatic context assembly for future planning
+
+**One-liner requirements:**
+- Must be substantive (describe what argument was made, not "section complete")
+- Should tell someone what was accomplished
+- Examples: "Establishes three-factor model" not "Methods written"
+
+**Performance tracking:**
+- Include duration, start/end timestamps
+- Include word count vs target
+- Used for velocity metrics in STATE.md
+
+**Key claims tracking:**
+- List the main claims/arguments the section makes
+- Include evidence/citation for each
+- Enables coherence checking across sections
+
+**Citations tracking:**
+- List citations added with context
+- Enables citation check verification
+
+**Deviations section:**
+- Documents unplanned work handled via deviation rules
+- Separate from "Issues Encountered" (which is planned work problems)
+- Auto-fixed issues: What was wrong, how fixed, verification
+- Deferred enhancements: Logged to ISSUES.md with ISS-XXX numbers
+
+**Decisions section:**
+- Key decisions made during writing
+- Include rationale (why this choice)
+- Extracted to STATE.md accumulated context
+- Use "None - followed plan as specified" if no deviations
+
+**After creation:**
+- STATE.md updated with position, word count, decisions, issues
+- Next plan can reference decisions made
+</guidelines>