wtf-p 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (10) hide show
  1. package/README.md +210 -229
  2. package/bin/install.js +557 -158
  3. package/bin/lib/utils.js +318 -0
  4. package/bin/uninstall.js +163 -201
  5. package/commands/wtfp/contribute.md +278 -0
  6. package/commands/wtfp/help.md +25 -0
  7. package/commands/wtfp/report-bug.md +131 -0
  8. package/commands/wtfp/request-feature.md +160 -0
  9. package/package.json +4 -2
  10. package/write-the-f-paper/references/github-contrib.md +216 -0
package/README.md CHANGED
@@ -1,338 +1,319 @@
1
1
  <div align="center">
2
2
 
3
- # WRITE THE F***ING PAPER
3
+ # WTF-P
4
4
 
5
- **The G.O.A.T. meta-prompting system for 10x researchers who need to submit papers/proposals YESTERDAY.**
5
+ **Context engineering for academic writing with Claude Code.**
6
6
 
7
7
  ```bash
8
- npx wtfp
8
+ npx wtf-p
9
9
  ```
10
10
 
11
- **Runs on everything. Mac, Windows, Linux. No excuses.**
12
- *(You need LaTeX and BibTeX or you're NGMI)*
11
+ *Write The Freaking Paper. Finally.*
13
12
 
14
- > "Bro, if you have the data, this ships the manuscript. Zero writer's block."
13
+ </div>
15
14
 
16
- > "I tried Overleaf and Notion — weak sauce. This tool actually ships words."
15
+ ---
17
16
 
18
- > "Literally the most based addition to my stack. It just writes the f*ing paper."
17
+ ## What This Does
19
18
 
20
- **Used by absolute legends at Gnosis Research Center at Illinois Tech.**
19
+ WTF-P turns Claude Code into a structured academic writing system. Instead of chatting with AI and hoping for the best, you get:
21
20
 
22
- [The Alpha](#the-alpha-why-i-built-this) · [The Stack](#the-stack) · [The Commands](#the-toolkit) · [The Logic](#the-logic)
21
+ - **Spec-driven writing** — Define your paper's vision, then execute section by section
22
+ - **Grounded output** — BibTeX integration, citation mapping, no hallucinated references
23
+ - **State management** — Pause, resume, track progress across sessions
24
+ - **Venue templates** — ACM, IEEE, Nature, arXiv-ML structures built in
23
25
 
24
- </div>
26
+ The philosophy: **context engineering beats prompt engineering**. The files you prepare matter more than what you type.
25
27
 
26
28
  ---
27
29
 
28
- ## The Alpha (Why I Built This)
29
-
30
- Yo, I'm leading the Gnosis Research Center at Illinois Tech. I got grants to win, labs to run, and exactly zero time to stare at a blinking cursor like an NPC. My PhD students? Same story.
30
+ ## Quick Start
31
31
 
32
- Other tools? Garbage. **Jasper?** Hallucinates. **ChatGPT?** Sounds like a robot trying to pass a Turing test. They don't get structure. They don't respect the citations.
32
+ ```bash
33
+ npx wtf-p
34
+ ```
33
35
 
34
- So I cooked up **WTF-P**. We're talking high-leverage context maxxing here. Under the hood? It's parsing BibTeX, mapping arguments, and enforcing that IMRaD structure so hard. You feed it data, it spits out submission-ready drafts.
36
+ Then in Claude Code:
35
37
 
36
- I trust the system. It builds the frame so I can just come in and drop the knowledge.
38
+ ```bash
39
+ /wtfp:new-paper # Define your paper
40
+ /wtfp:create-outline # Build the structure
41
+ /wtfp:plan-section 1 # Plan first section
42
+ /wtfp:write-section # Execute the plan
43
+ ```
37
44
 
38
- **No more "writer's block" excuses. We are shipping papers before the deadline. Period.**
45
+ Run `/wtfp:help` for the full command reference.
39
46
 
40
- — *akougkas (Nerd ^ academic+coder)*
47
+ <details>
48
+ <summary><strong>Installation Options</strong></summary>
41
49
 
42
- > Academic writing is usually chaotic evil. You ask AI for a lit review, it invents papers. Total beta move.
43
- > **WTF-P fixes that.** It's the grounding layer that makes Claude Code academic weapon grade. Describe the hypothesis, drop the .bib, and watch it cook.
50
+ ```bash
51
+ # Global install (recommended)
52
+ npx wtf-p --global
44
53
 
45
- ### Who This Is For
46
- PhDs, Postdocs, and PIs who are done playing games and need to submit the damn proposal/paper/report **right now**.
54
+ # Local to current project
55
+ npx wtf-p --local
47
56
 
48
- ---
57
+ # Custom Claude config directory
58
+ npx wtf-p --global --config-dir ~/research/.claude
49
59
 
50
- ## Let's Go
60
+ # Check installation status
61
+ npx wtf-p status
51
62
 
52
- ```bash
53
- npx wtfp
63
+ # Diagnose issues
64
+ npx wtf-p doctor
54
65
  ```
55
-
56
- Boom. Done. Check `/wtfp:help` if you're lost.
66
+ </details>
57
67
 
58
68
  <details>
59
- <summary><strong>Headless / CI / HPC (For the devops wizards)</strong></summary>
69
+ <summary><strong>Upgrading</strong></summary>
60
70
 
61
71
  ```bash
62
- npx wtfp --global # Install to ~/.claude/
63
- npx wtfp --local # Install to ./.claude/
72
+ # Update existing installation
73
+ npx wtf-p update
74
+
75
+ # Or reinstall with conflict handling
76
+ npx wtf-p --global # Interactive: prompts for conflicts
77
+ npx wtf-p --global --force # Overwrite everything
78
+ npx wtf-p --global --backup-all # Backup before overwriting
64
79
  ```
65
80
  </details>
66
81
 
67
82
  <details>
68
- <summary><strong>Custom Location (For the organized)</strong></summary>
83
+ <summary><strong>Uninstalling</strong></summary>
69
84
 
70
85
  ```bash
71
- # Install to a custom Claude config directory
72
- npx wtfp --global --config-dir ~/projects/my-paper/.claude
73
-
74
- # Or use environment variable
75
- CLAUDE_CONFIG_DIR=~/research/.claude npx wtfp --global
86
+ npx wtf-p-uninstall --global
87
+ npx wtf-p-uninstall --global --dry-run # Preview first
76
88
  ```
89
+
90
+ Only WTF-P files are removed. Your `CLAUDE.md` and other configs stay intact.
77
91
  </details>
78
92
 
79
- <details>
80
- <summary><strong>Upgrade / Reinstall (For the cautious)</strong></summary>
93
+ ---
81
94
 
82
- When upgrading, WTF-P respects your existing files:
95
+ ## Why AI Writing Tools Fail Researchers
83
96
 
84
- ```bash
85
- # Interactive: prompts for each conflict (overwrite/skip/backup)
86
- npx wtfp --global
97
+ Most researchers using AI for writing hit the same walls:
87
98
 
88
- # Force overwrite everything (yolo mode)
89
- npx wtfp --global --force
99
+ | Problem | What Happens |
100
+ |---------|--------------|
101
+ | **Dump and pray** | Paste a PDF, ask for a lit review, get hallucinated citations |
102
+ | **No verification layer** | AI sounds confident, but claims aren't grounded in your actual sources |
103
+ | **Monolithic approach** | Try to write 10k words at once, context window fills, quality degrades |
104
+ | **No structure** | Generic AI doesn't know IMRaD from a blog post |
90
105
 
91
- # Backup all existing files before overwriting
92
- npx wtfp --global --backup-all
93
- ```
94
- </details>
106
+ WTF-P solves these by treating academic writing as a **specification problem**, not a generation problem.
95
107
 
96
- <details>
97
- <summary><strong>Uninstall (For the tidy)</strong></summary>
108
+ ---
98
109
 
99
- ```bash
100
- # Interactive uninstall
101
- npx wtf-p-uninstall --global
110
+ ## The Approach: Context Engineering
102
111
 
103
- # Preview what would be removed
104
- npx wtf-p-uninstall --global --dry-run
112
+ The insight behind WTF-P: **what you prepare matters more than what you prompt**.
105
113
 
106
- # Backup before removing
107
- npx wtf-p-uninstall --global --backup
114
+ ### 1. Specification First
108
115
 
109
- # Also clean up backup files from prior installs
110
- npx wtf-p-uninstall --global --clean-backups
111
- ```
116
+ Before any writing, WTF-P interviews you to extract:
117
+ - Research questions and hypotheses
118
+ - Core argument structure
119
+ - Evidence and data inventory
120
+ - Target venue requirements
112
121
 
113
- Only WTF-P files are removed. Your `CLAUDE.md`, `settings.json`, and other configs stay intact.
114
- </details>
122
+ This becomes your `PROJECT.md` — the grounding document that keeps every section aligned.
115
123
 
116
- <details>
117
- <summary><strong>Dev Mode (For the builders)</strong></summary>
124
+ ### 2. Hierarchical Planning
118
125
 
119
- Clone it, build it, break it:
126
+ Papers aren't written in one shot. WTF-P breaks them down:
120
127
 
121
- ```bash
122
- git clone https://github.com/akougkas/wtfp.git
123
- cd wtfp
124
- node bin/install.js --local
125
128
  ```
126
- </details>
129
+ Paper Vision → Section Outline → Section Plan → Paragraph Execution
130
+ ```
127
131
 
128
- ### Pro Move: God Mode
129
- WTF-P is designed for flow state. Don't let permissions slow you down.
132
+ Each level has its own document. Each document is version-controlled. You always know where you are.
130
133
 
131
- ```bash
132
- claude --dangerously-skip-permissions
133
- ```
134
+ ### 3. Isolated Execution
135
+
136
+ When writing a section, WTF-P spawns a fresh context with only what's needed:
137
+ - The paper vision
138
+ - That section's plan
139
+ - Relevant citations from your BibTeX
140
+ - Prior sections for continuity
134
141
 
135
- > [!TIP]
136
- > This is the way. Stopping to approve `cat research_notes.txt` 50 times is strictly for amateurs.
142
+ No context pollution. No degradation over long documents.
143
+
144
+ ### 4. Human Verification
145
+
146
+ AI drafts. Humans verify. Every section goes through:
147
+ - Citation audit (are these real? are they relevant?)
148
+ - Argument check (does this follow from the evidence?)
149
+ - Rubric validation (does this meet venue requirements?)
150
+
151
+ The system flags issues. You fix them. Iterate until solid.
137
152
 
138
153
  ---
139
154
 
140
155
  ## The Workflow
141
156
 
142
- ### 1. The Setup
157
+ ### Starting Fresh
158
+
143
159
  ```bash
144
- /wtfp:new-paper
160
+ /wtfp:new-paper # Deep interview about your research
161
+ /wtfp:create-outline # Generate section structure + word budgets
145
162
  ```
146
- It grills you until it gets the alpha—your research questions, methods, findings. Creates `MANUSCRIPT.md`.
147
163
 
148
- ### 2. The Skeleton
164
+ Creates `.planning/` with your paper's specification:
165
+ - `PROJECT.md` — Vision, requirements, constraints
166
+ - `ROADMAP.md` — Section breakdown with status
167
+ - `STATE.md` — Writing progress and context
168
+
169
+ ### Writing Sections
170
+
149
171
  ```bash
150
- /wtfp:create-outline
172
+ /wtfp:plan-section 1 # Create detailed plan for section 1
173
+ /wtfp:write-section # Execute the plan
174
+ /wtfp:progress # Check status, get next action
151
175
  ```
152
- Generates:
153
- - `OUTLINE.md` — The IMRaD backbone.
154
- - `ARGUMENT.md` — The logic flow.
155
- - `REFS.md` — Citations mapped to sections. **No hallucinations allowed.**
156
176
 
157
- ### 3. The Grind
177
+ Each section gets its own planning documents. Plans are explicit — you see exactly what Claude intends before it writes.
178
+
179
+ ### Review and Polish
180
+
158
181
  ```bash
159
- /wtfp:plan-section 1 # Atomic planning
160
- /wtfp:write-section # Agent swarm execution
182
+ /wtfp:review-section 1 # Three-layer verification
183
+ /wtfp:polish-prose # Remove AI-speak, improve flow
184
+ /wtfp:check-refs # BibTeX audit
161
185
  ```
162
- Each section runs in a fresh subagent context. 200k tokens of pure synthesis. No degradation. It reads only what it needs. Surgical precision.
163
186
 
164
- ### 4. The Finish
187
+ ### Export
188
+
165
189
  ```bash
166
- /wtfp:polish-prose # De-robotize the text
167
- /wtfp:check-refs # BibTeX audit
168
- /wtfp:export-latex # LaTeX injection
190
+ /wtfp:export-latex # Generate .tex with proper formatting
169
191
  ```
170
- Ship the draft to your advisor. Get roasted. Iterate. The system is modular—you never get stuck in a monolithic doc.
171
192
 
172
193
  ---
173
194
 
174
- ## Resurrecting Dead Papers
195
+ ## Reviving Stalled Projects
175
196
 
176
- Got a paper rotting in a drawer? We're bringing it back to life.
197
+ Got a half-finished paper? WTF-P can work with existing material.
177
198
 
178
- ### 1. Context Maxxing
179
199
  ```bash
180
- /wtfp:map-project
200
+ /wtfp:map-project # Index your existing files
201
+ /wtfp:new-paper # Initialize with awareness of prior work
181
202
  ```
182
- Spawns agents to raid your directory. Creates `.planning/context/`:
183
203
 
184
- | Document | The Vibe |
185
- | :--- | :--- |
186
- | `LIT_REVIEW.md` | Your .bib analysis. |
187
- | `CURRENT_DRAFT.md` | The half-baked stuff you wrote 6 months ago. |
188
- | `DATA_SUMMARY.md` | Your results/figures decoded. |
189
- | `STYLE_GUIDE.md` | Nature/IEEE specs. |
190
- | `GAPS.md` | Where you messed up. |
204
+ The mapping phase analyzes:
205
+ - Existing drafts and their state
206
+ - Your BibTeX and how citations are used
207
+ - Data files and figures
208
+ - What's missing vs. what's done
191
209
 
192
- ### 2. Re-Init
193
- ```bash
194
- /wtfp:new-paper
195
- ```
196
- Same as fresh, but now it knows your history.
210
+ ---
197
211
 
198
- ### 3. Grind
199
- `/wtfp:create-outline` → `/wtfp:plan-section` → `/wtfp:write-section`
212
+ ## Command Reference
213
+
214
+ ### Setup
215
+ | Command | Purpose |
216
+ |---------|---------|
217
+ | `/wtfp:new-paper` | Initialize paper with deep context gathering |
218
+ | `/wtfp:create-outline` | Generate section structure |
219
+ | `/wtfp:map-project` | Index existing project materials |
220
+ | `/wtfp:analyze-bib` | Deep analysis of your bibliography |
221
+
222
+ ### Planning
223
+ | Command | Purpose |
224
+ |---------|---------|
225
+ | `/wtfp:discuss-section [N]` | Articulate vision before planning |
226
+ | `/wtfp:plan-section [N]` | Create execution plan |
227
+ | `/wtfp:list-assumptions [N]` | See what Claude plans to write |
228
+ | `/wtfp:research-gap [N]` | Literature analysis for a section |
229
+
230
+ ### Writing
231
+ | Command | Purpose |
232
+ |---------|---------|
233
+ | `/wtfp:write-section` | Execute a plan |
234
+ | `/wtfp:progress` | Status + intelligent next action |
235
+ | `/wtfp:pause-writing` | Save state for later |
236
+ | `/wtfp:resume-writing` | Restore context and continue |
237
+
238
+ ### Review
239
+ | Command | Purpose |
240
+ |---------|---------|
241
+ | `/wtfp:review-section [N]` | Three-layer verification |
242
+ | `/wtfp:plan-revision [N]` | Create fix plan from issues |
243
+ | `/wtfp:polish-prose` | Improve readability |
244
+ | `/wtfp:check-refs` | Citation audit |
245
+
246
+ ### Export
247
+ | Command | Purpose |
248
+ |---------|---------|
249
+ | `/wtfp:export-latex` | Generate .tex output |
250
+ | `/wtfp:submit-milestone` | Archive submission version |
251
+
252
+ ### Contributing
253
+ | Command | Purpose |
254
+ |---------|---------|
255
+ | `/wtfp:report-bug` | File a GitHub issue |
256
+ | `/wtfp:request-feature` | Request new functionality |
257
+ | `/wtfp:contribute` | Submit a pull request |
200
258
 
201
259
  ---
202
260
 
203
- ## Why It Crushes
204
-
205
- ### Context Maxxing
206
- Claude Code is cracked if you give it the right juice. Most profs just dump a PDF and pray.
207
- WTF-P handles the prompt engineering:
208
-
209
- | File | Function |
210
- | :--- | :--- |
211
- | `MANUSCRIPT.md` | The Vision. Always active. |
212
- | `OUTLINE.md` | The Backbone. |
213
- | `FLOW.md` | The Rhetoric. |
214
- | `DRAFT_PLAN.md` | The Battle Plan. |
215
- | `CRITIQUE.md` | Reviewer #2 Simulator. |
216
-
217
- ### XML Prompts (The Secret Sauce)
218
- We use structured XML so Claude doesn't go off the rails:
219
-
220
- ```xml
221
- <section type="synthesis">
222
- <title>3.2 Neural Architecture Search</title>
223
- <inputs>
224
- <file>data/results_table_3.csv</file>
225
- </inputs>
226
- <citations>
227
- <cite>vaswani2017attention</cite>
228
- </citations>
229
- <instruction>
230
- Describe the modified ResNet block.
231
- Tone: Objective, technical, gigabrain.
232
- </instruction>
233
- </section>
234
- ```
235
- Precise. No hallucinations. Pure signal.
261
+ ## Venue Templates
262
+
263
+ | Template | Structure |
264
+ |----------|-----------|
265
+ | `acm-cs` | Intro → Background → Approach → Evaluation → Related Work → Conclusion |
266
+ | `ieee-cs` | Intro → Background → Design → Implementation → Evaluation → Conclusion |
267
+ | `arxiv-ml` | Intro → Related Work → Preliminaries → Method → Experiments → Conclusion |
268
+ | `nature` | Intro → Methods → Results → Discussion |
269
+ | `thesis` | Flexible chapter structure |
236
270
 
237
- ### Subagent Swarm
238
- Writing 10k words? Context windows get full. The AI gets dumb.
239
- WTF-P prevents this. Every section = Fresh Agent.
271
+ ---
240
272
 
241
- | Section | Context | Quality |
242
- | :--- | :--- | :--- |
243
- | Intro | Fresh | 🔥 |
244
- | Methods | Fresh | 🔥 |
245
- | Discussion | Fresh | 🔥 |
273
+ ## WCN Mode (Reduced Tokens)
246
274
 
247
- No degradation. Walk away, come back to a finished Methods section.
275
+ For smaller models or limited context windows, WTF-P includes compressed workflows:
248
276
 
249
- ### Atomic Commits
250
- Every draft gets a git commit instantly:
251
- ```text
252
- abc123f text(intro): complete problem statement
253
- def456g text(methods): draft experimental setup
277
+ ```bash
278
+ ./tools/wcn/swap-workflows.sh wcn # Switch to compressed
279
+ ./tools/wcn/swap-workflows.sh verbose # Switch back
254
280
  ```
255
281
 
256
- > [!NOTE]
257
- > **Benefits:** Version control for your thesis. If a draft is mid, `git revert`.
282
+ 35-50% token reduction with equivalent output quality. Verified on Claude Haiku and Sonnet.
258
283
 
259
- ### WCN Mode (Lite Context)
260
- Running on smaller models? Limited context window? Free-tier Claude?
284
+ ---
261
285
 
262
- WCN (Workflow Compression Notation) cuts workflow tokens by **35-50%** with zero quality loss. Verified on Haiku and Sonnet.
286
+ ## Origin
263
287
 
264
- ```bash
265
- # Switch to compressed workflows
266
- ./tools/wcn/swap-workflows.sh wcn
288
+ WTF-P was built at the [Gnosis Research Center](https://www.intelli-gnosis.com/) at Illinois Tech.
267
289
 
268
- # Switch back to verbose
269
- ./tools/wcn/swap-workflows.sh verbose
270
- ```
290
+ The problem: research teams with grants to win, papers to publish, and no time to waste on writer's block. Existing AI tools either hallucinated citations or produced generic output that required complete rewrites.
271
291
 
272
- | Mode | create-outline | plan-section | Best For |
273
- | :--- | :--- | :--- | :--- |
274
- | Verbose | 13,029 chars | 13,655 chars | Opus, unlimited plans |
275
- | WCN | 6,676 chars | 8,863 chars | Haiku, Sonnet, free tiers |
292
+ The solution: treat Claude Code as a **structured writing system**, not a chatbot. Give it proper context, explicit specifications, and verification layers. Let humans focus on ideas while AI handles the mechanical synthesis.
276
293
 
277
- > [!TIP]
278
- > WCN uses structured notation (`[step:]`, `IF→`, `RUN:`) that smaller models parse just as well. You lose nothing but tokens.
294
+ The result: papers that ship.
279
295
 
280
296
  ---
281
297
 
282
- ## The Toolkit
283
-
284
- ### Setup & Planning
285
- | Command | Payload |
286
- | :--- | :--- |
287
- | `/wtfp:new-paper` | Start the grind. Picks venue template (ACM/IEEE/ML/Nature). |
288
- | `/wtfp:create-outline` | Build the skeleton from venue structure. |
289
- | `/wtfp:map-project` | Analyze the ruins of old drafts. |
290
- | `/wtfp:analyze-bib` | BibTeX intelligence. Cluster topics, find seminal works, map citations to sections. |
291
- | `/wtfp:discuss-section [N]` | Gather section context before planning. |
292
-
293
- ### Writing & Execution
294
- | Command | Payload |
295
- | :--- | :--- |
296
- | `/wtfp:plan-section [N]` | Tactical planning. |
297
- | `/wtfp:write-section` | Execute the draft. |
298
- | `/wtfp:progress` | Stats check. |
299
- | `/wtfp:insert-section [N]` | Add missing sauce. |
300
- | `/wtfp:remove-section [N]` | Kill your darlings. |
301
- | `/wtfp:research-gap` | Find the holes in literature. |
302
- | `/wtfp:list-assumptions` | Logic check. |
303
-
304
- ### Review & Polish
305
- | Command | Payload |
306
- | :--- | :--- |
307
- | `/wtfp:review-section [N]` | Reviewer personas: Hostile, Area Chair, Editor, Mentor. |
308
- | `/wtfp:plan-revision [N]` | Fix the damage. |
309
- | `/wtfp:polish-prose` | De-robotize the text. Kill AI-speak. |
310
- | `/wtfp:check-refs` | BibTeX audit. Find missing/unused citations. |
311
-
312
- ### Export & State
313
- | Command | Payload |
314
- | :--- | :--- |
315
- | `/wtfp:export-latex` | Generate .tex (The final boss). |
316
- | `/wtfp:submit-milestone` | Version lock. |
317
- | `/wtfp:pause-writing` | Save state. |
318
- | `/wtfp:resume-writing` | Load state. |
319
- | `/wtfp:help` | RTFM. |
320
-
321
- ### Venue Templates
322
- | Template | Structure |
323
- | :--- | :--- |
324
- | `acm-cs` | Intro → Background → Approach → Eval → Related → Conclusion |
325
- | `ieee-cs` | Intro → Background/Related → Design → Impl → Eval → Conclusion |
326
- | `arxiv-ml` | Intro → Related → Prelim → Method → Experiments → Conclusion |
327
- | `nature` | Intro → Methods → Results → Discussion (classic IMRaD) |
328
- | `thesis` | Flexible chapter structure for dissertations |
298
+ ## Contributing
299
+
300
+ Found a bug? Want a feature? WTF-P includes commands to help:
301
+
302
+ ```bash
303
+ /wtfp:report-bug # Creates a GitHub issue
304
+ /wtfp:request-feature # Submits a feature request
305
+ /wtfp:contribute # Guides you through a PR
306
+ ```
307
+
308
+ Or visit [github.com/akougkas/wtf-p](https://github.com/akougkas/wtf-p).
329
309
 
330
310
  ---
331
311
 
332
312
  ## License
313
+
333
314
  MIT License. Open source, open science.
334
315
 
335
316
  <div align="center">
336
- <br>
337
- <strong>Claude Code is powerful. WTF-P makes it tenured.</strong>
317
+ <br>
318
+ <strong>Stop staring at the cursor. Start shipping papers.</strong>
338
319
  </div>