Enrich All Compactions — Single Command Relaunch

Each of the steps in this pipeline has a specific function — skip them and the resulting work product ends up unreliable. That's the reason this pipeline enforces the full sequence rather than letting an agent shortcut it.

What This Does

Finds every session compaction that hasn't been fully enriched yet, then dispatches parallel subagents (20 at a time) to run the /compactions-enrich skill pipeline on each one. Each subagent invokes 4 skills in sequence, writes its results back incrementally after each step, and produces a full audit checklist.

Never call a paid API directly for this work. Everything here runs as ordinary Claude Code subagents inside your own session — never a separate call to the Anthropic API key, and never a silent substitution of a cheaper model than the one a step actually calls for (see "What didn't work" below).

Where compactions live

Default: the local compaction store — the folder alignment-harness records compactions prints, one <shortId>.md per compaction with YAML frontmatter for structured fields (see /agentic-session-compactions for the exact schema). This is what a fresh install has.

If you've built a database-backed compaction store of your own (MongoDB, Postgres, whatever), the same steps apply — just read/write records there instead of local files, with your own connection details. That's optional, advanced infrastructure this skill doesn't require.

Step 1: Find unenriched compactions

Local store (default):

DIR="$(alignment-harness records compactions)"
grep -rL "leverageScore:" "$DIR"/*.md 2>/dev/null | while read -r f; do
  title=$(grep -m1 '^title:' "$f" | sed 's/^title: *//')
  echo "$(basename "$f" .md) | ${title:-untitled} | $(wc -c < "$f")ch"
done

This lists every compaction file with no leverageScore field in its frontmatter yet — the same test as "hasn't been enriched."

Database-backed store (if you have one): query for records missing a leverage score, the same shape as the local check above, adapted to your schema.

Step 2: Dispatch agents in batches of 20

For each compaction, dispatch a background subagent with this prompt template:

Enrich compaction {ID} "{TITLE}".

Read skill at ~/.claude/skills/compactions-enrich/SKILL.md FIRST (or the plugin's bundled
copy, if you're running from the plugin install — check both).

INVOKE /reflect, /align, /compact-agentic-session, /incomplete-tasks-get-from-session via Skill tool.

WRITE RESULTS IMMEDIATELY after each step — to the compaction's own file in
`alignment-harness records compactions` (or the database record, if that's your store).

UX-first on all items — every object written must lead with who is affected, what they experience now, what they should experience, and what constrains it.

Assign phase + category.
Store full /align markdown in reflectionOnScope — this is the MOST COMMONLY SKIPPED field.

Content ({CONTENT_LENGTH}ch).

Dispatch all 20 in a single message with run_in_background: true.

Step 3: Monitor and verify

After each batch completes, run an audit:

DIR="$(alignment-harness records compactions)"
total=$(ls "$DIR"/*.md 2>/dev/null | wc -l)
withLev=$(grep -l "leverageScore:" "$DIR"/*.md 2>/dev/null | wc -l)
withRefl=$(grep -l "reflectionOnScope:" "$DIR"/*.md 2>/dev/null | wc -l)
remaining=$(grep -rL "leverageScore:" "$DIR"/*.md 2>/dev/null | wc -l)
echo "$total total | $withLev leverage | $withRefl reflection | $remaining remaining"

(Adapt to a real query if you're on a database-backed store.)

Step 4: If an agent fails — stop, fix, retry

Failure patterns discovered running this at real volume, and their fixes:

1. Template literal escaping — agents using inline scripts with backticks inside backticks. Fix: write any helper script to a real file in the project (not inline in a shell one-liner) and run it from there.

2. require() / read path from /tmp — a script written to /tmp/ can't resolve relative requires or the records folder the same way a script in the project can. Fix: write scripts inside the project, run with cd <project> && node tmp-enrich-<id>.js.

3. reflectionOnScope skipped — a majority of agents in early runs skipped writing this field. Fix: the skill file has an explicit code block for the write with a warning that this is the most commonly skipped field.

4. Context exhaustion — agents using ~100K+ tokens complete all 4 skills; agents under ~75K run out before the last step. Fix: incremental writes after each step so partial enrichment is preserved even if the agent runs out of context.

5. Rate limits — dispatching 20 agents simultaneously can hit your own usage limits. Fix: if agents return a limit message, wait for the reset window and redispatch.

6. Schema validation errors from a deprecated batch method — if you inherit existing compactions that were enriched by an API-key batch script instead of a real subagent, some may carry invalid enum values. Fix: don't use API-key batch scripts at all; if you find invalid values, fix them directly in the record before retrying enrichment. (See "repairing already-mistagged records" below if you're bringing in a large existing store.)

What Each Enriched Compaction Gets

Every compaction that passes through the pipeline gets:

• reflectionOnScope — full /reflect + /align markdown document (5,000-10,000 chars typical)
• alignmentNote — synthesis of intent, gap, leverage analysis
• leverageScore — 0-100 with tier reasoning
• overarchingIntentTitle + Description — top-level goal this work serves
• targetUxIntentTitle + Description — testable UX promise
• scopeDeclaration — intent, certainty, decomposed UX outcomes, boundary, assumptions
• agentReasoning — 5-field structured self-reflection
• uxCriticality — score + 4 dimension scores + reasoning
• preExecutionReflection — delivery chain, failure modes, UX requirements
• successMeasure — 1-2 actual KPIs
• howToConsumeThisWorkProduct — conversational framing for how the person should read this
• roadmapPhaseId — matched to closest roadmap phase, if you track one
• categoryIds — matched to parent category
• incompleteItems — new UX-first items extracted from reflect/align gap analysis
• enrichmentHistory — logged with model, timestamp, all fields touched — and never silently tagged with a cheaper model than what actually ran

Learnings from running this at real volume

What worked

• Incremental writes after each step prevent data loss
• 20 agents in parallel is a reasonable concurrency ceiling for a single Claude Code session
• The /compactions-enrich skill file with mandatory Skill tool invocations produces consistently high quality
• UX-first writing rule produces items the person can read without opening code
• Phase and category assignment adds navigability if you have an admin view over the store

What didn't work

• Scripts that call the Anthropic API directly (real money spent outside the person's own subscription, without their say-so — never do this)
• Writing helper scripts to /tmp (path resolution breaks)
• Batching all writes to a final step (agents run out of context before reaching it)
• The "efficiency" bias that makes agents skip skill invocations and write output themselves instead
• Silently substituting a cheaper/faster model when a specific one was called for, and not saying so

Keeping this from silently stopping

This pipeline is easy to build once and then forget to run — it has no value sitting idle while the compaction store grows behind it. Treat it as a sweep you check on a cadence (weekly is a reasonable default), not a one-time run:

• Before starting other enrichment-adjacent work, check alignment-harness records compactions for how many records are missing a leverageScore, and how long it's been since any record's enrichmentHistory was last touched.
• If it's been longer than your own chosen interval (or the person hasn't set one, ask what cadence they want — weekly is a fair default), offer to run a fresh sweep before doing anything else.
• Never report "nothing to enrich" without actually checking — an empty result and "never checked" look identical to the person unless you say which one it was.

Repairing already-mistagged records

If you're bringing in an existing store where some records were enriched by a deprecated cheap-model batch method (see failure pattern 6 above), don't just re-run the whole pipeline blindly — first find the ones tagged with that method specifically (grep enrichmentHistory for the deprecated tag) and re-run only those, so you're not burning a full sweep to fix a targeted problem.

Compacting sessions that were never compacted at all

If the sessions are too big, the answer isn't a "digest." The answer is to decompose the extraction process itself. Have agents mine the JSONL in chunks if you have to, but they must consume the raw source, not a sanitized rewrite. This came out of an oracle query run while building this pipeline, and it's worth keeping as a design principle regardless of whether you have the same oracle.

Never pre-digest or summarize transcripts before giving them to agents. A digest is a lossy summary that strips verbatim quotes and nuance. Agents must read the RAW transcript source.

Never skip skill invocations (/reflect, /align, /compact-agentic-session). Compaction is signal extraction, not summarization — a "lightweight" version that skips the real skills produces a worse record than not compacting at all.

The correct approach: chunk-based reading + full skills + incremental writes

Each agent:

1. Reads the raw transcript in chunks — first 100 lines, then last 100 lines, then (if budget allows) middle sections. Multiple Read tool calls, each on the actual raw transcript.
2. Invokes /reflect on what it actually read — the skill runs on real evidence, not a sanitized rewrite.
3. Writes the reflect output immediately (incremental write — prevents data loss).
4. Invokes /align on what it read — derives nested intent from the person's own words.
5. Writes the align output immediately.
6. Invokes /compact-agentic-session for structured field population.
7. Writes structured fields immediately.
8. Creates the compaction record with all fields populated.

If the agent runs out of context after step 3 or 5: the partial data is already saved from incremental writes. A follow-up enrichment agent can complete the remaining fields on the partially-created record.

Token budget reality

• Subagent budgets: ~60-100K tokens depending on rate limit pressure
• Reading 200 lines of a transcript: ~15-25K tokens
• Each skill invocation: ~10-20K tokens (less without the full project-conventions context)
• Each write: ~5K tokens
• Total minimum for the full pipeline: ~55-80K tokens

Success criteria

• Sessions under ~150KB: a single agent can complete the full pipeline
• Sessions 150KB-500KB: an agent may complete if it gets 80K+ token budget, otherwise partial data saved
• Sessions over 500KB: likely partial — rely on incremental writes + follow-up enrichment

What was tried and failed

1. Single agent, full skills, no incremental writes — died at the write step nearly every time
2. Pre-digest by the orchestrator before handing to subagents — produces a lossy summary dressed up as source material; rejected
3. A "lightweight" compaction without the real skills — produces a worse record than skipping compaction entirely; rejected
4. Incremental writes after each skill — works for enriching existing compactions, partially works for creating new ones from scratch