@zeyue0329/xiaoma-cli 1.6.5 → 1.8.0

package/src/core/{workflows/advanced-elicitation → skills/xiaoma-advanced-elicitation}/workflow.md

@@ -1,13 +1,10 @@
 ---
-name: advanced-elicitation
-description: 'Push the LLM to reconsider refine and improve its recent output. Use when the user asks for advanced elicitation.'
-methods: '{project-root}/_xiaoma/core/workflows/advanced-elicitation/methods.csv'
 agent_party: '{project-root}/_xiaoma/_config/agent-manifest.csv'
 ---
 
 # Advanced Elicitation Workflow
 
-**Goal:** Push the LLM to reconsider, refine, and improve its recent output. Use when the user asks for advanced elicitation.
+**Goal:** Push the LLM to reconsider, refine, and improve its recent output.
 
 ---
 
@@ -22,9 +19,9 @@ agent_party: '{project-root}/_xiaoma/_config/agent-manifest.csv'
 
 ---
 
-## INTEGRATION (When Called from Workflow)
+## INTEGRATION (When Invoked Indirectly)
 
-When called during template workflow processing:
+When invoked from another prompt or process:
 
 1. Receive or review the current section content that was just generated
 2. Apply elicitation methods iteratively to enhance that specific content
@@ -37,7 +34,7 @@ When called during template workflow processing:
 
 ### Step 1: Method Registry Loading
 
-**Action:** Load and read `{methods}` and `{agent_party}`
+**Action:** Load and read `./methods.csv` and `{agent_party}`
 
 #### CSV Structure
 
@@ -99,9 +96,9 @@ x. Proceed / No Further Actions
 **Case x (Proceed):**
 
 - Complete elicitation and proceed
-- Return the fully enhanced content back to create-doc.md
+- Return the fully enhanced content back to the invoking skill
 - The enhanced content becomes the final version for that section
-- Signal completion back to create-doc.md to continue with next section
+- Signal completion back to the invoking skill to continue with next section
 
 **Case a (List All):**
 

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

@@ -0,0 +1,6 @@
+---
+name: xiaoma-brainstorming
+description: 'Facilitate interactive brainstorming sessions using diverse creative techniques and ideation methods. Use when the user says help me brainstorm or help me ideate.'
+---
+
+Follow the instructions in ./workflow.md.

package/src/core/{workflows/brainstorming → skills/xiaoma-brainstorming}/steps/step-01-session-setup.md

@@ -48,6 +48,8 @@ If existing session files are found:
   **[2]** Start a new session
   **[3]** See all existing sessions"
 
+**HALT — wait for user selection before proceeding.**
+
 - If user selects **[1]** (continue): Set `{brainstorming_session_output_file}` to that file path and load `./step-01b-continue.md`
 - If user selects **[2]** (new): Generate new filename with current date/time and proceed to step 3
 - If user selects **[3]** (see all): List all session filenames and ask which to continue or if new
@@ -65,7 +67,7 @@ Create the brainstorming session document:
 mkdir -p "$(dirname "{brainstorming_session_output_file}")"
 
 # Initialize from template
-cp "{template_path}" "{brainstorming_session_output_file}"
+cp "../template.md" "{brainstorming_session_output_file}"
 ```
 
 #### B. Context File Check and Loading
@@ -155,6 +157,8 @@ When user selects approach, append the session overview content directly to `{br
 
 Which approach appeals to you most? (Enter 1-4)"
 
+**HALT — wait for user selection before proceeding.**
+
 ### 4. Handle User Selection and Initial Document Append
 
 #### When user selects approach number:

package/src/core/{workflows/brainstorming → skills/xiaoma-brainstorming}/steps/step-01b-continue.md

@@ -63,7 +63,9 @@ Based on session analysis, provide appropriate options:
 **Options:**
 [1] Review Results - Go through your documented ideas and insights
 [2] Start New Session - Begin brainstorming on a new topic
-[3) Extend Session - Add more techniques or explore new angles"
+[3] Extend Session - Add more techniques or explore new angles"
+
+**HALT — wait for user selection before proceeding.**
 
 **If Session In Progress:**
 "Let's continue where we left off!

package/src/core/{workflows/brainstorming → skills/xiaoma-brainstorming}/steps/step-02a-user-selected.md

@@ -40,7 +40,7 @@ Load techniques from CSV on-demand:
 
 **Load CSV and parse:**
 
-- Read `brain-methods.csv`
+- Read `../brain-methods.csv`
 - Parse: category, technique_name, description, facilitation_prompts, best_for, energy_level, typical_duration
 - Organize by categories for browsing
 
@@ -87,6 +87,8 @@ Show available categories with brief descriptions:
 
 **Which category interests you most? Enter 1-7, or tell me what type of thinking you're drawn to.**"
 
+**HALT — wait for user selection before proceeding.**
+
 ### 3. Handle Category Selection
 
 After user selects category:
@@ -154,6 +156,8 @@ This combination will take approximately [total_time] and focus on [expected out
 [C] Continue - Begin technique execution
 [Back] - Modify technique selection"
 
+**HALT — wait for user selection before proceeding.**
+
 ### 6. Update Frontmatter and Continue
 
 If user confirms:

package/src/core/{workflows/brainstorming → skills/xiaoma-brainstorming}/steps/step-02b-ai-recommended.md

@@ -47,7 +47,7 @@ Load techniques from CSV for analysis:
 
 **Load CSV and parse:**
 
-- Read `brain-methods.csv`
+- Read `../brain-methods.csv`
 - Parse: category, technique_name, description, facilitation_prompts, best_for, energy_level, typical_duration
 
 ### 2. Context Analysis for Technique Matching
@@ -152,6 +152,8 @@ Provide deeper insight into each recommended technique:
 [Details] - Tell me more about any specific technique
 [Back] - Return to approach selection
 
+**HALT — wait for user selection before proceeding.**
+
 ### 6. Handle User Response
 
 #### If [C] Continue:

package/src/core/{workflows/brainstorming → skills/xiaoma-brainstorming}/steps/step-02c-random-selection.md

@@ -47,7 +47,7 @@ Create anticipation for serendipitous technique discovery:
 
 **Load CSV and parse:**
 
-- Read `brain-methods.csv`
+- Read `../brain-methods.csv`
 - Parse: category, technique_name, description, facilitation_prompts, best_for, energy_level, typical_duration
 - Prepare for intelligent random selection
 
@@ -124,6 +124,8 @@ You're about to experience brainstorming in a completely new way. These unexpect
 [Details] - Tell me more about any specific technique
 [Back] - Return to approach selection
 
+**HALT — wait for user selection before proceeding.**
+
 ### 5. Handle User Response
 
 #### If [C] Continue:

package/src/core/{workflows/brainstorming → skills/xiaoma-brainstorming}/steps/step-02d-progressive-flow.md

@@ -66,7 +66,7 @@ Explain the value of systematic creative progression:
 
 **Load CSV and parse:**
 
-- Read `brain-methods.csv`
+- Read `../brain-methods.csv`
 - Parse: category, technique_name, description, facilitation_prompts, best_for, energy_level, typical_duration
 - Map techniques to each phase of the creative journey
 
@@ -176,6 +176,8 @@ Show the full progressive flow with timing and transitions:
 [Details] - Tell me more about any specific phase or technique
 [Back] - Return to approach selection
 
+**HALT — wait for user selection before proceeding.**
+
 ### 4. Handle Customization Requests
 
 If user wants customization:

package/src/core/{workflows/brainstorming → skills/xiaoma-brainstorming}/steps/step-03-technique-execution.md

@@ -1,7 +1,7 @@
 # Step 3: Interactive Technique Execution and Facilitation
 
 ---
-advancedElicitationTask: '{project-root}/_xiaoma/core/workflows/advanced-elicitation/workflow.md'
+
 ---
 
 ## MANDATORY EXECUTION RULES (READ FIRST):
@@ -290,6 +290,8 @@ After final technique element:
 [B] **Take a quick break** - Pause and return with fresh energy
 [C] **Move to organization** - Only when you feel we've thoroughly explored
 
+**HALT — wait for user selection before proceeding.**
+
 **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
@@ -303,7 +305,7 @@ After final technique element:
 #### 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 Advanced Elicitation: `{advancedElicitationTask}`
+- For option A: Invoke the `xiaoma-advanced-elicitation` skill
 
 ### 9. Update Documentation
 

package/src/core/{workflows/brainstorming → skills/xiaoma-brainstorming}/steps/step-04-idea-organization.md

@@ -249,6 +249,8 @@ Provide final session wrap-up and forward guidance:
 **Ready to complete your session documentation?**
 [C] Complete - Generate final brainstorming session document
 
+**HALT — wait for user selection before proceeding.**
+
 ### 8. Handle Completion Selection
 
 #### If [C] Complete:

package/src/core/{workflows/brainstorming → skills/xiaoma-brainstorming}/workflow.md

@@ -1,6 +1,4 @@
 ---
-name: brainstorming
-description: 'Facilitate interactive brainstorming sessions using diverse creative techniques and ideation methods. Use when the user says help me brainstorm or help me ideate.'
 context_file: '' # Optional context file path for project-specific guidance
 ---
 
@@ -42,19 +40,14 @@ Load config from `{project-root}/_xiaoma/core/config.yaml` and resolve:
 
 ### Paths
 
-- `installed_path` = `{project-root}/_xiaoma/core/workflows/brainstorming`
-- `template_path` = `{installed_path}/template.md`
-- `brain_techniques_path` = `{installed_path}/brain-methods.csv`
 - `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
-- `advancedElicitationTask` = `{project-root}/_xiaoma/core/workflows/advanced-elicitation/workflow.md`
-
 ---
 
 ## EXECUTION
 
-Read fully and follow: `steps/step-01-session-setup.md` to begin the workflow.
+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: xiaoma-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.

package/src/core/skills/xiaoma-distillator/agents/distillate-compressor.md

@@ -0,0 +1,116 @@
+# Distillate Compressor Agent
+
+Act as an information extraction and compression specialist. Your sole purpose is to produce a lossless, token-efficient distillate from source documents.
+
+You receive: source document file paths, an optional downstream_consumer context, and a splitting decision.
+
+You must load and apply `../resources/compression-rules.md` before producing output. Reference `../resources/distillate-format-reference.md` for the expected output format.
+
+## Compression Process
+
+### Step 1: Read Sources
+
+Read all source document files. For each, note the document type (product brief, discovery notes, research report, architecture doc, PRD, etc.) based on content and naming.
+
+### Step 2: Extract
+
+Extract every discrete piece of information from all source documents:
+- Facts and data points (numbers, dates, versions, percentages)
+- Decisions made and their rationale
+- Rejected alternatives and why they were rejected
+- Requirements and constraints (explicit and implicit)
+- Relationships and dependencies between entities
+- Named entities (products, companies, people, technologies)
+- Open questions and unresolved items
+- Scope boundaries (in/out/deferred)
+- Success criteria and validation methods
+- Risks and opportunities
+- User segments and their success definitions
+
+Treat this as entity extraction — pull out every distinct piece of information regardless of where it appears in the source documents.
+
+### Step 3: Deduplicate
+
+Apply the deduplication rules from `../resources/compression-rules.md`.
+
+### Step 4: Filter (only if downstream_consumer is specified)
+
+For each extracted item, ask: "Would the downstream workflow need this?"
+- Drop items that are clearly irrelevant to the stated consumer
+- When uncertain, keep the item — err on the side of preservation
+- Never drop: decisions, rejected alternatives, open questions, constraints, scope boundaries
+
+### Step 5: Group Thematically
+
+Organize items into coherent themes derived from the source content — not from a fixed template. The themes should reflect what the documents are actually about.
+
+Common groupings (use what fits, omit what doesn't, add what's needed):
+- Core concept / problem / motivation
+- Solution / approach / architecture
+- Users / segments
+- Technical decisions / constraints
+- Scope boundaries (in/out/deferred)
+- Competitive context
+- Success criteria
+- Rejected alternatives
+- Open questions
+- Risks and opportunities
+
+### Step 6: Compress Language
+
+For each item, apply the compression rules from `../resources/compression-rules.md`:
+- Strip prose transitions and connective tissue
+- Remove hedging and rhetoric
+- Remove explanations of common knowledge
+- Preserve specific details (numbers, names, versions, dates)
+- Ensure the item is self-contained (understandable without reading the source)
+- Make relationships explicit ("X because Y", "X blocks Y", "X replaces Y")
+
+### Step 7: Format Output
+
+Produce the distillate as dense thematically-grouped bullets:
+- `##` headings for themes — no deeper heading levels needed
+- `- ` bullets for items — every token must carry signal
+- No decorative formatting (no bold for emphasis, no horizontal rules)
+- No prose paragraphs — only bullets
+- Semicolons to join closely related short items within a single bullet
+- Each bullet self-contained — understandable without reading other bullets
+
+Do NOT include frontmatter — the calling skill handles that.
+
+## Semantic Splitting
+
+If the splitting decision indicates splitting is needed, load `../resources/splitting-strategy.md` and follow it.
+
+When splitting:
+
+1. Identify natural semantic boundaries in the content — coherent topic clusters, not arbitrary size breaks.
+
+2. Produce a **root distillate** containing:
+   - 3-5 bullet orientation (what was distilled, for whom, how many parts)
+   - Cross-references to section distillates
+   - Items that span multiple sections
+
+3. Produce **section distillates**, each self-sufficient. Include a 1-line context header: "This section covers [topic]. Part N of M from [source document names]."
+
+## Return Format
+
+Return a structured result to the calling skill:
+
+```json
+{
+  "distillate_content": "{the complete distillate text without frontmatter}",
+  "source_headings": ["heading 1", "heading 2"],
+  "source_named_entities": ["entity 1", "entity 2"],
+  "token_estimate": N,
+  "sections": null or [{"topic": "...", "content": "..."}]
+}
+```
+
+- **distillate_content**: The full distillate text
+- **source_headings**: All Level 2+ headings found across source documents (for completeness verification)
+- **source_named_entities**: Key named entities (products, companies, people, technologies, decisions) found in sources
+- **token_estimate**: Approximate token count of the distillate
+- **sections**: null for single distillates; array of section objects if semantically split
+
+Do not include conversational text, status updates, or preamble — return only the structured result.

package/src/core/skills/xiaoma-distillator/agents/round-trip-reconstructor.md

@@ -0,0 +1,68 @@
+# Round-Trip Reconstructor Agent
+
+Act as a document reconstruction specialist. Your purpose is to prove a distillate's completeness by reconstructing the original source documents from the distillate alone.
+
+**Critical constraint:** You receive ONLY the distillate file path. You must NOT have access to the original source documents. If you can see the originals, the test is meaningless.
+
+## Process
+
+### Step 1: Analyze the Distillate
+
+Read the distillate file. Parse the YAML frontmatter to identify:
+- The `sources` list — what documents were distilled
+- The `downstream_consumer` — what filtering may have been applied
+- The `parts` count — whether this is a single or split distillate
+
+### Step 2: Detect Document Types
+
+From the source file names and the distillate's content, infer what type of document each source was:
+- Product brief, discovery notes, research report, architecture doc, PRD, etc.
+- Use the naming conventions and content themes to determine appropriate document structure
+
+### Step 3: Reconstruct Each Source
+
+For each source listed in the frontmatter, produce a full human-readable document:
+
+- Use appropriate prose, structure, and formatting for the document type
+- Include all sections the original document would have had based on the document type
+- Expand compressed bullets back into natural language prose
+- Restore section transitions and contextual framing
+- Do NOT invent information — only use what is in the distillate
+- Flag any places where the distillate felt insufficient with `[POSSIBLE GAP]` markers — these are critical quality signals
+
+**Quality signals to watch for:**
+- Bullets that feel like they're missing context → `[POSSIBLE GAP: missing context for X]`
+- Themes that seem underrepresented given the document type → `[POSSIBLE GAP: expected more on X for a document of this type]`
+- Relationships that are mentioned but not fully explained → `[POSSIBLE GAP: relationship between X and Y unclear]`
+
+### Step 4: Save Reconstructions
+
+Save each reconstructed document as a temporary file adjacent to the distillate:
+- First source: `{distillate-basename}-reconstruction-1.md`
+- Second source: `{distillate-basename}-reconstruction-2.md`
+- And so on for each source
+
+Each reconstruction should include a header noting it was reconstructed:
+
+```markdown
+---
+type: distillate-reconstruction
+source_distillate: "{distillate path}"
+reconstructed_from: "{original source name}"
+reconstruction_number: {N}
+---
+```
+
+### Step 5: Return
+
+Return a structured result to the calling skill:
+
+```json
+{
+  "reconstruction_files": ["{path1}", "{path2}"],
+  "possible_gaps": ["gap description 1", "gap description 2"],
+  "source_count": N
+}
+```
+
+Do not include conversational text, status updates, or preamble — return only the structured result.

package/src/core/skills/xiaoma-distillator/resources/compression-rules.md

@@ -0,0 +1,51 @@
+# Compression Rules
+
+These rules govern how source text is compressed into distillate format. Apply as a final pass over all output.
+
+## Strip — Remove entirely
+
+- Prose transitions: "As mentioned earlier", "It's worth noting", "In addition to this"
+- Rhetoric and persuasion: "This is a game-changer", "The exciting thing is"
+- Hedging: "We believe", "It's likely that", "Perhaps", "It seems"
+- Self-reference: "This document describes", "As outlined above"
+- Common knowledge explanations: "Vercel is a cloud platform company", "MIT is an open-source license", "JSON is a data interchange format"
+- Repeated introductions of the same concept
+- Section transition paragraphs
+- Formatting-only elements (decorative bold/italic for emphasis, horizontal rules for visual breaks)
+- Filler phrases: "In order to", "It should be noted that", "The fact that"
+
+## Preserve — Keep always
+
+- Specific numbers, dates, versions, percentages
+- Named entities (products, companies, people, technologies)
+- Decisions made and their rationale (compressed: "Decision: X. Reason: Y")
+- Rejected alternatives and why (compressed: "Rejected: X. Reason: Y")
+- Explicit constraints and non-negotiables
+- Dependencies and ordering relationships
+- Open questions and unresolved items
+- Scope boundaries (in/out/deferred)
+- Success criteria and how they're validated
+- User segments and what success means for each
+- Risks with their severity signals
+- Conflicts between source documents
+
+## Transform — Change form for efficiency
+
+- Long prose paragraphs → single dense bullet capturing the same information
+- "We decided to use X because Y and Z" → "X (rationale: Y, Z)"
+- Repeated category labels → group under a single heading, no per-item labels
+- "Risk: ... Severity: high" → "HIGH RISK: ..."
+- Conditional statements → "If X → Y" form
+- Multi-sentence explanations → semicolon-separated compressed form
+- Lists of related short items → single bullet with semicolons
+- "X is used for Y" → "X: Y" when context is clear
+- Verbose enumerations → parenthetical lists: "platforms (Cursor, Claude Code, Windsurf, Copilot)"
+
+## Deduplication Rules
+
+- Same fact in multiple documents → keep the version with most context
+- Same concept at different detail levels → keep the detailed version
+- Overlapping lists → merge into single list, no duplicates
+- When source documents disagree → note the conflict explicitly: "Brief says X; discovery notes say Y — unresolved"
+- Executive summary points that are expanded elsewhere → keep only the expanded version
+- Introductory framing repeated across sections → capture once under the most relevant theme