Consolidate

Consolidate factual information from multiple source documents into one distilled body of work while not losing fidelity on nuance, detail, and resolution. This is consolidation, not summarization — the goal is to be as lossless as possible within scope.

The skill runs headless by default. No user interaction during execution. Conflicts, ambiguities, and open questions that cannot be resolved autonomously are surfaced in the output document itself.

---

Core Architecture

Analyze with claims, generate from sources.

Claims are an analytical layer — used for conflict detection, deduplication, gap identification, and coverage auditing. The consolidated document is generated from the original source text, guided by the analysis. This preserves code blocks, tables, examples, and structural detail that atomization would destroy.

Sources → ANALYZE (extract claims + build source map)
       → CROSS-SOURCE ANALYSIS (dedup, conflicts, scope, topic map)
       → GENERATE FROM SOURCES (read source text, guided by analysis)
       → VERIFY (check output against claim inventory)
       → OUTPUT

Architectural principle: Per-source ANALYSIS, cross-source GENERATION. Analysis (claim extraction, source mapping) is per-source isolated. Generation (recomposition) reads from all sources, guided by the cross-source analysis.

---

Output Artifacts

The skill produces artifacts at caller-specified paths:

1. Consolidated Document — coherent prose with inline citations, dedicated Conflicts & Open Questions sections. Filename is caller-specified (default: CONSOLIDATED.md). Citation format and document structure follow any conventions loaded by the caller. The document should read as if it were authored fresh — no consolidation provenance (source-report IDs, metadata tables, /tmp/ paths). Consolidation metadata goes in CLAIMS.md only.
2. Enriched Claim Inventory — per-claim records with provenance, confidence, content type, conflicts, and verification status. Exhaustive — surfaces ALL claims for auditing. Filename is caller-specified (default: CLAIMS.md).
3. Evidence files (optional) — when an evidence output path is specified, write per-dimension evidence files. Format follows any conventions loaded by the caller (e.g., research skill references).

---

Mandatory Execution Order

Execute these phases in order. Each phase completes before the next begins.

1. Phase 0: Setup — Parse inputs, detect available tools, create working directory
2. Phase 1: ANALYZE SOURCES — Extract claims + build source map (per source, independently)
3. Phase 2: CROSS-SOURCE ANALYSIS — Dedup claims, detect conflicts, scope filter, build topic map + outline
4. Phase 3: GENERATE FROM SOURCES — Draft from source text, guided by topic map + conflict analysis
5. Phase 4: VERIFY — Claim coverage audit, structural completeness audit, faithfulness check
6. Phase 5: OUTPUT — Write consolidated document + CLAIMS.md

---

Phase 0: Setup

Create workflow checkpoint tasks

⛔ ALWAYS THE FIRST ACTION. Before parsing inputs or reading sources, create tasks for each phase. These persist across context compaction and make skipped phases visible.

TaskCreate: "Consolidate: Setup — parse inputs, detect tools"            → in_progress
TaskCreate: "Consolidate: Analyze sources — claims + source maps"        → pending
TaskCreate: "Consolidate: Cross-source analysis — dedup, conflicts"      → pending
TaskCreate: "Consolidate: Generate from sources — draft sections"        → pending
TaskCreate: "Consolidate: Cross-cutting synthesis — patterns across sections" → pending
TaskCreate: "Consolidate: Verify — coverage + structural audit"          → pending
TaskCreate: "Consolidate: Output — write artifacts"                      → pending

Mark each task in_progress when starting, completed when done. The cross-cutting synthesis and verify tasks are the most commonly skipped — if you find yourself assembling or writing output without completing them, STOP.

Parse inputs

Read the invocation arguments:

• Sources: file paths, glob patterns, or inline content. Resolve globs. Report which sources are accessible and which are not.
• Output file: explicit file path for the consolidated document (e.g., /path/to/REPORT.md). If a directory is given instead, write CONSOLIDATED.md in that directory. If not specified, write CONSOLIDATED.md in the current directory.
• Claims file: explicit file path for the claim inventory. Default: CLAIMS.md alongside the output file.
• Evidence path (optional): directory for evidence files (e.g., /path/to/evidence/). If specified, write per-dimension evidence files there. If not specified, no evidence files — CLAIMS.md is sufficient.
• Scope (optional): question, rubric, freeform criteria, or none. Default: "everything in sources."
• Consolidation brief (optional): purpose, priorities, stance, conflict resolution preference.

If no brief is provided, derive purpose from the sources themselves (scan first few lines of each to understand the domain and apparent intent).

Create working directory

Create a temporary working directory for intermediary files:

CONSOLIDATE_WORK_DIR=$(mktemp -d /tmp/consolidate-XXXXXX)

Clean up this directory after Phase 5 (OUTPUT) completes.

Detect execution mode

Check which tools are available for parallel source analysis:

Check	Result	Execution mode
Task/Agent tool accessible?	Yes	Subagents — fan out one per source
Task/Agent tool inaccessible, Bash accessible?	Yes	Nested claudes — spawn via env -u CLAUDECODE -u CLAUDE_CODE_ENTRYPOINT claude -p "..." --dangerously-skip-permissions < /dev/null
Neither accessible	—	Sequential — process each source in separate prompts within own context

Log the detected mode. The quality principle (per-source isolation for analysis) is the same in all modes.

---

Phase 1: ANALYZE SOURCES

⛔ Per-source analysis — NEVER analyze multiple sources in the same pass. Each source gets its own analysis pass. This prevents cross-source contamination during claim extraction.

Load: references/decomposition-prompts.md

For each source independently, produce two outputs:

1. Claim inventory (for analysis)

Extract ALL substantive content as structured claims. Every assertion, code block, table, example, and reasoning chain — tagged by content type:

## Claim: "[claim text or description]"
- **Source:** [source_id]
- **Span:** [original text from source]
- **Normalized:** [claim restated for cross-source comparison]
- **Confidence:** [CONFIRMED | SUPPORTED | INFERRED | UNCERTAIN]
- **Content type:** [prose | code | table | example | diagram | reasoning-chain]
- **Source type:** [structured | unstructured]

Content type tagging is critical. Code blocks, tables, and examples must be extracted as intact units with their content type tagged — not atomized into [entity] [fact] fragments. A code block is ONE claim of type code. A comparison table is ONE claim of type table. This enables the structural completeness audit in Phase 4.

2. Source map (for generation)

Build a section-by-section index of the source. This tells Phase 3 WHERE to find content:

## Source Map: [source_id]

### Section: [heading or topic]
- **Content types present:** [prose, code, table, ...]
- **Topic tags:** [key topics this section covers]
- **Claim IDs:** [C1, C2, C5 — which claims came from this section]
- **Location:** [line range or section identifier in the source]

The source map is cheap to produce (indexing, not decomposing) and preserves the connection between claims and their original source context.

Parallel execution

Load: references/worker-handoff.md

• Subagent mode: Dispatch one subagent per source (cap ~5 concurrent). Each writes claims + source map to the working directory.
• Nested claude mode: Same pattern via Bash background commands.
• Sequential mode: Process each source in a separate prompt.

For >5 sources: batch into groups of ~5, process groups sequentially, each group's sources in parallel.

After all sources are analyzed, merge all per-source claim inventories into a unified claim inventory and all source maps into a unified source map.

---

Phase 2: CROSS-SOURCE ANALYSIS

Load: references/conflict-detection.md

This phase operates on the unified claim inventory and unified source map. All work is cross-source.

Step 1: Deduplicate claims

Identify semantically equivalent claims across sources:

• Claims with very similar normalized forms likely say the same thing
• When duplicates are found: keep the most detailed variant as representative, record all source attributions
• Flag near-duplicates with subtle differences for conflict review

Step 2: Detect and classify conflicts

For claims that address the same subject but make different assertions:

1. Detect: Are there conflicts? Use binary detection with chain-of-thought.
2. Classify type using the 5-type semantic taxonomy (no conflict, complementary, conflicting opinions, freshness, misinformation).
3. Distinguish contradiction from novelty: Sources covering different topics are complementary, not conflicting.
4. Detect conclusion disagreements: After factual conflict detection, scan for sources that agree on facts but reach different conclusions or recommendations about the same decision. These are not factual conflicts — they are reconcilable tensions where both positions are valid under different framings. Surface them in the Conflicts section as "Conclusion disagreement" with an explicit reconciliation explaining how both positions are compatible.

Step 3: Resolve or surface conflicts

Apply type-appropriate resolution:

Conflict type	Action
No conflict	Proceed — no action needed
Complementary	Consolidate all perspectives cohesively
Conflicting opinions	Surface all viewpoints neutrally. Do NOT pick a winner.
Freshness	Prefer the most recent. Acknowledge the outdated.
Misinformation	Discard the inaccurate claim. Note in claim inventory.

For conflicts that cannot be classified confidently, surface both positions.

Step 4: Apply scope filter (if scoped)

If a scope was provided:

• Classify each claim as in-scope or out-of-scope
• Remove out-of-scope claims (retain in inventory with scope: out-of-scope tag)
• Check for in-scope topics with no claims — note as missing coverage

Step 5: Build topic map and outline

Merge the per-source source maps into a topic map — grouping source sections by topic across all sources:

## Topic: [topic name]
- **Source sections:** S1/Section 3, S2/Section 1, S4/Section 7
- **Content types present:** [prose, code, table]
- **Conflicts on this topic:** [F1 — opinions on X]
- **Gaps:** [no source covers Y aspect]

Generate the outline from the topic map:

⛔ Every topic in the topic map MUST become a section in the outline. The LLM may organize, order, and group topics — but it MUST NOT drop any. If a source section exists and is in scope, it gets an outline section. The source map is the completeness guarantee. Dropping topics silently is the #1 cause of coverage loss.

• Each topic becomes a section with a descriptive heading
• Order by: importance (topics covered by more sources first), then logical flow
• For each section: note which source sections to read, what conflicts to apply, what content types to preserve
• If a topic's content naturally forms a comparison, flag for table format
• Topics covered by only one source still get their own section — single-source content is not "less important"

---

Phase 3: GENERATE FROM SOURCES

Load: references/recomposition-prompts.md

⛔ Generate from source text, not from claims. The outline and conflict analysis guide WHAT to write and WHERE to watch for issues. The source text provides the actual content — preserving code blocks, tables, examples, and detail.

⛔ Never generate the entire document in one pass. Section-by-section drafting prevents end-of-output hallucination and lost-in-the-middle effects.

Step 1: Draft each section independently

For each section in the outline (separate prompt per section):

1. Read the relevant source sections identified in the topic map (the actual source text)
2. Read the conflict analysis for this topic from Phase 2
3. Draft the section from the source text:
   • Write coherent prose that preserves the depth and detail of the source material
   • Preserve code blocks verbatim from sources — do not summarize code into prose descriptions
   • Preserve tables from sources — reproduce comparison matrices, benchmark tables, feature matrices
   • Preserve examples — worked examples, step-by-step walkthroughs, architectural patterns
   • Where sources overlap on the same point: synthesize into a single treatment (don't duplicate)
   • Where sources have unique content on the same topic: include all unique content
   • Where sources conflict: apply the resolution from Phase 2 (surface opinions, prefer recent, discard misinformation)
   • Include inline citations linking substantive claims to sources — follow any citation format conventions loaded by the caller. If no conventions loaded, use [n] numbered refs as default.
   • Preserve hedging and epistemic markers from sources — NEVER upgrade uncertainty

Step 2: Coherence cross-check (as you draft, not after)

While drafting and reviewing sections, actively check:

• Cross-finding consistency: If two sections address the same topic, ensure they don't contradict without explanation. Reconcile (one is conditional) or acknowledge the tension.
• Stat consistency: When the same number appears in multiple sections, verify all instances use the same value. Stats drift when copied.
• Claim fidelity: When synthesizing quantitative claims, preserve the exact population, metric type, and qualifiers from the source. Do not mutate "40% of star performers" into "40% more deals" — these are different claims.
• Confidence-prose alignment: Match prose certainty to evidence strength. Declarative for confirmed findings, hedged for inferred.
• Conditionality: If a finding is version-bound, config-dependent, or context-specific, state the conditions. Do not flatten into unconditional claims.

Step 3: Cross-cutting synthesis

⛔ Mark the "Cross-cutting synthesis" task as in_progress. Do not skip this step.

After all content sections are drafted, review them together as a whole. Identify named themes — insights that emerge from the combination of sections that no individual section captures on its own.

For each theme, produce:

### Theme: [descriptive name]

[1-3 sentences explaining the pattern and why it matters]

**Evidence across sections:** Section N established X. Section M confirmed Y
from a different angle. Section P's finding on Z reinforces this because...

**Implication:** [What this means for the reader — a conclusion that only
becomes visible when looking across sections]

What to look for:

• Convergent findings — multiple sections independently arrive at the same conclusion from different evidence. Name the convergence.
• Tensions — one section's recommendation creates constraints for another. Name the tradeoff.
• Emergent implications — the combination of findings answers a question that no individual section addresses. Name the answer.

When consolidating multiple source sections, cross-cutting synthesis is expected, not optional — multiple independent investigations covering related ground will almost always produce cross-cutting patterns. If you genuinely cannot identify any, state that explicitly and explain why (e.g., "the sources cover completely independent topics with no conceptual overlap").

Breadth matters. Themes that draw evidence from more sections are more valuable than narrow themes — a pattern visible across many dimensions is higher-value synthesis than one confined to two sections. Produce as many genuine themes as the evidence supports; do not consolidate themes just to make them wider.

Step 4: Generate dedicated sections

After content and synthesis sections, generate Conflicts & Disagreements, Open Questions, and Limitations sections. (See references/recomposition-prompts.md for templates.) Do NOT include a "Consolidation Metadata" section in the document — metadata goes in CLAIMS.md only. The document should read as authored fresh.

Step 5: Assemble

Combine all independently drafted sections into one document. Add minimal connecting tissue between sections. Do NOT rewrite — assemble.

---

Phase 4: VERIFY

Single verification pass. Do NOT iterate beyond one critique + revision.

Claim coverage audit (bidirectional)

1. Faithfulness (precision): For each substantive claim in the output, verify it traces to a source claim in the inventory. Flag any claim that doesn't.
2. Completeness (recall): For each in-scope claim in the source inventory, check it appears in the output. Flag any important source claim that's missing.

Structural completeness audit

Check that content types present in sources survived into the output:

• For each claim tagged code in the inventory: is there a corresponding code block in the output?
• For each claim tagged table: is there a table or structured comparison in the output?
• For each claim tagged example: is there a worked example in the output?
• Flag structural drops — content types that existed in sources but are absent from output.

Faithfulness check

Review the output for:

• Claims not supported by any source (hallucination)
• Hedging that was upgraded ("may cause" → "causes")
• Attributions that don't match (citations pointing to wrong source)

Single revision

Fix issues found in the audits. Do NOT iterate further — quality degrades after 2-3 revision passes.

---

Phase 5: OUTPUT

Write artifacts to the caller-specified paths:

1. Consolidated document (at the output file path) — the assembled, verified document
2. Claim inventory (at the claims file path) — the enriched claim inventory with per-claim metadata including content types
3. Evidence files (at the evidence path, if specified) — per-dimension evidence files following any formatting conventions loaded by the caller

If no explicit filename was given, use defaults: CONSOLIDATED.md and CLAIMS.md.

Clean up the working directory ($CONSOLIDATE_WORK_DIR).

Log a completion summary: sources processed, claims extracted, conflicts detected, coverage ratio, structural completeness.

---

Prompting Invariants

These constraints apply to every prompt in the pipeline — analysis workers, generation drafts, verification judgments.

Embed in every generation prompt:

You have high metacognitive awareness. Express uncertainty faithfully:
- Use confident language for well-supported claims
- Use calibrated hedging ("evidence suggests," "likely," "sources indicate")
  for inferred or uncertain claims
- Explicitly state when information is missing or sources are insufficient
- Never upgrade hedging from source material — if a source says "may cause,"
  output "may cause," not "causes"
- If sources lack necessary information, say so rather than speculating

Embed in every generation prompt:

After generating, review your output and identify:
1. Topics within scope that no source addresses (missing coverage)
2. Claims where sources provide insufficient evidence (low-confidence)
3. Points where sources contradict each other (conflicts)
4. Terms or claims that are ambiguous without additional context

Surface all of these. Do NOT silently resolve ambiguity by choosing one
interpretation. Do NOT omit missing coverage.

---

Anti-Patterns

Anti-pattern	What it looks like	Correction
Generating from claims instead of sources	Drafting prose from the claim inventory rather than reading source text	Claims are for analysis and verification. Read the actual source sections during Phase 3 drafting.
Cross-source analysis in Phase 1	Reading multiple sources in one prompt during claim extraction	Each source gets its own analysis pass. No exceptions.
Monolithic output	Generating the entire consolidated document in one prompt	Use the outline → section-by-section pattern
Summarizing code blocks	Converting a code example into a prose description	Preserve code blocks verbatim from sources. They ARE the content.
Flattening tables	Converting a comparison table into a list or prose paragraph	Preserve tables as tables. The structure carries information.
Silent conflict resolution	Picking one source's version without noting the disagreement	Classify the conflict type, apply type-appropriate resolution, surface in Conflicts section
Hedging upgrade	Source says "may" → output says "does"	Preserve the original epistemic marker. When in doubt, hedge MORE, not less.
Over-hedging	Every sentence has "possibly," "perhaps," "it's unclear"	Only hedge where genuine uncertainty exists. High-confidence claims get clean, authoritative prose.
Novelty-as-contradiction	Flagging sources that cover different topics as "conflicting"	Complementary coverage is not a conflict. Only flag opposing assertions about the same subject.
Iterative revision spiral	Running 3+ revision passes trying to perfect the output	Cap at one critique + revision pass. Quality degrades after 2-3 iterations.
Dropping unique source content	Only including content that appears in multiple sources	Every source's unique contributions within scope belong in the output. Multiple-source content gets synthesis; single-source content gets inclusion.
Dropping entire dimensions	Omitting entire source sections/topics from the outline because they seem "less important"	Every topic in the source map MUST appear in the outline. Organize and order — never drop.
Provenance leakage	Consolidated document contains source-report identifiers ("S4"), consolidation metadata tables, /tmp/ paths, or "(from source reports)" labels	The document must read as if authored fresh. All consolidation provenance goes in CLAIMS.md only.
Excessive duplication	Same finding stated 3+ times across sections because multiple topics reference it	State each finding ONCE in its primary section. Other sections reference it briefly ("as discussed in Section N") rather than restating.

Incorrect vs Correct Examples

Silent conflict resolution (WRONG):

Two sources disagree on architecture: Source A recommends "git as persistence layer with in-memory editing state." Source B recommends "source code becomes a derived view from a component CRDT — not the canonical data." The consolidation silently adopts Source B's position as the unified recommendation without acknowledging Source A's more conservative approach existed.

Surfacing the conflict (CORRECT):

The consolidation presents both positions, classifies the conflict type, and either resolves with evidence or surfaces as unresolved: "Sources diverge on the source-of-truth architecture. Source A recommends git as the persistence layer with in-memory editing state [1]. Source B goes further, recommending source code as a derived view from a component CRDT [2]. This reflects a genuine architectural tension between..." The Conflicts section has a structured entry.

Flattening epistemic qualifiers (WRONG):

Source says: "the architecture appears generalizable to any skill that needs persistent multi-iteration workflows (ASSESSED — not production-tested outside /ship)." The consolidation writes: "The architecture is generalizable to any skill that needs persistent multi-iteration workflows."

The qualifier "(ASSESSED — not production-tested)" carried critical information: this is an inference, not a verified claim. Dropping it converts uncertainty into false certainty.

Preserving epistemic qualifiers (CORRECT):

The consolidation preserves the qualifier: "The architecture appears generalizable to persistent multi-iteration workflows, though this has been assessed architecturally rather than production-tested outside its current use in /ship [1]."

Unattributed cross-source synthesis (WRONG):

The consolidation weaves findings from 4 sub-reports into a seamless narrative. A reader cannot tell which sub-report contributed "no OSS editor persists undo history" or "Figma achieves 600ms p95 edit persistence." These could be verified findings or hallucinations — there's no way to audit.

Attributed claims (CORRECT):

Each substantive claim has an inline citation linking to the source. The CLAIMS.md inventory maps every claim to its source with the original span. A reader can audit any claim by checking the citation.

---

Summarizing code blocks (WRONG):

The source has a code example showing how the undo manager is configured with three parameters. The consolidation replaces it with:

"The undo manager uses a three-gate system with captureTimeout, trackedOrigins, and deleteFilter to control which operations are undoable."

This loses the actual implementation — a reader can't use the prose description to write the code.

Preserving code blocks (CORRECT):

The consolidation reproduces the code block from the source verbatim, with a brief prose introduction explaining what it does. The code IS the content — prose describes it, but doesn't replace it.

Flattening tables (WRONG):

The source has a comparison table of 5 platforms across 4 dimensions. The consolidation replaces it with:

"The platforms handle persistence differently: A uses X, B uses Y, C uses Z..."

This loses the comparative structure — a reader can't scan across dimensions for a specific platform.

Preserving tables (CORRECT):

The consolidation reproduces the table from the source. If multiple sources have overlapping tables, merge into one comprehensive table with all columns and rows. The table structure carries comparative meaning that prose cannot.

Dropping a dimension (WRONG):

Seven source topics exist in the source map, but the outline only has 5 sections. Two topics that appeared in a single sub-report were silently excluded because they "don't fit the main narrative."

Including all dimensions (CORRECT):

Seven source topics → seven outline sections. Single-source topics get their own sections. They may be shorter, but they are present. The outline organizes and orders — it never drops.

---

Reference Index

Path	Priority	Use when
references/decomposition-prompts.md	P0	Phase 1 — extracting claims + building source maps
references/conflict-detection.md	P0	Phase 2 — detecting and classifying conflicts
references/recomposition-prompts.md	P0	Phase 3 — drafting from source text with analysis guidance
references/claim-inventory-format.md	P0	Writing CLAIMS.md — the enriched claim inventory
references/worker-handoff.md	P1	Dispatching analysis workers (subagents or nested claudes)