/doc-consolidation

name: doc-consolidation
description: Merges ephemeral report and analysis artifacts into permanent documentation. Use when LLM-generated markdown files have accumulated and need consolidation.
globs: "**/*.md"
alwaysApply: false
category: documentation
tags:
- docs
- consolidation
- cleanup
- git-hygiene
- knowledge-management
status: stable
created: 2025-12-06
updated: 2025-12-06
modules:
- modules/candidate-detection.md
- modules/content-analysis.md
- modules/destination-routing.md
- modules/merge-execution.md

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

• Updating docs to match a code change (use `sanctum:doc-updates`)
• Detecting AI patterns in prose (use `scribe:slop-detector`)

Formatting

When merging content into permanent documentation, follow `Skill(leyline:markdown-formatting)` conventions: wrap prose at 80 chars (prefer sentence/clause boundaries), blank lines around headings, ATX headings only, blank line before lists, and reference-style links for long URLs.

Quick Start

/consolidate-docs

Or invoke directly:

I have some report files that need consolidating into permanent docs.

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)
• **Check the audience tier before routing.** A destination

serves one reader, and merging across tiers is how a getting-started page acquires an audit table. Report-derived findings, metrics, and rationale are `expert` content: route them to `docs/deep-dive/<topic>.md`, an ADR, or a benchmarks page, then link from the `newcomer` document rather than weaving into it. Tier table and cut test: `scribe:slop-detector` module `audience-targeting.md`. When the destination's own tier is unclear, **ask, do not guess**.

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]

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:

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

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

Content Categories

| Category | Description | Default Destination | |----------|-------------|---------------------| | Actionable Items | Tasks, TODOs, next steps | `docs/plans/YYYY-MM-DD-{topic}.md` | | Decisions Made | Architecture choices | `docs/adr/NNNN-{date}-{topic}.md` | | Findings/Insights | Audit results, analysis | Best-match existing doc **of the same tier**, else `docs/deep-dive/` | | Metrics/Baselines | Before/after comparisons | `docs/benchmarks/` | | Migration Guides | Step-by-step procedures | `docs/migration-guide.md` | | API Changes | Breaking changes, deprecations | CHANGELOG or api docs |

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 n