wtf-p 0.1.0

package/write-the-f-paper/templates/revision-issues.md

@@ -0,0 +1,169 @@
+# Revision Issues Template
+
+Template for `.planning/sections/XX-name/{section}-{plan}-ISSUES.md` - section-scoped issues discovered during verification.
+
+**Purpose:** Capture issues found during `/wtfp:review-section`. Unlike global ISSUES.md (for deferred enhancements), this file tracks problems in specific written sections.
+
+**Location:** Same directory as the SUMMARY.md being reviewed.
+
+---
+
+## File Template
+
+```markdown
+# Revision Issues: Section [X] Plan [Y]
+
+**Reviewed:** [date]
+**Source:** [path to SUMMARY.md that was reviewed]
+**Reviewer:** User via /wtfp:review-section
+
+## Open Issues
+
+### REV-001: [Brief description]
+
+**Discovered:** [date]
+**Section/Plan:** [XX]-[YY]
+**Severity:** [Critical/Major/Minor/Polish]
+**Verification Layer:** [Citation/Coherence/Rubric]
+**Description:** [Detailed description of the problem]
+**Location:** [Paragraph/sentence where issue appears]
+**Expected:** [What should be there]
+**Actual:** [What is currently there]
+**Suggested Fix:** [How to address this]
+
+### REV-002: [Brief description]
+
+...
+
+## Resolved Issues
+
+[Moved here after /wtfp:plan-revision executes and fixes are verified]
+
+### REV-001: [Brief description]
+**Resolved:** [date] - Fixed in [section]-[plan]-FIX.md
+**Commit:** [hash]
+
+---
+
+*Section: XX-name*
+*Plan: YY*
+*Reviewed: [date]*
+```
+
+---
+
+## Severity Guide
+
+| Severity | Definition | Example |
+|----------|------------|---------|
+| **Critical** | Factual error or logical contradiction | Claim contradicts data, wrong citation |
+| **Major** | Significant argument weakness | Missing evidence, unclear logic |
+| **Minor** | Issue affects clarity or flow | Awkward transition, unclear sentence |
+| **Polish** | Style or preference issue | Could be tighter, alternative wording |
+
+## Verification Layer
+
+| Layer | What It Checks | Example Issues |
+|-------|----------------|----------------|
+| **Citation** | All claims supported, citations correct | Unsupported claim, wrong page number |
+| **Coherence** | Argument flows logically | Claim doesn't follow from evidence |
+| **Rubric** | Meets requirements | Over word limit, missing required section |
+
+---
+
+## REV Numbering
+
+- **Prefix:** `REV-` (distinguishes from ISS- enhancement issues)
+- **Scope:** Per-file numbering (REV-001, REV-002, etc. within each file)
+- **No global numbering:** Each {section}-{plan}-ISSUES.md has its own sequence
+
+---
+
+<good_examples>
+```markdown
+# Revision Issues: Section 3 Plan 1
+
+**Reviewed:** 2025-01-15
+**Source:** .planning/sections/03-methods/03-01-SUMMARY.md
+**Reviewer:** User via /wtfp:review-section
+
+## Open Issues
+
+### REV-001: Sample size justification missing
+
+**Discovered:** 2025-01-15
+**Section/Plan:** 03-01
+**Severity:** Major
+**Verification Layer:** Coherence
+**Description:** The methods section states N=45 but provides no justification for this sample size. Reviewers typically expect power analysis or precedent citation.
+**Location:** Participants subsection, paragraph 2
+**Expected:** Justification for sample size (power analysis, precedent, or acknowledged limitation)
+**Actual:** Just states "Forty-five participants were recruited" with no justification
+**Suggested Fix:** Add either (a) power analysis showing N=45 sufficient for expected effect size, (b) citation to similar studies with comparable N, or (c) acknowledge as limitation
+
+### REV-002: Missing IRB number
+
+**Discovered:** 2025-01-15
+**Section/Plan:** 03-01
+**Severity:** Critical
+**Verification Layer:** Rubric
+**Description:** Journal requirements specify IRB approval number must appear in methods. Currently absent.
+**Location:** Ethical considerations paragraph
+**Expected:** "This study was approved by [Institution] IRB (#XXXX-XXXX)"
+**Actual:** States "This study was approved by the institutional review board" without number
+**Suggested Fix:** Add IRB number from user's records: #2024-0123
+
+### REV-003: Passive voice in procedure description
+
+**Discovered:** 2025-01-15
+**Section/Plan:** 03-01
+**Severity:** Polish
+**Verification Layer:** Rubric
+**Description:** Journal style guide prefers active voice. Several sentences use passive construction.
+**Location:** Procedure subsection, sentences 2-4
+**Expected:** Active voice: "Participants completed..."
+**Actual:** Passive voice: "The survey was completed by participants..."
+**Suggested Fix:** Convert to active voice throughout procedure
+
+## Resolved Issues
+
+[None yet]
+
+---
+
+*Section: 03-methods*
+*Plan: 01*
+*Reviewed: 2025-01-15*
+```
+</good_examples>
+
+<guidelines>
+**When to create:**
+- First time /wtfp:review-section finds an issue for a plan
+- One file per plan reviewed
+
+**Location:**
+- `.planning/sections/XX-name/{section}-{plan}-ISSUES.md`
+- Lives alongside SUMMARY.md being reviewed
+
+**Difference from global ISSUES.md:**
+- Global ISSUES.md: Deferred enhancements (nice-to-haves)
+- Revision ISSUES.md: Actual problems found during review
+
+**Workflow:**
+1. /wtfp:review-section creates this file with issues
+2. /wtfp:plan-revision reads this file and creates FIX.md plan
+3. After FIX.md executes, issues move to "Resolved" section
+4. File becomes historical record of what was found and fixed
+
+**Resolution:**
+- Don't delete resolved issues - move to "Resolved Issues" section
+- Include fix reference (commit hash, plan that fixed it)
+- File serves as audit trail
+
+**Severity assignment:**
+- Critical: Would cause rejection - must fix before submission
+- Major: Significant weakness - should fix before submission
+- Minor: Noticeable issue - fix if time permits
+- Polish: Optional improvement - defer to final pass
+</guidelines>

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

@@ -0,0 +1,187 @@
+# Roadmap Template
+
+Template for `.planning/ROADMAP.md`.
+
+## Initial Roadmap (Paper/Grant)
+
+```markdown
+# Roadmap: [Paper/Grant Title]
+
+## Overview
+
+[One paragraph describing the writing journey from outline to submission]
+
+## Document Structure
+
+**Type:** [IMRaD / Grant-NSF / Grant-NIH / Thesis Chapter / Custom]
+
+**Target Length:** [Total word count or page limit]
+
+## Domain Expertise
+
+[Paths to domain knowledge that inform writing. These documents serve as indexes — during section planning, read them to find relevant context.]
+
+- .planning/structure/argument-map.md
+- .planning/structure/outline.md
+- .planning/sources/literature.md
+
+Or: None — new project
+
+## Sections
+
+**Section Numbering:**
+- Integer sections (1, 2, 3): Planned document structure
+- Decimal sections (2.1, 2.2): Urgent insertions (marked with INSERTED)
+
+Decimal sections appear between their surrounding integers in numeric order.
+
+- [ ] **Section 1: [Name]** - [One-line description]
+- [ ] **Section 2: [Name]** - [One-line description]
+- [ ] **Section 3: [Name]** - [One-line description]
+- [ ] **Section 4: [Name]** - [One-line description]
+
+## Section Details
+
+### Section 1: [Name]
+**Goal**: [What this section accomplishes for the reader]
+**Depends on**: Nothing (first section) or Argument map
+**Research**: Unlikely (writing from notes) / Likely (need to read more literature)
+**Plans**: [Number of writing plans, e.g., "2 plans" or "TBD"]
+**Word budget**: [Target word count]
+
+Plans:
+- [ ] 01-01: [Brief description of first writing plan]
+- [ ] 01-02: [Brief description of second writing plan]
+
+### Section 2: [Name]
+**Goal**: [What this section accomplishes]
+**Depends on**: Section 1 (builds on introduction)
+**Research**: Likely (methods need detail)
+**Research topics**: [What needs investigating]
+**Plans**: [Number of plans]
+**Word budget**: [Target word count]
+
+Plans:
+- [ ] 02-01: [Brief description]
+- [ ] 02-02: [Brief description]
+
+### Section 2.1: Critical Addition (INSERTED)
+**Goal**: [Urgent writing inserted between sections]
+**Depends on**: Section 2
+**Plans**: 1 plan
+
+Plans:
+- [ ] 2.1-01: [Description]
+
+### Section 3: [Name]
+**Goal**: [What this section accomplishes]
+**Depends on**: Section 2
+**Research**: Unlikely (reporting results)
+**Plans**: [Number of plans]
+**Word budget**: [Target word count]
+
+Plans:
+- [ ] 03-01: [Brief description]
+- [ ] 03-02: [Brief description]
+
+### Section 4: [Name]
+**Goal**: [What this section accomplishes]
+**Depends on**: Sections 1-3 (synthesis)
+**Research**: Unlikely (interpretation)
+**Plans**: [Number of plans]
+**Word budget**: [Target word count]
+
+Plans:
+- [ ] 04-01: [Brief description]
+
+## Word Budget
+
+| Section | Target | Current | Status |
+|---------|--------|---------|--------|
+| Abstract | 250 | 0 | Not started |
+| Introduction | 800 | 0 | Not started |
+| Methods | 1200 | 0 | Not started |
+| Results | 1500 | 0 | Not started |
+| Discussion | 1200 | 0 | Not started |
+| **Total** | **5000** | **0** | **0%** |
+
+## Progress
+
+**Execution Order:**
+Sections execute in numeric order: 2 → 2.1 → 2.2 → 3 → 3.1 → 4
+
+| Section | Plans Complete | Status | Completed |
+|---------|----------------|--------|-----------|
+| 1. [Name] | 0/2 | Not started | - |
+| 2. [Name] | 0/2 | Not started | - |
+| 3. [Name] | 0/2 | Not started | - |
+| 4. [Name] | 0/1 | Not started | - |
+```
+
+<guidelines>
+**Initial planning:**
+- Section count depends on document structure (IMRaD: 5-6, Grant: varies by funder)
+- Each section delivers a coherent argument
+- Sections can have 1+ plans (split if complex or long)
+- Plans use naming: {section}-{plan}-PLAN.md (e.g., 01-02-PLAN.md)
+- Word budgets help pace writing
+- Progress table updated by write workflow
+
+**Research flags:**
+- `Research: Likely` - Need to read more literature, verify facts, find citations
+- `Research: Unlikely` - Writing from notes, existing data, established knowledge
+- Include `Research topics:` when Likely
+- Flags are hints, not mandates - validate at planning time
+
+**After milestones (submissions) complete:**
+- Collapse completed revision rounds in `<details>` tags
+- Add new revision sections for upcoming work
+- Keep continuous section numbering across revisions
+</guidelines>
+
+<status_values>
+- `Not started` - Haven't begun
+- `In progress` - Currently writing
+- `Draft` - First pass complete, needs revision
+- `Complete` - Done (add completion date)
+- `Deferred` - Pushed to later (with reason)
+</status_values>
+
+## Grant-Specific Roadmap
+
+For grant proposals, adapt the structure:
+
+```markdown
+# Roadmap: [Grant Title]
+
+## Overview
+
+[One paragraph describing the proposal journey from aims to submission]
+
+## Document Structure
+
+**Type:** Grant-NSF / Grant-NIH / [Other]
+**Deadline:** [Submission date]
+**Target Length:** [Page limit per section]
+
+## Sections
+
+- [ ] **Section 1: Specific Aims** - One-page summary of goals
+- [ ] **Section 2: Significance** - Why this matters
+- [ ] **Section 3: Innovation** - What's new
+- [ ] **Section 4: Approach** - How we'll do it
+- [ ] **Section 5: Timeline & Budget** - When and what resources
+
+## Section Details
+
+### Section 1: Specific Aims
+**Goal**: Capture reviewer attention, state hypothesis and aims
+**Depends on**: Approach must be planned first
+**Word budget**: 1 page (350-400 words)
+**Plans**: 1 plan
+
+Plans:
+- [ ] 01-01: Draft specific aims page
+
+[...]
+```

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

@@ -0,0 +1,178 @@
+# Section Archive Template
+
+Template for `.planning/archive/round-[N]/` - preserves state after completing a submission round.
+
+**Purpose:** Snapshot the project state before major transitions (submission, revision, resubmission) for context preservation and rollback capability.
+
+---
+
+## Directory Structure
+
+```
+.planning/
+├── archive/
+│   ├── round-1/                    # Initial submission
+│   │   ├── PROJECT.md             # Copy of project state
+│   │   ├── STATE.md               # Copy of state at submission
+│   │   ├── ROADMAP.md             # Copy of roadmap
+│   │   ├── sections/              # Copy of all section plans/summaries
+│   │   └── ARCHIVE-NOTES.md       # What was submitted, outcome
+│   │
+│   ├── round-2/                    # After R1 revision
+│   │   └── ...
+│   │
+│   └── round-3/                    # After R2 revision (if needed)
+│       └── ...
+```
+
+## Archive Notes Template
+
+```markdown
+# Archive: Round [N]
+
+**Archived:** [date]
+**Event:** [Initial submission / R1 revision / R2 revision / Accepted]
+**Venue:** [Journal/Conference name]
+
+## Submission Details
+
+**Submitted:** [date]
+**Manuscript ID:** [if assigned]
+**Word count:** [total words at submission]
+**Files submitted:**
+- manuscript.pdf
+- supplementary.pdf (if applicable)
+- cover_letter.pdf
+
+## State at Submission
+
+**Sections complete:**
+- [x] Abstract
+- [x] Introduction
+- [x] Methods
+- [x] Results
+- [x] Discussion
+- [x] References
+
+**Verification status:**
+- Citation check: Pass
+- Coherence check: Pass
+- Rubric check: Pass
+
+**Known limitations:**
+- [Issues we're aware of but submitted anyway]
+
+## Outcome
+
+**Decision:** [Pending / Accept / Minor revision / Major revision / Reject]
+**Decision date:** [date]
+**Reviews received:** [N] reviewers
+
+## Summary of Changes (from previous round)
+
+[If Round 2+:]
+- [Major change 1]
+- [Major change 2]
+- [Major change 3]
+
+## Next Steps
+
+[What happens after this round]
+
+---
+
+*Archived by /wtfp:submit-milestone*
+*Round: [N]*
+```
+
+<guidelines>
+**When to archive:**
+- Before submitting manuscript
+- Before starting major revision
+- After acceptance (final archive)
+
+**What to archive:**
+- PROJECT.md - Project vision at that point
+- STATE.md - Position and progress
+- ROADMAP.md - Section structure
+- All section PLAN.md and SUMMARY.md files
+- ARCHIVE-NOTES.md - Meta information
+
+**What NOT to archive:**
+- The actual manuscript files (those are in paper/)
+- Working files that will be recreated
+- Temporary analysis files
+
+**Archive naming:**
+- round-1: Initial submission
+- round-2: After first revision
+- round-3+: Subsequent revisions
+- Use descriptive names if needed: round-2-major-revision
+
+**Workflow:**
+1. /wtfp:submit-milestone creates archive
+2. Archive preserves state for reference
+3. New revision work starts fresh in .planning/
+4. Can reference archive for context during revision
+</guidelines>
+
+<example>
+```markdown
+# Archive: Round 1
+
+**Archived:** 2025-02-15
+**Event:** Initial submission
+**Venue:** CHI 2025
+
+## Submission Details
+
+**Submitted:** 2025-02-15
+**Manuscript ID:** chi25-papers-1234
+**Word count:** 9,847
+**Files submitted:**
+- manuscript.pdf (main paper)
+- supplementary.pdf (appendix with framework details)
+- cover_letter.pdf
+
+## State at Submission
+
+**Sections complete:**
+- [x] Abstract (247 words)
+- [x] Introduction (892 words)
+- [x] Literature Review (1,523 words)
+- [x] Methods (1,245 words)
+- [x] Results (2,156 words)
+- [x] Discussion (1,834 words)
+- [x] Conclusion (412 words)
+- [x] References (65 citations)
+
+**Verification status:**
+- Citation check: Pass (all 65 citations verified)
+- Coherence check: Pass (argument flows confirmed)
+- Rubric check: Pass (CHI format, word limit, sections)
+
+**Known limitations:**
+- Sample size (N=45) may draw questions - addressed in limitations
+- Framework not yet validated with large-scale study - noted as future work
+
+## Outcome
+
+**Decision:** Pending
+**Decision date:** Expected 2025-04-01
+**Reviews received:** -
+
+## Summary of Changes (from previous round)
+
+N/A - Initial submission
+
+## Next Steps
+
+- Wait for reviews (expected April)
+- If revision requested, use /wtfp:import-reviews to begin
+
+---
+
+*Archived by /wtfp:submit-milestone*
+*Round: 1*
+```
+</example>

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

@@ -0,0 +1,114 @@
+# Section Context Template
+
+Template for `.planning/SECTION-CONTEXT.md` - temporary handoff file from discuss-section to plan-section.
+
+**Purpose:** Persist section discussion context so `/clear` can be used between commands. This file is consumed by `/wtfp:plan-section` and deleted after the plan is created.
+
+---
+
+## File Template
+
+```markdown
+# Section Context
+
+**Generated:** [date]
+**Status:** Ready for /wtfp:plan-section
+
+<section_goal>
+## Section Goal
+
+[What this section should accomplish for the reader - identified during discussion]
+
+**Section:** [Section number and name]
+**Purpose:** [Why this section matters for the overall argument]
+**Word budget:** [Target word count]
+
+</section_goal>
+
+<key_arguments>
+## Key Arguments to Make
+
+[Arguments identified during discussion - the substance of this section]
+
+1. **[Argument 1]**: [How to support it]
+2. **[Argument 2]**: [How to support it]
+3. **[Argument 3]**: [How to support it]
+
+</key_arguments>
+
+<sources_to_use>
+## Sources to Use
+
+[Material available for this section]
+
+**Literature:**
+- [Citation 1]: [How to use it]
+- [Citation 2]: [How to use it]
+
+**Data:**
+- [Figure/table 1]: [Where to place]
+- [Figure/table 2]: [Where to place]
+
+**Prior drafts:**
+- [Material]: [What to incorporate]
+
+</sources_to_use>
+
+<structure_hints>
+## Structure Hints
+
+[Rough organization discussed with user]
+
+- Opening: [What to establish first]
+- Middle: [Main content flow]
+- Closing: [How to conclude/transition]
+
+</structure_hints>
+
+<constraints>
+## Constraints
+
+[Any constraints or boundaries mentioned during discussion]
+
+- [Constraint 1]
+- [Constraint 2]
+
+</constraints>
+
+<notes>
+## Additional Context
+
+[Anything else captured during discussion that informs the section]
+
+</notes>
+
+---
+
+*This file is temporary. It will be deleted after /wtfp:plan-section creates the plan.*
+```
+
+<guidelines>
+**This is a handoff artifact, not permanent documentation.**
+
+The file exists only to pass context from `discuss-section` to `plan-section` across a `/clear` boundary.
+
+**Lifecycle:**
+1. `/wtfp:discuss-section` creates this file at end of discussion
+2. User runs `/clear` (safe now - context is persisted)
+3. `/wtfp:plan-section` reads this file
+4. `/wtfp:plan-section` uses context to create detailed plan
+5. `/wtfp:plan-section` deletes this file after successful creation
+
+**Content should include:**
+- Section goal and purpose
+- Key arguments to make
+- Sources available (literature, data, prior drafts)
+- Rough structure hints
+- Constraints or boundaries
+- Notes from discussion
+
+**Content should NOT include:**
+- Detailed paragraph structure (that comes during planning)
+- Exact citations with page numbers (defer to writing)
+- Final word allocations (planning refines these)
+</guidelines>