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.

   bash

   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.

   bash

   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):

   bash

   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").

Phase Transition

Execute §CMD_GATE_PHASE.

2. Interrogation (Brief Clarification)

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

Interrogation Depth Selection

Before asking questions, present this choice via AskUserQuestion (multiSelect: false):

"How detailed should the clarification be?"

Record the user's choice.

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"

Interrogation Exit Gate

After reaching minimum rounds, present this choice via AskUserQuestion (multiSelect: true):

"Clarification complete (minimum met). What next?"

• •"Proceed to Phase 3: Writing" — (terminal: if selected, skip all others and move on)
• •"More clarification (1 more round)" — Additional questions, then this gate re-appears
• •"Devil's advocate round" — 1 round challenging the framing
• •"Deep dive round" — 1 round drilling into a specific aspect

3. Writing

Intent: Generate the writeup document.

1. •

   Compute Filename:

   code

   YYYY_MM_DD_<TOPIC_SLUG>.md
   

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

   Compute Full Path:

   code

   <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.
4. •

   Report: Output to chat the created file path as a clickable link per ¶INV_TERMINAL_FILE_LINKS.

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

Quick Reference