A reusable Claude Code skill that turns
a long LLM-conversation export (a single .md transcript, typically
100k–10M chars) into a navigable nested document tree, an imperative
dev guide, and a set of architecture decision records (ADRs).
The original transcript is never edited. Every artifact is
regenerable from the manifests, and the pipeline ships with a
verify.py that runs 9 end-to-end integrity checks (hash, line
coverage, cross-references, link integrity, idempotency).
| Artifact | Where | Produced by |
|---|---|---|
source.sha256, turns.json |
<output-dir>/manifests/ |
Stage 0 (script) |
phases.json, decisions.json, reconciliation.md |
<output-dir>/manifests/ |
Stage 1 (agents) |
phase-NN-<slug>/turn-NNN-<role>.md |
<output-dir>/raw/ |
Stage 2 (script) |
dev-guide/00-overview.md, dev-guide/NN-<slug>.md |
<docs-dir>/ |
Stage 3 (agents) |
decisions/NNNN-<slug>.md, decisions/README.md |
<docs-dir>/ |
Stage 4 (agents) |
source.md ──► Stage 0 ──► Stage 1 ──► Stage 2 ──► Stage 3 ──► Stage 4 ──► Stage 5
(script) (agents) (script) (agents) (agents) (manual)
- Scripts are deterministic — re-running produces byte-identical output. Used where bytes matter (turn segmentation, file splitting, verification).
- Agents are non-deterministic but semantically equivalent across runs. Used where meaning matters (phase clustering, chapter writing, ADR extraction).
- Manifests are the contract between layers. Cross-reference validation catches integration bugs before they propagate.
This repo IS a fragment of .claude/ — drop its contents into your
project's .claude/:
git clone https://github.com/Ethycs/claude-chat-decompose.git
cp -r claude-chat-decompose/.claude/. /path/to/your-project/.claude/If your project doesn't have a .claude/ directory yet, just rename:
git clone https://github.com/Ethycs/claude-chat-decompose.git
cp -r claude-chat-decompose/.claude /path/to/your-project/The skill needs Python 3.11+ for the scripts. No third-party dependencies — pure standard library.
Once installed, three ways to invoke from your project:
Slash command (Claude Code):
/decompose-chat path/to/your-export.md
Natural language (Claude Code) — the skill auto-triggers:
"Decompose this chat export at
transcripts/team-design-call.mdinto a doc tree."
Direct script invocation (no Claude Code required for the deterministic stages):
python .claude/skills/chat-decompose/scripts/build_turn_index.py \
--source path/to/export.md \
--output-dir _ingest
python .claude/skills/chat-decompose/scripts/split_into_phases.py \
--source path/to/export.md \
--output-dir _ingest
python .claude/skills/chat-decompose/scripts/verify.py \
--source path/to/export.md \
--output-dir _ingest \
--docs-dir docs(Stages 1, 3, and 4 are agent-driven and need a Claude Code session, or you can hand-write the manifests yourself and run only the deterministic stages.)
Defaults match the most common Claude/ChatGPT markdown export format:
- Turn delimiter:
^---\s*$(---line outside code fences) - Role heading:
^##\s+(User|Assistant)\s*$
Other formats are supported via --turn-delim / --role-pattern
flags. Examples:
# ChatGPT export with **You:** / **ChatGPT:**
--turn-delim '^\s*$' --role-pattern '^\*\*(You|ChatGPT):\*\*'
# Slack-style with H3 role headings
--role-pattern '^###\s+(User|Assistant):'The skill orchestrator sniffs the first 200 lines of the source and proposes appropriate flags before running.
Five agent dispatches across the pipeline:
- Three parallel
chat-decompose-clustereragents in Stage 1a — each reads a third of the merged turns and proposes phase boundaries + decision moments as JSON. - One
chat-decompose-reconcileragent in Stage 1b — merges the three proposals into canonicalphases.json,decisions.json,reconciliation.md. chat-decompose-chapteragents in Stage 3 (one per phase, up to 3 in parallel per round) — write the imperative dev-guide chapters.chat-decompose-adragents in Stage 4 (up to 3 in parallel, each may write 1–4 ADRs) — write the MADR-lite ADRs.
If those subagent definitions aren't installed, the orchestrator falls
back to general-purpose / Explore / Plan agents with templated
prompts.
claude-chat-decompose/
├── README.md ← you are here
├── LICENSE ← MIT
└── .claude/ ← drop into your project's .claude/
├── skills/
│ └── chat-decompose/
│ ├── SKILL.md ← orchestrator instructions
│ ├── README.md ← skill-level docs
│ ├── scripts/
│ │ ├── build_turn_index.py
│ │ ├── split_into_phases.py
│ │ └── verify.py
│ └── templates/
│ ├── phase_proposal.md
│ ├── phase_reconcile.md
│ ├── chapter.md
│ └── adr.md
├── agents/
│ ├── chat-decompose-clusterer.md ← Explore-style proposal agent
│ ├── chat-decompose-reconciler.md ← Plan-style reconciliation agent
│ ├── chat-decompose-chapter.md ← chapter writer (Write access)
│ └── chat-decompose-adr.md ← ADR writer (Write access)
└── commands/
└── decompose-chat.md ← /decompose-chat <path>
- Multiple same-role blocks per logical turn. Many exporters split
one assistant reply into multiple
## Assistantblocks (one per text segment between tool calls). The merged-turn collapse handles this — operate onmerged_turnsfor phase reasoning, on sub-turns for byte-level addressing. ---inside code fences. The script ignores delimiters inside```/~~~fences. If the export uses different fence markers, pass a custom regex.- Plan-type subagents are read-only. They cannot
Write; they return content as text. Usegeneral-purpose(or thechat-decompose-chapter/chat-decompose-adrsubagents in this skill) for any agent that must produce files. - Cross-reference validation is mandatory. After Stage 1b, validate that every decision's turn refs fall inside the phase it claims. Three real cross-reference bugs were caught in the bootstrap run that produced this skill.
- The skill's own README has more detail on per-stage internals.
SKILL.mdis the orchestrator's instructions — read this if you want to understand exactly how the agents are dispatched.
MIT — see LICENSE.