wtf-p 0.1.0

package/write-the-f-paper/workflows/lit-review-phase.md

@@ -0,0 +1,281 @@
+<purpose>
+Execute literature discovery at the appropriate depth level.
+Produces DISCOVERY.md (for Level 2-3) that informs section planning.
+
+Called from plan-section.md's mandatory_literature_check step with a depth parameter.
+
+NOTE: For comprehensive literature research ("how do I position my work"), use
+/wtfp:research-gap instead, which produces RESEARCH.md.
+</purpose>
+
+<depth_levels>
+**This workflow supports three depth levels:**
+
+| Level | Name | Time | Output | When |
+| ----- | ---- | ---- | ------ | ---- |
+| 1 | Quick Verify | 2-5 min | No file, proceed with verified source | Confirming a specific citation |
+| 2 | Standard | 15-30 min | DISCOVERY.md | Need multiple sources, typical lit review |
+| 3 | Deep Dive | 1+ hour | Detailed DISCOVERY.md | Comprehensive background, theoretical framework |
+
+**Depth is determined by plan-section.md before routing here.**
+</depth_levels>
+
+<source_hierarchy>
+**MANDATORY: User's sources BEFORE external search**
+
+1. **User's existing materials** - literature.md, prior-drafts.md, PDFs they have
+2. **Database search** - Google Scholar, field-specific databases
+3. **WebSearch LAST** - For recent/emerging work only
+
+Prefer sources the user already has access to and has likely read.
+</source_hierarchy>
+
+<process>
+
+<step name="determine_depth">
+Check the depth parameter passed from plan-section.md:
+- `depth=verify` → Level 1 (Quick Verification)
+- `depth=standard` → Level 2 (Standard Discovery)
+- `depth=deep` → Level 3 (Deep Dive)
+
+Route to appropriate level workflow below.
+</step>
+
+<step name="level_1_quick_verify">
+**Level 1: Quick Verification (2-5 minutes)**
+
+For: Confirming a specific source, verifying a citation is correct.
+
+**Process:**
+
+1. Check user's existing sources:
+   ```bash
+   cat .planning/sources/literature.md 2>/dev/null | grep -i "[search term]"
+   ```
+
+2. If found, verify:
+   - Citation is complete and correct
+   - Source is relevant to the claim
+   - No conflicting information
+
+3. **If verified:** Return to plan-section.md with confirmation. No DISCOVERY.md needed.
+
+4. **If concerns found:** Escalate to Level 2.
+
+**Output:** Verbal confirmation to proceed, or escalation to Level 2.
+</step>
+
+<step name="level_2_standard">
+**Level 2: Standard Discovery (15-30 minutes)**
+
+For: Finding sources for a claim, standard literature grounding.
+
+**Process:**
+
+1. **Identify what to find:**
+   - What claim needs support?
+   - What type of source is appropriate?
+   - How many sources are needed?
+
+2. **Check existing sources first:**
+   ```bash
+   cat .planning/sources/literature.md 2>/dev/null
+   cat .planning/sources/prior-drafts.md 2>/dev/null
+   ```
+
+3. **Search for additional sources:**
+   - Academic databases for the topic
+   - Recent work (last 3-5 years preferred)
+   - Seminal papers if establishing foundation
+
+4. **For each source found:**
+   - Full citation
+   - Key finding relevant to your claim
+   - Where it should be cited
+
+5. **Create DISCOVERY.md:**
+   - Summary with sources identified
+   - Key findings per source
+   - Citation placement recommendations
+   - Confidence level (should be MEDIUM-HIGH for Level 2)
+
+6. Return to plan-section.md.
+
+**Output:** `.planning/sections/XX-name/DISCOVERY.md`
+</step>
+
+<step name="level_3_deep_dive">
+**Level 3: Deep Dive (1+ hour)**
+
+For: Comprehensive literature review, theoretical framework, establishing field context.
+
+**Process:**
+
+1. **Scope the discovery:**
+   - Define what the section needs to establish
+   - List specific questions to answer
+   - Identify key themes to cover
+
+2. **Exhaustive source search:**
+   - All relevant foundational work
+   - Comprehensive recent coverage
+   - Multiple perspectives/schools of thought
+   - Methodological precedents
+
+3. **For each source:**
+   - Full citation
+   - Key contributions
+   - Relationship to your work
+   - Where it fits in your argument
+
+4. **Synthesize themes:**
+   - Group sources by argument they support
+   - Identify consensus and controversy
+   - Document the gap your work addresses
+
+5. **Create comprehensive DISCOVERY.md:**
+   - Full structure with all sources
+   - Thematic organization
+   - Gap analysis
+   - Citation placement map
+   - Confidence by finding
+
+6. **Confidence gate:** If LOW confidence on any critical finding, present options.
+
+7. Return to plan-section.md.
+
+**Output:** `.planning/sections/XX-name/DISCOVERY.md` (comprehensive)
+</step>
+
+<step name="identify_gaps">
+**For Level 2-3:** Define what literature is needed.
+
+Ask: What does the reader need to know from prior work?
+
+- What foundational concepts need establishing?
+- What prior approaches exist?
+- What's the current state of knowledge?
+- Where are the gaps?
+</step>
+
+<step name="create_discovery_scope">
+Define discovery scope:
+
+- Clear objective (what claims need support)
+- Include/exclude boundaries (what's relevant)
+- Source preferences (recency, type, field)
+- Output structure for DISCOVERY.md
+</step>
+
+<step name="execute_discovery">
+Run the discovery:
+- Check user's existing sources first
+- Search academic databases
+- Prefer peer-reviewed sources
+- Structure findings for easy citation
+</step>
+
+<step name="create_discovery_output">
+Write `.planning/sections/XX-name/DISCOVERY.md`:
+
+```markdown
+# Literature Discovery: [Topic]
+
+## Summary
+**Objective:** [What we needed to find]
+**Sources found:** [N] relevant sources
+**Recommendation:** [Summary of what to cite where]
+
+## Sources by Theme
+
+### [Theme 1]
+| Source | Key Finding | Cite In |
+|--------|-------------|---------|
+| Smith (2023) | [finding] | Introduction |
+| Jones (2022) | [finding] | Discussion |
+
+### [Theme 2]
+[Continue...]
+
+## Gap Documentation
+Based on this literature:
+- [Gap 1]: [What hasn't been addressed]
+- [Gap 2]: [Limitation in current approaches]
+
+## Citation Map
+| Section | Sources to Cite |
+|---------|-----------------|
+| Introduction | Smith 2023, Jones 2022 |
+| Methods | Brown 2021 |
+| Discussion | All above + Lee 2024 |
+
+## Confidence
+**Level:** [HIGH/MEDIUM/LOW]
+**Reason:** [Brief explanation]
+
+## Open Questions
+- [Any remaining uncertainties]
+```
+</step>
+
+<step name="confidence_gate">
+After creating DISCOVERY.md, check confidence level.
+
+If confidence is LOW:
+Use AskUserQuestion:
+
+- header: "Low Confidence"
+- question: "Literature discovery confidence is LOW: [reason]. How to proceed?"
+- options:
+  - "Dig deeper" - Do more research
+  - "Proceed anyway" - Accept uncertainty
+  - "Pause" - I need to think about this
+
+If confidence is MEDIUM:
+Inline: "Discovery complete (medium confidence). [brief reason]. Proceed to planning?"
+
+If confidence is HIGH:
+Proceed directly, just note: "Discovery complete (high confidence)."
+</step>
+
+<step name="offer_next">
+```
+Discovery complete: .planning/sections/XX-name/DISCOVERY.md
+Sources found: [N]
+Confidence: [level]
+
+What's next?
+
+1. Discuss section context (/wtfp:discuss-section [section])
+2. Create section plan (/wtfp:plan-section [section])
+3. Refine discovery (dig deeper)
+4. Review discovery
+```
+
+NOTE: DISCOVERY.md is NOT committed separately. It will be committed with section completion.
+</step>
+
+</process>
+
+<success_criteria>
+**Level 1 (Quick Verify):**
+- Existing sources checked
+- Citation verified or concerns escalated
+- Verbal confirmation to proceed (no files)
+
+**Level 2 (Standard):**
+- Existing sources checked first
+- Additional sources found if needed
+- DISCOVERY.md created with sources
+- Confidence level MEDIUM or higher
+- Ready to inform PLAN.md creation
+
+**Level 3 (Deep Dive):**
+- Discovery scope defined
+- Exhaustive source search completed
+- DISCOVERY.md created with comprehensive analysis
+- Thematic organization provided
+- Gap analysis included
+- Confidence gate passed
+- Ready to inform PLAN.md creation
+</success_criteria>

package/write-the-f-paper/workflows/lit-review-phase.wcn.md

@@ -0,0 +1,92 @@
+<purpose>
+Execute literature discovery at the appropriate depth level.
+Produces DISCOVERY.md (for Level 2-3) that informs section planning.
+
+Called from plan-section.md's mandatory_literature_check step with a depth parameter.
+
+NOTE: For comprehensive literature research ("how do I position my work"), use
+/wtfp:research-gap instead, which produces RESEARCH.md.
+</purpose>
+
+<depth_levels>
+**This workflow supports three depth levels:**
+
+| Level | Name | Time | Output | When |
+| ----- | ---- | ---- | ------ | ---- |
+| 1 | Quick Verify | 2-5 min | No file, proceed with verified source | Confirming a specific citation |
+| 2 | Standard | 15-30 min | DISCOVERY.md | Need multiple sources, typical lit review |
+| 3 | Deep Dive | 1+ hour | Detailed DISCOVERY.md | Comprehensive background, theoretical framework |
+
+**Depth is determined by plan-section.md before routing here.**
+</depth_levels>
+
+<source_hierarchy>
+**MANDATORY: User's sources BEFORE external search**
+
+1. **User's existing materials** - literature.md, prior-drafts.md, PDFs they have
+2. **Database search** - Google Scholar, field-specific databases
+3. **WebSearch LAST** - For recent/emerging work only
+
+Prefer sources the user already has access to and has likely read.
+</source_hierarchy>
+
+<process>
+
+[step:determine_depth]
+[/step]
+
+[step:level_1_quick_verify]
+RUN: cat .planning/sources/literature.md 2>/dev/null | grep -i "[search term]"
+IF verified → Return to plan-section.md with confirmation. No...
+IF concerns_found → Escalate to Level 2.
+[/step]
+
+[step:level_2_standard]
+RUN: cat .planning/sources/literature.md 2>/dev/null
+[/step]
+
+[step:level_3_deep_dive]
+[/step]
+
+[step:identify_gaps]
+[/step]
+
+[step:create_discovery_scope]
+[/step]
+
+[step:execute_discovery]
+[/step]
+
+[step:create_discovery_output]
+[/step]
+
+[step:confidence_gate]
+[/step]
+
+[step:offer_next]
+[/step]
+
+</process>
+
+<success_criteria>
+**Level 1 (Quick Verify):**
+- Existing sources checked
+- Citation verified or concerns escalated
+- Verbal confirmation to proceed (no files)
+
+**Level 2 (Standard):**
+- Existing sources checked first
+- Additional sources found if needed
+- DISCOVERY.md created with sources
+- Confidence level MEDIUM or higher
+- Ready to inform PLAN.md creation
+
+**Level 3 (Deep Dive):**
+- Discovery scope defined
+- Exhaustive source search completed
+- DISCOVERY.md created with comprehensive analysis
+- Thematic organization provided
+- Gap analysis included
+- Confidence gate passed
+- Ready to inform PLAN.md creation
+</success_criteria>