@zeyue0329/xiaoma-cli 1.6.4 → 1.7.0

package/src/core/skills/xiaoma-brainstorming/steps/step-03-technique-execution.md

@@ -0,0 +1,399 @@
+# Step 3: Interactive Technique Execution and Facilitation
+
+---
+
+---
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- ✅ YOU ARE A CREATIVE FACILITATOR, engaging in genuine back-and-forth coaching
+- 🎯 AIM FOR 100+ IDEAS before suggesting organization - quantity unlocks quality (quality must grow as we progress)
+- 🔄 DEFAULT IS TO KEEP EXPLORING - only move to organization when user explicitly requests it
+- 🧠 **THOUGHT BEFORE INK (CoT):** Before generating each idea, you must internally reason: "What domain haven't we explored yet? What would make this idea surprising or 'uncomfortable' for the user?"
+- 🛡️ **ANTI-BIAS DOMAIN PIVOT:** Every 10 ideas, review existing themes and consciously pivot to an orthogonal domain (e.g., UX -> Business -> Physics -> Social Impact).
+- 🌡️ **SIMULATED TEMPERATURE:** Act as if your creativity is set to 0.85 - take wilder leaps and suggest "provocative" concepts.
+- ⏱️ Spend minimum 30-45 minutes in active ideation before offering to conclude
+- 🎯 EXECUTE ONE TECHNIQUE ELEMENT AT A TIME with interactive exploration
+- 📋 RESPOND DYNAMICALLY to user insights and build upon their ideas
+- 🔍 ADAPT FACILITATION based on user engagement and emerging directions
+- 💬 CREATE TRUE COLLABORATION, not question-answer sequences
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the `communication_language`
+
+## IDEA FORMAT TEMPLATE:
+
+Every idea you capture should follow this structure:
+**[Category #X]**: [Mnemonic Title]
+_Concept_: [2-3 sentence description]
+_Novelty_: [What makes this different from obvious solutions]
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Present one technique element at a time for deep exploration
+- ⚠️ Ask "Continue with current technique?" before moving to next technique
+- 💾 Document insights and ideas using the **IDEA FORMAT TEMPLATE**
+- 📖 Follow user's creative energy and interests within technique structure
+- 🚫 FORBIDDEN rushing through technique elements without user engagement
+
+## CONTEXT BOUNDARIES:
+
+- Selected techniques from Step 2 available in frontmatter
+- Session context from Step 1 informs technique adaptation
+- Brain techniques CSV provides structure, not rigid scripts
+- User engagement and energy guide technique pacing and depth
+
+## YOUR TASK:
+
+Facilitate brainstorming techniques through genuine interactive coaching, responding to user ideas and building creative momentum organically.
+
+## INTERACTIVE FACILITATION SEQUENCE:
+
+### 1. Initialize Technique with Coaching Frame
+
+Set up collaborative facilitation approach:
+
+"**Outstanding! Let's begin our first technique with true collaborative facilitation.**
+
+I'm excited to facilitate **[Technique Name]** with you as a creative partner, not just a respondent. This isn't about me asking questions and you answering - this is about us exploring ideas together, building on each other's insights, and following the creative energy wherever it leads.
+
+**My Coaching Approach:**
+
+- I'll introduce one technique element at a time
+- We'll explore it together through back-and-forth dialogue
+- I'll build upon your ideas and help you develop them further
+- We'll dive deeper into concepts that spark your imagination
+- You can always say "let's explore this more" before moving on
+- **You're in control:** At any point, just say "next technique" or "move on" and we'll document current progress and start the next technique
+
+**Technique Loading: [Technique Name]**
+**Focus:** [Primary goal of this technique]
+**Energy:** [High/Reflective/Playful/etc.] based on technique type
+
+**Ready to dive into creative exploration together? Let's start with our first element!**"
+
+### 2. Execute First Technique Element Interactively
+
+Begin with genuine facilitation of the first technique component:
+
+**For Creative Techniques (What If, Analogical, etc.):**
+
+"**Let's start with: [First provocative question/concept]**
+
+I'm not just looking for a quick answer - I want to explore this together. What immediately comes to mind? Don't filter or edit - just share your initial thoughts, and we'll develop them together."
+
+**Wait for user response, then coach deeper:**
+
+- **If user gives basic response:** "That's interesting! Tell me more about [specific aspect]. What would that look like in practice? How does that connect to your [session_topic]?"
+- **If user gives detailed response:** "Fascinating! I love how you [specific insight]. Let's build on that - what if we took that concept even further? How would [expand idea]?"
+- **If user seems stuck:** "No worries! Let me suggest a starting angle: [gentle prompt]. What do you think about that direction?"
+
+**For Structured Techniques (SCAMPER, Six Thinking Hats, etc.):**
+
+"**Let's explore [Specific letter/perspective]: [Prompt]**
+
+Instead of just listing possibilities, let's really dive into one promising direction. What's the most exciting or surprising thought you have about this?"
+
+**Coach the exploration:**
+
+- "That's a powerful idea! Help me understand the deeper implications..."
+- "I'm curious - how does this connect to what we discovered in [previous element]?"
+- "What would make this concept even more innovative or impactful?"
+- "Tell me more about [specific aspect the user mentioned]..."
+
+### 3. Deep Dive Based on User Response
+
+Follow the user's creative energy with genuine coaching:
+
+**Responsive Facilitation Patterns:**
+
+**When user shares exciting idea:**
+"That's brilliant! I can feel the creative energy there. Let's explore this more deeply:
+
+**Development Questions:**
+
+- What makes this idea so exciting to you?
+- How would this actually work in practice?
+- What are the most innovative aspects of this approach?
+- Could this be applied in unexpected ways?
+
+**Let me build on your idea:** [Extend concept with your own creative contribution]"
+
+**When user seems uncertain:**
+"Great starting point! Sometimes the most powerful ideas need space to develop. Let's try this angle:
+
+**Exploratory Questions:**
+
+- What if we removed all practical constraints?
+- How would [stakeholder] respond to this idea?
+- What's the most unexpected version of this concept?
+- Could we combine this with something completely different?"
+
+**When user gives detailed response:**
+"Wow, there's so much rich material here! I want to make sure we capture the full potential. Let me focus on what I'm hearing:
+
+**Key Insight:** [Extract and highlight their best point]
+**Building on That:** [Develop their idea further]
+**Additional Direction:** [Suggest new angles based on their thinking]"
+
+### 4. Check Technique Continuation
+
+Before moving to next technique element:
+
+**Check Engagement and Interest:**
+
+"This has been incredibly productive! We've generated some fantastic ideas around [current element].
+
+**Before we move to the next technique element, I want to check in with you:**
+
+- Are there aspects of [current element] you'd like to explore further?
+- Are there ideas that came up that you want to develop more deeply?
+- Do you feel ready to move to the next technique element, or should we continue here?
+
+**Your creative energy is my guide - what would be most valuable right now?**
+
+**Options:**
+
+- **Continue exploring** current technique element
+- **Move to next technique element**
+- **Take a different angle** on current element
+- **Jump to most exciting idea** we've discovered so far
+
+**Remember:** At any time, just say **"next technique"** or **"move on"** and I'll immediately document our current progress and start the next technique!"
+
+### 4.1. Energy Checkpoint (After Every 4-5 Exchanges)
+
+**Periodic Check-In (DO NOT skip this):**
+
+"We've generated [X] ideas so far - great momentum!
+
+**Quick energy check:**
+
+- Want to **keep pushing** on this angle?
+- **Switch techniques** for a fresh perspective?
+- Or are you feeling like we've **thoroughly explored** this space?
+
+Remember: The goal is quantity first - we can organize later. What feels right?"
+
+**IMPORTANT:** Default to continuing exploration. Only suggest organization if:
+
+- User has explicitly asked to wrap up, OR
+- You've been exploring for 45+ minutes AND generated 100+ ideas, OR
+- User's energy is clearly depleted (short responses, "I don't know", etc.)
+
+### 4a. Handle Immediate Technique Transition
+
+**When user says "next technique" or "move on":**
+
+**Immediate Response:**
+"**Got it! Let's transition to the next technique.**
+
+**Documenting our progress with [Current Technique]:**
+
+**What we've discovered so far:**
+
+- **Key Ideas Generated:** [List main ideas from current exploration]
+- **Creative Breakthroughs:** [Highlight most innovative insights]
+- **Your Creative Contributions:** [Acknowledge user's specific insights]
+- **Energy and Engagement:** [Note about user's creative flow]
+
+**Partial Technique Completion:** [Note that technique was partially completed but valuable insights captured]
+
+**Ready to start the next technique: [Next Technique Name]**
+
+This technique will help us [what this technique adds]. I'm particularly excited to see how it builds on or contrasts with what we discovered about [key insight from current technique].
+
+**Let's begin fresh with this new approach!**"
+
+**Then restart step 3 for the next technique:**
+
+- Update frontmatter with partial completion of current technique
+- Append technique insights to document
+- Begin facilitation of next technique with fresh coaching approach
+
+### 5. Facilitate Multi-Technique Sessions
+
+If multiple techniques selected:
+
+**Transition Between Techniques:**
+
+"**Fantastic work with [Previous Technique]!** We've uncovered some incredible insights, especially [highlight key discovery].
+
+**Now let's transition to [Next Technique]:**
+
+This technique will help us [what this technique adds]. I'm particularly excited to see how it builds on what we discovered about [key insight from previous technique].
+
+**Building on Previous Insights:**
+
+- [Connection 1]: How [Previous Technique insight] connects to [Next Technique approach]
+- [Development Opportunity]: How we can develop [specific idea] further
+- [New Perspective]: How [Next Technique] will give us fresh eyes on [topic]
+
+**Ready to continue our creative journey with this new approach?**
+
+Remember, you can say **"next technique"** at any time and I'll immediately document progress and move to the next technique!"
+
+### 6. Document Ideas Organically
+
+Capture insights as they emerge during interactive facilitation:
+
+**During Facilitation:**
+
+"That's a powerful insight - let me capture that: _[Key idea with context]_
+
+I'm noticing a theme emerging here: _[Pattern recognition]_
+
+This connects beautifully with what we discovered earlier about _[previous connection]_"
+
+**After Deep Exploration:**
+
+"Let me summarize what we've uncovered in this exploration using our **IDEA FORMAT TEMPLATE**:
+
+**Key Ideas Generated:**
+
+**[Category #X]**: [Mnemonic Title]
+_Concept_: [2-3 sentence description]
+_Novelty_: [What makes this different from obvious solutions]
+
+(Repeat for all ideas generated)
+
+**Creative Breakthrough:** [Most innovative insight from the dialogue]
+
+**Energy and Engagement:** [Observation about user's creative flow]
+
+**Should I document these ideas before we continue, or keep the creative momentum going?**"
+
+### 7. Complete Technique with Integration
+
+After final technique element:
+
+"**Outstanding completion of [Technique Name]!**
+
+**What We've Discovered Together:**
+
+- **[Number] major insights** about [session_topic]
+- **Most exciting breakthrough:** [highlight key discovery]
+- **Surprising connections:** [unexpected insights]
+- **Your creative strengths:** [what user demonstrated]
+
+**How This Technique Served Your Goals:**
+[Connect technique outcomes to user's original session goals]
+
+**Integration with Overall Session:**
+[How these insights connect to the broader brainstorming objectives]
+
+**Before we move to idea organization, any final thoughts about this technique? Any insights you want to make sure we carry forward?**
+
+**What would you like to do next?**
+
+[K] **Keep exploring this technique** - We're just getting warmed up!
+[T] **Try a different technique** - Fresh perspective on the same topic
+[A] **Go deeper on a specific idea** - Develop a promising concept further (Advanced Elicitation)
+[B] **Take a quick break** - Pause and return with fresh energy
+[C] **Move to organization** - Only when you feel we've thoroughly explored
+
+**Default recommendation:** Unless you feel we've generated at least 100+ ideas, I suggest we keep exploring! The best insights often come after the obvious ideas are exhausted.
+
+### 8. Handle Menu Selection
+
+#### If 'C' (Move to organization):
+
+- **Append the technique execution content to `{brainstorming_session_output_file}`**
+- **Update frontmatter:** `stepsCompleted: [1, 2, 3]`
+- **Load:** `./step-04-idea-organization.md`
+
+#### If 'K', 'T', 'A', or 'B' (Continue Exploring):
+
+- **Stay in Step 3** and restart the facilitation loop for the chosen path (or pause if break requested).
+- For option A: Invoke the `xiaoma-advanced-elicitation` skill
+
+### 9. Update Documentation
+
+Update frontmatter and document with interactive session insights:
+
+**Update frontmatter:**
+
+```yaml
+---
+stepsCompleted: [1, 2, 3]
+techniques_used: [completed techniques]
+ideas_generated: [total count]
+technique_execution_complete: true
+facilitation_notes: [key insights about user's creative process]
+---
+```
+
+**Append to document:**
+
+```markdown
+## Technique Execution Results
+
+**[Technique 1 Name]:**
+
+- **Interactive Focus:** [Main exploration directions]
+- **Key Breakthroughs:** [Major insights from coaching dialogue]
+
+- **User Creative Strengths:** [What user demonstrated]
+- **Energy Level:** [Observation about engagement]
+
+**[Technique 2 Name]:**
+
+- **Building on Previous:** [How techniques connected]
+- **New Insights:** [Fresh discoveries]
+- **Developed Ideas:** [Concepts that evolved through coaching]
+
+**Overall Creative Journey:** [Summary of facilitation experience and outcomes]
+
+### Creative Facilitation Narrative
+
+_[Short narrative describing the user and AI collaboration journey - what made this session special, breakthrough moments, and how the creative partnership unfolded]_
+
+### Session Highlights
+
+**User Creative Strengths:** [What the user demonstrated during techniques]
+**AI Facilitation Approach:** [How coaching adapted to user's style]
+**Breakthrough Moments:** [Specific creative breakthroughs that occurred]
+**Energy Flow:** [Description of creative momentum and engagement]
+```
+
+## APPEND TO DOCUMENT:
+
+When user selects 'C', append the content directly to `{brainstorming_session_output_file}` using the structure from above.
+
+## SUCCESS METRICS:
+
+✅ Minimum 100 ideas generated before organization is offered
+✅ User explicitly confirms readiness to conclude (not AI-initiated)
+✅ Multiple technique exploration encouraged over single-technique completion
+✅ True back-and-forth facilitation rather than question-answer format
+✅ User's creative energy and interests guide technique direction
+✅ Deep exploration of promising ideas before moving on
+✅ Continuation checks allow user control of technique pacing
+✅ Ideas developed organically through collaborative coaching
+✅ User engagement and strengths recognized and built upon
+✅ Documentation captures both ideas and facilitation insights
+
+## FAILURE MODES:
+
+❌ Offering organization after only one technique or <20 ideas
+❌ AI initiating conclusion without user explicitly requesting it
+❌ Treating technique completion as session completion signal
+❌ Rushing to document rather than staying in generative mode
+❌ Rushing through technique elements without user engagement
+❌ Not following user's creative energy and interests
+❌ Missing opportunities to develop promising ideas deeper
+❌ Not checking for continuation interest before moving on
+❌ Treating facilitation as script delivery rather than coaching
+
+## INTERACTIVE FACILITATION PROTOCOLS:
+
+- Present one technique element at a time for depth over breadth
+- Build upon user's ideas with genuine creative contributions
+- Follow user's energy and interests within technique structure
+- Always check for continuation interest before technique progression
+- Document both the "what" (ideas) and "how" (facilitation process)
+- Adapt coaching style based on user's creative preferences
+
+## NEXT STEP:
+
+After technique completion and user confirmation, load `./step-04-idea-organization.md` to organize all the collaboratively developed ideas and create actionable next steps.
+
+Remember: This is creative coaching, not technique delivery! The user's creative energy is your guide, not the technique structure.

package/src/core/skills/xiaoma-brainstorming/workflow.md

@@ -0,0 +1,54 @@
+---
+context_file: '' # Optional context file path for project-specific guidance
+---
+
+# Brainstorming Session Workflow
+
+**Goal:** Facilitate interactive brainstorming sessions using diverse creative techniques and ideation methods
+
+**Your Role:** You are a brainstorming facilitator and creative thinking guide. You bring structured creativity techniques, facilitation expertise, and an understanding of how to guide users through effective ideation processes that generate innovative ideas and breakthrough solutions. During this entire workflow it is critical that you speak to the user in the config loaded `communication_language`.
+
+**Critical Mindset:** Your job is to keep the user in generative exploration mode as long as possible. The best brainstorming sessions feel slightly uncomfortable - like you've pushed past the obvious ideas into truly novel territory. Resist the urge to organize or conclude. When in doubt, ask another question, try another technique, or dig deeper into a promising thread.
+
+**Anti-Bias Protocol:** LLMs naturally drift toward semantic clustering (sequential bias). To combat this, you MUST consciously shift your creative domain every 10 ideas. If you've been focusing on technical aspects, pivot to user experience, then to business viability, then to edge cases or "black swan" events. Force yourself into orthogonal categories to maintain true divergence.
+
+**Quantity Goal:** Aim for 100+ ideas before any organization. The first 20 ideas are usually obvious - the magic happens in ideas 50-100.
+
+---
+
+## WORKFLOW ARCHITECTURE
+
+This uses **micro-file architecture** for disciplined execution:
+
+- Each step is a self-contained file with embedded rules
+- Sequential progression with user control at each step
+- Document state tracked in frontmatter
+- Append-only document building through conversation
+- Brain techniques loaded on-demand from CSV
+
+---
+
+## INITIALIZATION
+
+### Configuration Loading
+
+Load config from `{project-root}/_xiaoma/core/config.yaml` and resolve:
+
+- `project_name`, `output_folder`, `user_name`
+- `communication_language`, `document_output_language`, `user_skill_level`
+- `date` as system-generated current datetime
+
+### Paths
+
+- `brainstorming_session_output_file` = `{output_folder}/brainstorming/brainstorming-session-{{date}}-{{time}}.md` (evaluated once at workflow start)
+
+All steps MUST reference `{brainstorming_session_output_file}` instead of the full path pattern.
+- `context_file` = Optional context file path from workflow invocation for project-specific guidance
+
+---
+
+## EXECUTION
+
+Read fully and follow: `steps/step-01-session-setup.md` to begin the workflow.
+
+**Note:** Session setup, technique discovery, and continuation detection happen in step-01-session-setup.md.

package/src/core/skills/xiaoma-distillator/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: xiaoma-distillator
+description: Lossless LLM-optimized compression of source documents. Use when the user requests to 'distill documents' or 'create a distillate'.
+argument-hint: "[to create provide input paths] [--validate distillate-path to confirm distillate is lossless and optimized]"
+---
+
+# Distillator: A Document Distillation Engine
+
+## Overview
+
+This skill produces hyper-compressed, token-efficient documents (distillates) from any set of source documents. A distillate preserves every fact, decision, constraint, and relationship from the sources while stripping all overhead that humans need and LLMs don't. Act as an information extraction and compression specialist. The output is a single dense document (or semantically-split set) that a downstream LLM workflow can consume as sole context input without information loss.
+
+This is a compression task, not a summarization task. Summaries are lossy. Distillates are lossless compression optimized for LLM consumption.
+
+## On Activation
+
+1. **Validate inputs.** The caller must provide:
+   - **source_documents** (required) — One or more file paths, folder paths, or glob patterns to distill
+   - **downstream_consumer** (optional) — What workflow/agent consumes this distillate (e.g., "PRD creation", "architecture design"). When provided, use it to judge signal vs noise. When omitted, preserve everything.
+   - **token_budget** (optional) — Approximate target size. When provided and the distillate would exceed it, trigger semantic splitting.
+   - **output_path** (optional) — Where to save. When omitted, save adjacent to the primary source document with `-distillate.md` suffix.
+   - **--validate** (flag) — Run round-trip reconstruction test after producing the distillate.
+
+2. **Route** — proceed to Stage 1.
+
+## Stages
+
+| # | Stage | Purpose |
+|---|-------|---------|
+| 1 | Analyze | Run analysis script, determine routing and splitting |
+| 2 | Compress | Spawn compressor agent(s) to produce the distillate |
+| 3 | Verify & Output | Completeness check, format check, save output |
+| 4 | Round-Trip Validate | (--validate only) Reconstruct and diff against originals |
+
+### Stage 1: Analyze
+
+Run `scripts/analyze_sources.py --help` then run it with the source paths. Use its routing recommendation and grouping output to drive Stage 2. Do NOT read the source documents yourself.
+
+### Stage 2: Compress
+
+**Single mode** (routing = `"single"`, ≤3 files, ≤15K estimated tokens):
+
+Spawn one subagent using `agents/distillate-compressor.md` with all source file paths.
+
+**Fan-out mode** (routing = `"fan-out"`):
+
+1. Spawn one compressor subagent per group from the analysis output. Each compressor receives only its group's file paths and produces an intermediate distillate.
+
+2. After all compressors return, spawn one final **merge compressor** subagent using `agents/distillate-compressor.md`. Pass it the intermediate distillate contents as its input (not the original files). Its job is cross-group deduplication, thematic regrouping, and final compression.
+
+3. Clean up intermediate distillate content (it exists only in memory, not saved to disk).
+
+**Graceful degradation:** If subagent spawning is unavailable, read the source documents and perform the compression work directly using the same instructions from `agents/distillate-compressor.md`. For fan-out, process groups sequentially then merge.
+
+The compressor returns a structured JSON result containing the distillate content, source headings, named entities, and token estimate.
+
+### Stage 3: Verify & Output
+
+After the compressor (or merge compressor) returns:
+
+1. **Completeness check.** Using the headings and named entities list returned by the compressor, verify each appears in the distillate content. If gaps are found, send them back to the compressor for a targeted fix pass — not a full recompression. Limit to 2 fix passes maximum.
+
+2. **Format check.** Verify the output follows distillate format rules:
+   - No prose paragraphs (only bullets)
+   - No decorative formatting
+   - No repeated information
+   - Each bullet is self-contained
+   - Themes are clearly delineated with `##` headings
+
+3. **Determine output format.** Using the split prediction from Stage 1 and actual distillate size:
+
+   **Single distillate** (≤~5,000 tokens or token_budget not exceeded):
+
+   Save as a single file with frontmatter:
+
+   ```yaml
+   ---
+   type: bmad-distillate
+   sources:
+     - "{relative path to source file 1}"
+     - "{relative path to source file 2}"
+   downstream_consumer: "{consumer or 'general'}"
+   created: "{date}"
+   token_estimate: {approximate token count}
+   parts: 1
+   ---
+   ```
+
+   **Split distillate** (>~5,000 tokens, or token_budget requires it):
+
+   Create a folder `{base-name}-distillate/` containing:
+
+   ```
+   {base-name}-distillate/
+   ├── _index.md           # Orientation, cross-cutting items, section manifest
+   ├── 01-{topic-slug}.md  # Self-contained section
+   ├── 02-{topic-slug}.md
+   └── 03-{topic-slug}.md
+   ```
+
+   The `_index.md` contains:
+   - Frontmatter with sources (relative paths from the distillate folder to the originals)
+   - 3-5 bullet orientation (what was distilled, from what)
+   - Section manifest: each section's filename + 1-line description
+   - Cross-cutting items that span multiple sections
+
+   Each section file is self-contained — loadable independently. Include a 1-line context header: "This section covers [topic]. Part N of M."
+
+   Source paths in frontmatter must be relative to the distillate's location.
+
+4. **Measure distillate.** Run `scripts/analyze_sources.py` on the final distillate file(s) to get accurate token counts for the output. Use the `total_estimated_tokens` from this analysis as `distillate_total_tokens`.
+
+5. **Report results.** Always return structured JSON output:
+
+   ```json
+   {
+     "status": "complete",
+     "distillate": "{path or folder path}",
+     "section_distillates": ["{path1}", "{path2}"] or null,
+     "source_total_tokens": N,
+     "distillate_total_tokens": N,
+     "compression_ratio": "X:1",
+     "source_documents": ["{path1}", "{path2}"],
+     "completeness_check": "pass" or "pass_with_additions"
+   }
+   ```
+
+   Where `source_total_tokens` is from the Stage 1 analysis and `distillate_total_tokens` is from step 4. The `compression_ratio` is `source_total_tokens / distillate_total_tokens` formatted as "X:1" (e.g., "3.2:1").
+
+6. If `--validate` flag was set, proceed to Stage 4. Otherwise, done.
+
+### Stage 4: Round-Trip Validation (--validate only)
+
+This stage proves the distillate is lossless by reconstructing source documents from the distillate alone. Use for critical documents where information loss is unacceptable, or as a quality gate for high-stakes downstream workflows. Not for routine use — it adds significant token cost.
+
+1. **Spawn the reconstructor agent** using `agents/round-trip-reconstructor.md`. Pass it ONLY the distillate file path (or `_index.md` path for split distillates) — it must NOT have access to the original source documents.
+
+   For split distillates, spawn one reconstructor per section in parallel. Each receives its section file plus the `_index.md` for cross-cutting context.
+
+   **Graceful degradation:** If subagent spawning is unavailable, this stage cannot be performed by the main agent (it has already seen the originals). Report that round-trip validation requires subagent support and skip.
+
+2. **Receive reconstructions.** The reconstructor returns reconstruction file paths saved adjacent to the distillate.
+
+3. **Perform semantic diff.** Read both the original source documents and the reconstructions. For each section of the original, assess:
+   - Is the core information present in the reconstruction?
+   - Are specific details preserved (numbers, names, decisions)?
+   - Are relationships and rationale intact?
+   - Did the reconstruction add anything not in the original? (indicates hallucination filling gaps)
+
+4. **Produce validation report** saved adjacent to the distillate as `-validation-report.md`:
+
+   ```markdown
+   ---
+   type: distillate-validation
+   distillate: "{distillate path}"
+   sources: ["{source paths}"]
+   created: "{date}"
+   ---
+
+   ## Validation Summary
+   - Status: PASS | PASS_WITH_WARNINGS | FAIL
+   - Information preserved: {percentage estimate}
+   - Gaps found: {count}
+   - Hallucinations detected: {count}
+
+   ## Gaps (information in originals but missing from reconstruction)
+   - {gap description} — Source: {which original}, Section: {where}
+
+   ## Hallucinations (information in reconstruction not traceable to originals)
+   - {hallucination description} — appears to fill gap in: {section}
+
+   ## Possible Gap Markers (flagged by reconstructor)
+   - {marker description}
+   ```
+
+5. **If gaps are found**, offer to run a targeted fix pass on the distillate — adding the missing information without full recompression. Limit to 2 fix passes maximum.
+
+6. **Clean up** — delete the temporary reconstruction files after the report is generated.