kernel-split

Announce at start: "I'm using the kernel-split skill to partition <target-skill.md>."

Partition any large skill.md into a resident kernel and an on-demand reference, using the keyword-scoring rubric. Prove the split with a permanent context-budget regression test.

When to Use

• A skill's wc -c exceeds the byte budget (>6 KB) and it's causing context pressure in production sessions
• The doctor reports the skill is oversized or failing context-budget regression tests
• A skill has a large reference section that is rarely needed at trigger time

NOT when: the skill is appropriately sized — splitting for its own sake adds maintenance overhead without benefit.

Reference index

Load reference.md selectively. Do not load it for a routine operation.

Prerequisites

Before partitioning, verify:

1. tools/section-loader.sh exists and is executable.
2. tools/skill-partitioner exists and is executable.
3. The target skill has at least 3 behavioral bats tests. If fewer than 3: add tests first, commit them, then proceed.
4. Record the target skill's current byte count -- this is the before baseline.

wc -c <path/to/skill.md>

Workflow

Step 1 -- Propose the split

tools/skill-partitioner propose <path/to/skill.md>

The tool prints per-section scores and writes three files to a temp dir:

• proposed-kernel.md -- sections scoring >= +2
• proposed-reference.md -- sections scoring <= -1
• ambiguous-items.md -- sections scoring -1 to +1 (human decision required)

Review the proposal. Move ambiguous sections manually into the correct proposed file before proceeding. Read reference.md under Ambiguous section decisions for guidance.

Step 2 -- Apply the split

tools/skill-partitioner apply <path/to/skill.md> <proposed-kernel.md> <proposed-reference.md>

This overwrites skill.md with the kernel content (routing table prepended) and writes reference.md alongside it.

Verify the routing table rows match the reference headings. Fill in the Need column with plain-language descriptions.

Step 3 -- Wire the section-loader call

Embed this origin-bound loader. Source references use their checkout loader; installed references use managed tooling. Replace <installed-name> with _skill_dest_name output (usually the first /sp-* trigger without /, such as sp-debate). Installed precedence is .claude, .codex, .agents: deploy.sh always refreshes .claude, while --skip-augment can preserve stale optional copies. The outer four-backtick fence renders the inner block:

<!-- kernel-split-reference-loader:start -->
```bash
_ks_ref=""
_ks_loader=""
for _candidate in \
  "$HOME/.claude/skills/<installed-name>/reference.md" \
  "$HOME/.codex/skills/<installed-name>/reference.md" \
  "$HOME/.agents/skills/<installed-name>/reference.md"
do
  if [ -r "$_candidate" ]; then _ks_ref="$_candidate"; break; fi
done
if [ -n "$_ks_ref" ]; then
  _ks_loader="$HOME/.codex/superpowers-plus/tools/section-loader.sh"
else
  _project_root="$(git rev-parse --show-toplevel 2>/dev/null || true)"
  _source_dir="$_project_root/skills/<domain>/<skill-name>"
  if [ -n "$_project_root" ] && [ -r "$_source_dir/skill.md" ] && \
     [ -r "$_source_dir/reference.md" ] && \
     [ -r "$_project_root/tools/section-loader.sh" ]; then
    _ks_ref="$_source_dir/reference.md"
    _ks_loader="$_project_root/tools/section-loader.sh"
  fi
fi
[ -r "$_ks_ref" ] || { printf 'reference missing\n' >&2; exit 1; }
[ -r "$_ks_loader" ] || { printf 'section-loader missing\n' >&2; exit 1; }
# Replace <section heading> below with one of the exact strings from
# the Reference index table above before running.
_section='<section heading>'
bash "$_ks_loader" "$_ks_ref" "$_section" \
  || { printf 'section not found: %s\n' "$_section" >&2; exit 1; }
```
<!-- kernel-split-reference-loader:end -->

Step 4 -- Add a context-budget regression test

Add an entry to tests/engineering/kernel-split-context.bats:

@test "SKILLNAME kernel stays within byte budget" {
  REPO_ROOT="$(cd "$BATS_TEST_DIRNAME/../.." && pwd -P)"
  SKILL="$REPO_ROOT/skills/DOMAIN/SKILLNAME/skill.md"
  BEFORE_BYTES=99999  # replace with actual pre-split byte count
  BUDGET_RATIO_PERCENT=60
  MAX_BYTES=$(( BEFORE_BYTES * BUDGET_RATIO_PERCENT / 100 ))
  current="$(wc -c < "$SKILL" | tr -d ' ')"
  [ "$current" -le "$MAX_BYTES" ]
}

Step 5 -- Verify

bats tests/engineering/kernel-split.bats
bats tests/engineering/kernel-split-context.bats

Verify: kernel byte count <= 60% of before, and the full behavioral test suite for the target skill passes.

Safety invariants

• Smallest safe, not smallest. Safety-critical content (hard gates, NEVER rules, scope checks) stays in the kernel even if it is long.
• Never move YAML frontmatter. It always stays in the kernel (scored +999).
• Never silently omit preflight blocks. A section containing a mandatory pre-write checklist must either stay in the kernel, or be listed in the routing table with an explicit "load before every write" note so agents always fetch it before the associated operation.
• The section-loader must fail loudly (non-zero exit) when a heading is missing -- it never falls back to whole-file.
• Bind loader to reference origin. A validated source tuple uses its checkout loader; installed references use only ~/.codex/superpowers-plus/tools/section-loader.sh.
• Use installed destination names. A source skill named debate with trigger /sp-debate resolves installed references under sp-debate/.
• The budget test is permanent -- it fails if the kernel grows past the pinned ratio. Do not delete it.

Failure Modes

Companion tools

• tools/section-loader.sh -- section-precise reference reader
• tools/skill-partitioner -- propose and apply subcommands
• tests/engineering/kernel-split-context.bats -- fleet-wide budget regression suite