Table of Contents

• •When to Use
• •Quick Start
• •Two-Phase Workflow
• •Phase 1: Triage (Fast Model)
• •Phase 2: Execute (Main Model)
• •Workflow Details
• •Step 1: Candidate Detection
• •Step 2: Content Analysis
• •Step 3: Destination Routing
• •Step 4: Generate Plan
• •Source: API_REVIEW_REPORT.md
• •Post-Consolidation
• •Step 5: Execute Merges
• •Fast Model Delegation
• •Content Categories
• •Merge Strategies
• •Intelligent Weave
• •Replace Section
• •Append with Context
• •Create New File
• •Integration
• •Example Session
• •Troubleshooting
• •No candidates found
• •Low-quality extractions
• •Merge conflicts
• •Related Skills

Doc Consolidation

Extracts valuable knowledge from ephemeral LLM outputs and merges it into permanent documentation.

When To Use

Use this skill when:

• •You have untracked *_REPORT.md or *_ANALYSIS.md files from Claude sessions
• •Git status shows markdown files that shouldn't be committed but contain useful content
• •You want to preserve insights from code reviews, refactoring reports, or API audits
• •Preparing a PR and need to clean up working artifacts

Do NOT use when:

• •Files are already in proper documentation locations (docs/, skills/)
• •Files are intentionally temporary scratch notes
• •User explicitly wants to preserve the original report format
• •Source files have no extractable value (pure log output)

When NOT To Use

• •Files are already in docs/ or skills/ locations
• •Files are intentionally temporary scratch notes
• •Source files have no extractable value
• •Files are already in docs/ or skills/ locations

Quick Start

/consolidate-docs

Verification: Run the command with --help flag to verify availability.

Or invoke directly:

**Verification:** Run the command with `--help` flag to verify availability.
I have some report files that need consolidating into permanent docs.

Verification: Run the command with --help flag to verify availability.

Two-Phase Workflow

Phase 1: Triage (Fast Model)

Read-only analysis to generate a consolidation plan:

1. •Detect candidates - Find untracked markdown files with LLM output markers
2. •Analyze content - Extract and categorize valuable sections
3. •Route destinations - Match content to existing docs or propose new files
4. •Present plan - Show user what will be consolidated and where

Checkpoint: User reviews and approves plan before execution.

Phase 2: Execute (Main Model)

After approval, performs the consolidation:

1. •Merge content - Weave into existing docs or create new files
2. •Delete sources - Remove ephemeral files after successful merge
3. •Generate summary - Report what was created/updated/deleted

Workflow Details

Step 1: Candidate Detection

Load: @modules/candidate-detection.md

Identifies files using:

• •Git status (untracked .md files)
• •Location (not in standard doc directories)
• •Naming (ALL_CAPS non-standard names)
• •Content markers (Executive Summary, Findings, Action Items)

Step 2: Content Analysis

Load: @modules/content-analysis.md

For each candidate:

• •Extract sections as content chunks
• •Categorize: Actionable Items, Decisions, Findings, Metrics, Migration Guides, API Changes
• •Score value: high/medium/low

Step 3: Destination Routing

Load: @modules/destination-routing.md

For each valuable chunk:

• •Semantic match against existing documentation
• •Apply default mappings if no good match
• •Determine merge strategy (weave, replace, append, create)

Step 4: Generate Plan

Present consolidation plan to user:

# Consolidation Plan

## Source: API_REVIEW_REPORT.md

| Content | Category | Value | Destination | Action |
|---------|----------|-------|-------------|--------|
| API inventory | Findings | High | docs/api-overview.md | Create |
| Action items | Actionable | High | docs/plans/2025-12-06-api.md | Create |

### Post-Consolidation
- Delete: API_REVIEW_REPORT.md

Proceed with consolidation? [Y/n]

Verification: Run the command with --help flag to verify availability.

Step 5: Execute Merges

Load: @modules/merge-execution.md

After user approval:

• •Group operations by destination file
• •Apply merge strategies
• •Validate results (frontmatter intact, structure preserved)
• •Delete source files
• •Generate execution summary

Fast Model Delegation

Phase 1 tasks are delegated to haiku-class models for efficiency:

# scripts/consolidation_planner.py handles:
- scan_for_candidates()
- extract_content_chunks()
- categorize_chunks()
- score_value()
- find_semantic_matches()

Verification: Run the command with --help flag to verify availability.

Phase 2 stays on the main model for careful merge execution.

Content Categories

Merge Strategies

Intelligent Weave

Insert content into matching existing sections, preserving style.

Use when: Destination has relevant section, content is additive.

Replace Section

Replace existing section with more detailed new content.

Use when: New content 2x+ more detailed or has later date.

Append with Context

Add new section with date and source reference.

Use when: No matching section, content doesn't fit existing structure.

Create New File

Generate complete new document.

Use when: No suitable destination exists, content warrants standalone doc.

Integration

Works with other sanctum skills:

• •git-workspace-review: May suggest consolidation when untracked reports detected
• •pr-prep: Warns about untracked analysis files before PR creation
• •doc-updates: Can invoke for final polish after consolidation

Example Session

**Verification:** Run the command with `--help` flag to verify availability.
User: I have API_REVIEW_REPORT.md from our review session. Can you consolidate it?

Claude: I'll consolidate the report into permanent documentation.

**Phase 1: Triage**

Scanning for candidates...
- Found: API_REVIEW_REPORT.md (untracked, LLM markers detected)

Analyzing content...
- Extracted 6 content chunks
- High value: API inventory, action items, CLI recommendation
- Medium value: security assessment
- Low value: executive summary (generic)

Routing destinations...
- API inventory → docs/api-overview.md (CREATE)
- Action items → docs/plans/2025-12-06-api-consistency.md (CREATE)
- CLI naming → docs/adr/0002-cli-naming.md (CREATE ADR)
- Security → Already covered in docs/security.md (SKIP)

**Consolidation Plan**
[table shown]

Proceed? [Y/n]

User: Y

Claude: **Phase 2: Executing**

Created: docs/api-overview.md (1,247 bytes)
Created: docs/plans/2025-12-06-api-consistency.md (892 bytes)
Created: docs/adr/0002-2025-12-06-cli-naming.md (634 bytes)
Deleted: API_REVIEW_REPORT.md

Consolidation complete. Review the created files and commit when ready.

Verification: Run the command with --help flag to verify availability.

Troubleshooting

No candidates found

• •Check git status for untracked files
• •Files may already be in standard locations
• •Try explicit file path: "Consolidate API_REVIEW_REPORT.md"

Low-quality extractions

• •Source file may lack structured sections
• •Content may be too generic to categorize
• •Try manual extraction for unstructured reports

Merge conflicts

• •Destination file structure changed
• •Try APPEND strategy instead of WEAVE
• •Manual intervention may be needed

Related Skills

• •sanctum:doc-updates - General documentation updates
• •sanctum:git-workspace-review - Pre-flight workspace analysis
• •sanctum:pr-prep - Pull request preparation
• •imbue:catchup - Understanding recent changes