writeup

name	writeup
description	Creates semi-permanent situational documents in project docs folders. Lightweight skill — no session, no logs, just focused writing. Triggers: "write up", "writeup".
version	3
tier	lightweight

Creates semi-permanent situational documents for reference. Writeups describe a current situation, explain context, and suggest improvements. Stored in apps/*/docs/writeups/ or packages/*/docs/writeups/.

Writeup Protocol (Lightweight Situational Documentation)

[!!!] LIGHTWEIGHT SKILL: No session directory, no log file, no tags. Just focused writing.

0. Setup & Discovery

Intent: Parse the topic and discover available destinations.

1. Parse Topic: Extract the writeup topic from the user's prompt.

   • If unclear, ask: "What topic should this writeup cover?"

2. Discover Destinations: Find all apps/ and packages/ directories that have a docs/ folder.

   ls -d apps/*/docs 2>/dev/null | sed 's|/docs||'
   ls -d packages/*/docs 2>/dev/null | sed 's|/docs||'
   

3. Ask Destination: Use AskUserQuestion to present discovered locations.

   • Options: Each discovered app/package as a choice.
   • The selected path becomes: <choice>/docs/writeups/

4. Ensure Directory: Create the writeups/ subdirectory if it doesn't exist.

   mkdir -p <destination>/docs/writeups
   

5. Ask Model: Execute §CMD_SUGGEST_EXTERNAL_MODEL with:

   modelQuestion: "Use an external model for writing instead of Claude?"

   Records externalModel (model name or "claude").

Phase 0 always proceeds to Phase 1 — no transition question needed.

---

1. RAG Keywords (Optional Context Discovery)

Intent: Offer the user keywords to search for related context.

1. Generate Keywords: Based on the topic, generate 4-6 relevant search keywords.

   • Example: Topic "extraction accuracy" → keywords: "extraction", "accuracy", "parsing", "LLM output", "validation"

2. Present Keywords: Use AskUserQuestion with multiSelect: true.

   • Header: "RAG Keywords"
   • Question: "Select keywords to search for related context (or skip):"
   • Options: Each keyword + a "Skip RAG" option.

3. Execute Searches: For each selected keyword (if any):

   engine session-search query "<keyword>" --limit 5
   engine doc-search query "<keyword>" --limit 5
   

   • Collect unique file paths and brief descriptions.
   • These populate the "Related" section of the writeup.

4. If Skipped: Proceed without the Related section (or mark it "None").

---

2. Interrogation (Brief Clarification)

Intent: Gather structured input for each section of the writeup.

¶ASK_WRITEUP_DEPTH

Extends: §ASK_INTERROGATION_DEPTH Trigger: when starting writeup clarification phase

Decision: Writeup Depth

• [LITE] Short (1 round) Simple writeup, you already have context
• [MEDM] Medium (2 rounds) Standard writeup, some unknowns
• [FULL] Long (3+ rounds) Complex topic, multiple perspectives

Interrogation Topics (Writeup)

Themes to explore during clarification.

Standard topics (typically covered once):

• Audience — Who will read this? Technical depth needed?
• Tone & style — Formal/informal, opinionated/neutral?
• Key takeaways — What should the reader walk away knowing?
• Structure preference — Problem/solution, comparison, narrative?
• Sources & citations — What evidence or references to include?
• Length constraints — Brief (1 page) or comprehensive?
• Visual aids — Diagrams, tables, code examples needed?
• Draft vs final — Is this a first draft or publication-ready?

Repeatable topics (can be selected any number of times):

• Followup — Clarify or revisit answers from previous rounds
• Devil's advocate — Challenge assumptions and decisions made so far
• What-if scenarios — Explore hypotheticals, edge cases, and alternative futures
• Deep dive — Drill into a specific topic from a previous round in much more detail

Round Execution

Use AskUserQuestion to clarify the writeup content.

Questions to ask (combine into one AskUserQuestion call with multiple questions):

1. Problem: "What's the core problem or situation to document?"

   • Options: Free-form (let user type via "Other")

2. Options: "What options or approaches exist?"

   • Options: Provide 2-3 common patterns if detectable, plus "Other"

3. Recommendation: "Do you have a preferred recommendation, or should I analyze and suggest?"

   • Options: "I have a recommendation" / "Analyze and suggest" / "No recommendation yet"

¶ASK_WRITEUP_EXIT

Extends: §ASK_INTERROGATION_EXIT Trigger: after minimum writeup clarification rounds are met

Decision: Writeup Exit

• [NEXT] Proceed to Writing Done clarifying — start writing
• [MORE] More clarification (1 more round) Additional questions, then this gate re-appears
• [DEEP] Deep dive round 1 round drilling into a specific aspect
• Devil's advocate round 1 round challenging the framing

---

3. Writing

Intent: Generate the writeup document.

1. Compute Filename:

   YYYY_MM_DD_<TOPIC_SLUG>.md
   

   • TOPIC_SLUG: Uppercase, underscores, derived from topic (e.g., "extraction gaps" → "EXTRACTION_GAPS")

2. Compute Full Path:

   <destination>/docs/writeups/YYYY_MM_DD_<TOPIC_SLUG>.md
   

3. Generate Content:

   If externalModel is not "claude" (external model path):

   1. Gather context file paths: Collect paths to all relevant files — RAG results, user-referenced files, interrogation context. Do NOT read them into context (save tokens).
   2. Compose prompt: Describe the writeup structure, interrogation answers, tone, and audience.
   3. Execute §CMD_EXECUTE_EXTERNAL_MODEL with:
      • prompt: The composed writeup instructions
      • template: TEMPLATE_WRITEUP.md path
      • vars: TOPIC, DATE, etc.
      • system: "You are a technical writer producing a situational document. Output ONLY the document content in Markdown. No preamble."
      • contextFiles: The gathered file paths
   4. Write the output to the computed path.

   If externalModel is "claude" (default path):

   1. Populate Template: Use §CMD_WRITE_FROM_TEMPLATE with TEMPLATE_WRITEUP.md.
      • Problem: From interrogation answer + agent analysis.
      • Context: Agent synthesizes from loaded context + RAG results.
      • Related: List of RAG-discovered files (if any). Format as bullet list with brief descriptions.
      • Options: From interrogation + agent analysis. Present 2-3 options with trade-offs.
      • Recommendation: From user preference or agent's analysis.
      • Next Steps: Concrete actionable items.
   2. Write File: Create the document at the computed path.

Constraint: No debrief, no log, no session summary. Just report the created file.

---

Quick Reference

Aspect	Value
Session	None
Log	None
Tags	None
Output	<app_or_pkg>/docs/writeups/YYYY_MM_DD_TOPIC.md
Template	assets/TEMPLATE_WRITEUP.md
Phases	4 (Setup → RAG → Interrogation → Writing)