Skip to content

About

A reusable Claude Code skill that decomposes long LLM-conversation exports into a navigable doc tree, imperative dev guide, and MADR-lite architecture decision records.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

1 Commit

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 

Repository files navigation

claude-chat-decompose

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).

What you get

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)

Pipeline

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.

Install

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.

Use

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.md into 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.)

Configuring for non-standard transcript formats

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.

What the agents do

Five agent dispatches across the pipeline:

  1. Three parallel chat-decompose-clusterer agents in Stage 1a — each reads a third of the merged turns and proposes phase boundaries + decision moments as JSON.
  2. One chat-decompose-reconciler agent in Stage 1b — merges the three proposals into canonical phases.json, decisions.json, reconciliation.md.
  3. chat-decompose-chapter agents in Stage 3 (one per phase, up to 3 in parallel per round) — write the imperative dev-guide chapters.
  4. chat-decompose-adr agents 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.

Repo layout

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>

Common gotchas

  • Multiple same-role blocks per logical turn. Many exporters split one assistant reply into multiple ## Assistant blocks (one per text segment between tool calls). The merged-turn collapse handles this — operate on merged_turns for 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. Use general-purpose (or the chat-decompose-chapter / chat-decompose-adr subagents 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.

See also

  • The skill's own README has more detail on per-stage internals.
  • SKILL.md is the orchestrator's instructions — read this if you want to understand exactly how the agents are dispatched.

License

MIT — see LICENSE.

About

A reusable Claude Code skill that decomposes long LLM-conversation exports into a navigable doc tree, imperative dev guide, and MADR-lite architecture decision records.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages