Context kit split

Split Context Docs Skill

Move accumulated history out of session-loaded entry-point docs into dedicated companion files. Keeps the per-session context bill low without losing the history (it just lives in a separate, grep-able file).

---

Conventions (governed by context-kit-steward)

--- GOVERNED CONVENTIONS (source: context-kit-steward charter v1.0) --- Do not edit here. Change the charter in context-kit-steward and re-run it to re-sync; local edits to this block will be overwritten on the next sync.

This skill honors these shared Context Kit conventions (full text + rationale in the context-kit-steward charter):

• Preserves C2 (ordering): history moved into a companion file keeps its existing order (changelog newest-first; history chronological) -- a relocation, not a re-sort.
• Preserves C7 (hygiene): substance is moved verbatim; never drop or alter content, and never introduce secrets or absolute mount/session paths.
• Follows C3 (concurrency): re-read shared index files before editing; make minimal targeted edits; do not blind-rewrite a file another session may be appending to.
• Respects C8 (read-only _ dirs); follows C10 (never rm -- move to Trash).

---

When to Use

• An entry-point doc that gets loaded on every session (CLAUDE.md, README.md, status.md, a primary runbook) has grown past ~250-400 lines AND most of the weight is accumulated history (changelog tables, "Completed: YYYY-MM-DD" subsections, per-version lessons, long module catalogs).
• The user says: "my docs have grown too large", "CLAUDE.md is too big", "shrink the changelog", "split my docs", "extract history out of CLAUDE.md", "reduce context for agents", "the changelog is bloating CLAUDE.md". An explicit request like this targets whatever file or section the user names -- the ~250-400 line heuristic below is only for proactive discovery, so don't refuse to split a small file the user has pointed you at.
• Proactively, but lightly: if in the course of other work you happen to observe that an entry-point doc has grown large and is dominated by accumulated history, you may offer once, as a soft by-the-way -- "by the way, your CLAUDE.md is ~X lines, mostly changelog; I can split that out to cut per-session context whenever you like." Don't go hunting for candidates (no spontaneous repo-wide wc -l sweeps mid-task), and if the offer is declined, drop it for the session. This is a nicety, not a behavior to force.

Skip when:

• The doc is large because it has substantive current reference content (e.g., a coding-standards doc, a comprehensive API reference). Size isn't inherent waste in those cases.
• The project already extracts each shipped change into its own file or PR (e.g., uses CHANGELOG.md natively, or has a release-notes/ directory). No consolidation problem to fix.
• The user has explicitly declined a previous offer this session.

---

Core principle

Entry-point docs pay per-session context cost; companion files pay only on-demand grep cost.

When CLAUDE.md (or equivalent project-instructions file) is 600 lines and 80% of its byte weight is a changelog table that no agent reads to do current work, every cold session is paying for context nobody uses. The fix is structural, not editorial:

• Active reference (current state, open work, conventions, links) stays in the entry-point doc.
• Accumulated history (per-version changelog rows, completed-work implementation notes, accumulated lessons from prior batches) moves to a named companion file with a one-line pointer left behind.
• Both halves stay in the repo; the entry-point doc just stops carrying the history's byte weight.

Verbatim preservation of the substance is non-negotiable: this is a move-and-pointer pass, not a rewrite, and you never reword, condense, or "improve" the content as you move it. The one sanctioned exception is mechanical reference repair -- when a section moves, a cross-file pointer like "Step 4 above" becomes ambiguous and must be re-aimed at the file it now refers to (Phase 5). That is not an editorial change; it's preserving the meaning of a reference whose context moved out from under it. So: substance copied byte-for-byte, pointers fixed where the move broke them, nothing else touched. The change is large by line count but narrow in risk -- each chunk is a copy-paste with a small pointer left behind.

---

Workflow

Phase 1: Detect

If the user already named the file or section to split ("extract the lessons out of deploy.md", "the changelog in CLAUDE.md is too big"), that is the target -- go straight to it and skip the discovery scan. The size scan below is only for the proactive case, where you're looking for candidates the user hasn't pointed at; never refuse an explicitly named target just because it's small.

For proactive discovery, run the broad scan first to know what you're dealing with:

find . -name "*.md" \
  -not -path "./node_modules/*" \
  -not -path "*/_reference/*" \
  | xargs wc -l | sort -rn | head -20

Note files over ~250 lines, then classify each by the real question: is the bulk of this file cold accumulated history (written once, rarely re-read to do current work) or live reference (consulted on most sessions)? History is the candidate; live reference is not, however large. Skimming the section headers is a fast way to guess:

grep -n "^## " <large-file.md>

Header names that suggest history: "## Changelog" / "## History" / repeated "## Completed: YYYY-MM-DD" / repeated "### From the v0.X.Y batch". Header names that suggest live reference: "## Standards" / "## API" / "## Conventions" / topical sections like "## Error handling". But treat these as hints, not a checklist -- a file whose headers match neither list still gets classified by the cold-history-vs-consulted-reference judgment. When the bulk is consulted reference, leave it alone; its size is purposeful.

Also check:

• Are there sync-conflict artifacts -- *-conflict.md, *~, or host-suffixed copies like *-<hostname>.md (e.g. a OneDrive *-work-laptop.md)? Flag for deletion alongside the split (separate concern, but worth catching).
• Are there SUPERSEDED plan docs in docs/plans/ or equivalent that could move to docs/_reference/?

Phase 2: Plan

Identify each split candidate and decide its split shape. The common shapes:

Source content	Lives in	Splits to	Active file keeps
Changelog table	CLAUDE.md / top-of-project doc	docs/changelog.md	One-line pointer + Version header
"Completed: YYYY-MM-DD" subsections	status.md / project-state doc	docs/history.md	Summary table (version + date + 1-line headline) + pointer
"From the v0.X.Y batch" lessons	runbook.md	runbook-lessons.md (companion)	Pointer paragraph + "where to add new lessons" rule
Per-module deep dive	architecture.md	docs/architecture/modules.md	Brief module list + pointer
SUPERSEDED plan	docs/plans/	docs/_reference/	(move, don't split)

Write a short plan listing:

• Each file being split (current line count -> projected after)
• Each new file being created (estimated line count)
• Each cross-reference that will need updating (use grep -rn to count)
• Files to delete (sync artifacts)

Phase 3: Confirm with operator

For non-trivial splits (more than one file), use AskUserQuestion to confirm:

• Which extractions to do (let the operator pick subset)
• Naming convention for companion files (X-lessons.md vs lessons/X.md)
• Whether to also flag related cleanup (sync artifacts, SUPERSEDED docs)
• Sort order for any summary tables (version-desc vs chronological)

Do NOT confirm the full plan via AskUserQuestion -- use ExitPlanMode only if the harness is in plan mode. Otherwise just narrate the plan and ask the operator to greenlight.

Phase 4: Split each file

For each split:

1. Extract the section to the new file. Copy the substance verbatim -- the only edits permitted anywhere in this pass are the mechanical cross-file pointer repairs in Phase 5; everything else is copied unchanged. Use sed -n 'A,Bp' source.md or similar.
2. Wrap the extracted content with:
   • A title (# <Project> Changelog / # <Project> History / similar)
   • A brief intro paragraph naming the parent doc and the back-pointer
   • A top-of-file index only when the extracted content is prose -- e.g. a run of "Completed: YYYY-MM-DD" write-ups or "From the vX batch" subsections, where a small summary table (version + date + one-line headline) makes the detail below scannable. If the extracted content is already a table (a changelog), it is its own index -- don't synthesize a second table on top of it; title + intro + the table is enough.
3. Replace the extracted section in the parent file with a pointer paragraph (see "Pointer paragraph template" below).
4. Add a "Where to add new content" rule to the pointer paragraph -- so future sessions know new entries go in the companion file, not the parent. This is the load-bearing part that prevents drift.

For multi-file moves (e.g., extracting many "Completed:" subsections that are interleaved with active queue items), use a multi-pass sed pattern:

{
  sed -n '1,Ap' source.md                # active content before
  cat <<'EOF'
  ### Recently completed work
  | Version | Date | Summary |
  ... summary table ...
  EOF
  sed -n 'B,Cp' source.md                # active content middle
  sed -n 'D,$p' source.md                # active content end
} > source.md.new && mv source.md.new source.md

Phase 5: Cross-reference sweep

First, establish what actually moved. The whole sweep keys off one fact: which sections changed location. A reference is stale only if it points at content that moved; references to content that stayed put are still correct and must be left exactly as they are -- re-pointing a valid link corrupts it. Worked example: if you extract a runbook's lessons but leave its procedure in place, another doc that says "follow deploy.md Step 3" still resolves (Step 3 didn't move), so you leave it untouched; but a line inside the extracted lessons that said "Step 3 above" now lives in a different file and must be re-aimed. Same words, opposite treatment -- the deciding factor is always whether the target moved, not whether the string matches.

With that settled, two classes of reference need attention:

(a) Forward-looking references in step-by-step procedures. If a runbook says "update the CLAUDE.md changelog with X" and the changelog moved to docs/changelog.md, re-point that step. To find them, grep broadly for the moved section's name and its old parent filename, then read each hit and decide whether its target actually moved -- don't lean on one canned pattern, since the same instruction gets phrased many ways ("the changelog in CLAUDE.md", "CLAUDE.md's changelog", "see the changelog above"). For example:

# adjust the term to the section you moved; widen if hits look incomplete
grep -rni "changelog" docs/ README.md CLAUDE.md

Files that often hold these references:

• docs/runbooks/*.md (any "update these files when X happens" instructions)
• README "contributing" or "how to release" sections
• docs/standards.md or equivalent

(b) Cross-file "above" / "below" references in lessons files. When you extract a "Lessons" section out of a runbook, any line in the extracted content that says "Step N above" or "the convention table above" now spans files and is ambiguous. Re-point to the procedure file by name:

• "Step N above" -> "Step N in runbook.md"
• "the convention table above" -> "the convention table in runbook.md"

Within-file "above" / "below" references (pointing at content still in the same file) stay as-is.

(c) Historical inline-code references. Long historical paragraphs (changelog rows describing past bumps) often contain inline code like `docs/plans/foo.md` describing where a file was at the time. If you move that file:

• Update active-tense references (e.g., status.md proposals saying "design lives in [plans/foo.md]") to the new path.
• LEAVE historical-tense references (e.g., a v1.37 changelog row describing "we evaluated docs/plans/foo.md") at the old path -- they accurately describe the state at the time. Updating them would either misrepresent history or clutter the narrative with parentheticals. Use judgment.

Phase 6: Verify

This skill bundles scripts/verify_split.sh (in the skill folder) for the two checks worth automating. Run them from the project root, passing the skill's own path:

SKILL=<path-to-this-skill>   # the directory containing SKILL.md

# 1. New file line counts match the plan
wc -l <new-files>

# 2. Verbatim preservation -- confirm the moved range survived in the new file.
#    Point <orig.md> at the PRE-split version (the parent file was edited in
#    place), e.g. dump it from git first:
#        git show HEAD:CLAUDE.md > /tmp/orig.md
#    The <start>:<end> range is the section's line numbers in that original
#    (you noted these in Phase 1/4). The script reports any original line not
#    found verbatim in the new file; an empty report means a pure move. Lines
#    you intentionally re-pointed in Phase 5 are surfaced too -- confirm each
#    flagged line is a repoint you made, not an accidental drop.
"$SKILL/scripts/verify_split.sh" preserved /tmp/orig.md <start>:<end> <new.md>

# 3. Every relative markdown link resolves across the touched files/dirs
"$SKILL/scripts/verify_split.sh" links <touched-files-or-dirs>

# 4. If the project has tests, run them -- doc-only changes shouldn't break
#    anything, but a contract test on a project version-literal would catch
#    drift if you also bumped versions.
<project test command>   # e.g. npm test, pytest, go test -- whatever the project uses

Both subcommands exit non-zero on a problem (a broken link, or an original line missing from the new file), so they double as a gate in an autonomous loop. If the script is somehow unavailable, the manual equivalents are grep -F "<distinctive phrase>" <new-file> for (2) and eyeballing grep -rn "\]\(.*\.md\)" <touched-files> for (3).

Spot-check the rendered output: open one of the modified files in a markdown previewer and confirm the pointer paragraph reads cleanly and the summary table renders.

Phase 7: Record the change

For projects that version their entry-point doc (e.g., a CLAUDE.md carrying a **Version:** X.Y header tied to a changelog table):

1. Bump the entry-point doc's Version + Last Updated headers.
2. Add a new row at the top of the (now-moved) changelog table describing the reorg: which files moved, why (note the per-session context savings), and what stayed verbatim. Footer the row with "Doc-only change; no source code, test, or smoke changes; tests still N/N green" if applicable.

For projects without versioning conventions, a single commit message that captures the same information is sufficient.

Do not bundle the reorg with unrelated content changes. The whole point is the diff is "verbatim move + pointer + tree update" -- small per-line risk even at large line counts. Bundling editorial changes muddies the review.

---

Pointer paragraph template

The pointer paragraph that REPLACES the extracted section should be short, self-contained, and include the "where to add new content" rule. Generic template:

## <Section Name>

The <full <X> table | full <Y> detail | accumulated <Z>> lives at
[<path>](<path>). <One-sentence note about what's there.>

**Where to add new content:** new <entries / subsections / lessons> go
in [<path>](<path>), not here. <One-sentence rationale: this file is the
<procedure / current-state / index>; the companion file is the durable
history.>

Concrete examples seen in practice:

## Changelog

The full v1.0 -> current changelog table lives at [docs/changelog.md](docs/changelog.md).
Bump the `Version` header at the top of this file and add a row at the top of
that table on every CLAUDE.md content change.

## Gotchas / Lessons Learned

Accumulated lessons from prior tool-addition batches -- architectural
patterns, per-version application notes, Graph API quirks, smoke testing
patterns, MCP integration tips -- live in
[extension-workflow-lessons.md](extension-workflow-lessons.md). Load that
file when planning a new batch so prior lessons inform the design.

**Where to add new lessons:** if a new batch produces a cross-version
lesson worth capturing, append it to
[extension-workflow-lessons.md](extension-workflow-lessons.md) -- not to
this runbook directly. The runbook is the procedure; the lessons file is
the durable history.

---

Companion file naming

Two common patterns:

Pattern	When to use	Example
X.md + X-lessons.md (companion in same dir)	Procedure files that have a sister lessons file	extension-workflow.md + extension-workflow-lessons.md
Dedicated rollup file (changelog.md, history.md)	Cross-cutting history that doesn't belong to one runbook	docs/changelog.md, docs/history.md

Avoid:

• X-old.md / X-archive.md -- implies the content is stale, but it isn't (the procedure stays current; only its presentation split).
• X.md.bak -- looks like a backup artifact.
• Deep nesting (docs/runbooks/lessons/extension-workflow.md) -- adds navigation friction for marginal organizational gain.

---

Common pitfalls

1. Sort order drift in summary tables. When you extract "Completed:" subsections into a history file and put a summary table in the active file, decide once whether the table is version-descending or chronological-ascending, and apply the same order to both the active-file table and the history-file index table. Mixed orders within a single table look careless.

2. Forgetting the "where to add new" rule. Without an explicit rule in the pointer paragraph, the next session adds new entries to the parent file (where the old content used to live) instead of the companion. Two bumps later the split has reverted by accident.

3. Cross-file "above" refs. Lessons files often say "Step N above" or "the table above" -- these become ambiguous once the file is split. Phase 5 (b) handles this; don't skip it.

4. Step-procedure references in OTHER runbooks. If runbook A says "update CLAUDE.md changelog per step 3 of runbook B" and the changelog has moved out of CLAUDE.md, both A and B need updating. Grep widely.

5. Verbatim content drift. Resist the temptation to "improve the wording while you're here." Make the split a verbatim move. Editorial changes go in a separate commit so the diff stays reviewable.

6. Empty parent directories. If you move the last file out of (e.g.) docs/plans/, the directory becomes empty. Decide: keep it (if the purpose-description in the doc tree still applies and new files of that type will land there) or remove it (clutter). Default: keep, since git doesn't track empty dirs anyway and CLAUDE.md / equivalent tree documentation usually still references the directory's purpose.

7. Sync conflict artifacts. OneDrive / Dropbox / iCloud often leave duplicate files -- *-conflict.md, or host-suffixed copies like *-<hostname>.md (e.g. a OneDrive *-work-laptop.md) -- that are STALE copies of the live file. While scanning markdown sizes, flag any you spot with diff + mtime comparison; delete with operator confirmation. Not strictly part of this skill but a frequent co-occurrence with "my docs feel cluttered."

---

Checklist (end-of-skill)

• Every split file lives in its new location (verify with wc -l)
• Moved sections survived verbatim (verify_split.sh preserved ...; any flagged line is an intended Phase-5 repoint, not a drop)
• Every pointer paragraph includes a "where to add new content" rule
• All relative markdown links resolve (verify_split.sh links ...)
• All cross-file "above"/"below" refs in lessons files re-pointed
• All step-by-step procedures in OTHER runbooks updated to name new locations
• Summary tables (if any) are in consistent order across active + history files
• Sync conflict artifacts / SUPERSEDED files cleaned up alongside (with operator confirmation)
• Tests still pass (if the project has them)
• CLAUDE.md / equivalent tree documentation updated to reflect new files
• If the project versions its entry-point doc: Version + Last Updated bumped, new row at top of changelog table

---

Notes for autonomous loops

If the skill is being run via /loop or similar autonomous mechanism:

• Always confirm split scope with the operator before Phase 4 -- verbatim content moves are low-risk but file deletions and SUPERSEDED moves are not. Default to asking.
• Stop after Phase 6 (verify) if anything looks off; do not proceed to Phase 7 (record) until the operator has reviewed. Use scripts/verify_split.sh as the gate: a non-zero exit (a broken link, or an original line missing from the new file that you can't account for as an intended repoint) means stop and surface it rather than recording the change.
• Do not chain into a "now reorg the next project's docs" loop without explicit operator request. Each project's doc structure has its own intentional shape; the skill is a tool, not a policy.