Agent Session Compactions — Full Lifecycle Skill

What This System Is

Agent session compactions are structured summaries of Claude Code agent work sessions. They capture:

• Overarching intent — the big-picture UX goal of the session
• Target UX intent — the specific testable UX promise delivered
• Success measure — how to verify the work achieved its goal
• UX stories brought to reality — conversational descriptions of what changed
• Incomplete items — work that was started but not finished (with status/priority)
• Principles — "When X then Y" statements extracted from the session
• How to consume — step-by-step instructions to verify/use the work

This is for AGENT (Claude Code) session compactions — records of what an agent did across a work session, for a later session (agent or person) to pick up from. It is a different thing from a transcript of a coaching or support conversation with an end user, if your project has one of those — don't conflate the two if both exist in your project.

Where compactions live

Default: a local file, no server required. Run alignment-harness records compactions — it prints the folder (creating it if needed) and that is where a compaction for this session goes, as <sessionId>.md (or <shortId>.md — pick one and be consistent within a project) with YAML frontmatter for the structured fields and the narrative in the body. This is the Tier 1 store every install gets by default; nothing about the schema below is specific to any one company's product, only where it used to be written was.

Optional: a hosted store. If you run your own backend and want compactions in a database with a search index and an admin UI (one reference setup does this — a Mongoose model, an Express API, a React admin page), that's a project-specific integration you build and wire in during /alignment-harness:harness-setup. Nothing here assumes it exists. If you have one, keep using its API in place of the local file write below; the field shape is identical either way.

When to Create a Compaction

Create a compaction when a session involved:

• 3+ meaningful file changes (not just formatting)
• 1+ new patterns, principles, or architectural decisions
• Work on a feature that spans multiple sessions
• Debugging that uncovered a non-obvious root cause
• Any incomplete work that a future agent needs to pick up

Do NOT compact trivial sessions (single typo fix, config change, etc.).

UX Criticality and Pre-Execution Reflection

Before composing the compaction, run the ux-criticality-measurement skill if the work was user-facing (if you don't have that skill installed, just reason it through: how visible is this to a real user, how bad is it if it's wrong). If the criticality is high, also think through ux-pre-execution-reflection (or the skill of that name, if installed) and include both as uxCriticality and preExecutionReflection fields below.

How to Create a Compaction

Default: write the local file

DIR="$(alignment-harness records compactions)"
SESSION_ID="${CLAUDE_CODE_SESSION_ID:-$(alignment-harness session-id)}"
cat > "$DIR/${SESSION_ID}.md" <<'EOF'
---
sessionId: <unique-session-identifier>
repo: <this project's name>
title: Human-readable title describing UX impact
subtitle: One-line context
overarchingIntentTitle: The big-picture goal
overarchingIntentDescription: "When {constraints} we {testable outcome}"
successMeasure: How to verify this work achieved its goal
targetUxIntentTitle: Specific UX promise
targetUxIntentDescription: "When {user does X} they {experience Y}"
howToConsumeThisWorkProduct: |
  Step 1: go to <path or URL>
  Step 2: click X
  Step 3: verify Y
uxStoriesBroughtToReality:
  - "When a person does X, they now experience Y instead of Z"
incompleteItems:
  - title: Wire up X
    content: Description of remaining work
    status: pending
    priority: 80
principles:
  - title: Short principle name
    content: Detailed explanation
    scope: "When {X constraint} then {Y behavior}"
    status: pending
    priority: 70
    leverageScore: 85
    tags: [admin, ux]
agentReasoning:
  gestaltObservation: What would it take to observe the gestalt and deduce the actual clear intent the person would instantly understand?
  alignmentFailures: What failures of alignment with existing code intent were surfaced? Dependencies created unnecessarily? Breakage from assumptions?
  sanityCheckSteps: Simple sanity check steps to verify the work — articulated so a human can check without reading code
  surfacingQuestion: The question that, if asked of yourself, surfaces signal over noise of this work product
  surfacingAnswer: The honest answer to that question
uxCriticality:
  criticalityScore: 6.5
  isUserFacing: true
  dimensions: { silentFailureDegradation: 7, deliveryChainLength: 5, firstImpressionWeight: 8, harmIfWrong: 6 }
  reasoning: Explain why each dimension scored the way it did
  reflectionRequired: true
  reflectionLevel: full
preExecutionReflection:
  targetIntent: "When {person} does {action}, they experience {outcome}"
  deliveryChain:
    - { layer: Layer Name, servesOrFights: serves, note: Why this serves/fights the intent }
  failureModes: [Silent failure mode 1, Silent failure mode 2]
  uxRequirements: [Must X, Must Y]
  harmPotential: How this could cause more harm than good
  riskyAssumption: The assumption most likely to be wrong
  metaQuestion: The question I should be asking
  metaAnswer: The answer to that question
tags: [admin, compactions, discoverability]
---

Full markdown content of the compaction — the narrative version of everything above,
readable on its own without parsing the frontmatter.
EOF
echo "Compaction saved: $DIR/${SESSION_ID}.md"

Print the path after writing it — that's how the person finds it (there's no admin link to print unless you've wired the optional hosted store below).

If alignment-harness records compactions cannot be run yet (Tier 1 local store not set up), don't silently drop the compaction: keep it in the session, or write it to a plain file in the current working directory and print that path, and say plainly that persistent storage isn't configured yet.

Optional: hosted store

If your project has its own backend and admin UI for these records, POST the same fields to whatever endpoint you built for it, using this schema as the contract. Print whatever confirmation link your own admin UI supports.

Agent Self-Reasoning (do this before composing)

Before generating any compaction fields, reason through and populate these 5 agentReasoning fields:

1. gestaltObservation — What would it take to observe the gestalt and deduce the actual clear intent in nested UX terms that the person would instantly understand, so they could instantly know your sense of their intent and whether it was aligned?
2. alignmentFailures — What failures of alignment with existing code intent were surfaced? Where did you create dependencies that didn't need to exist, or breakage from making assumptions?
3. sanityCheckSteps — The simplest sanity check steps to actually verify the work, articulated so a human can perform them without reading code.
4. surfacingQuestion — The question that, if asked of yourself, would surface signal over noise of this actual work product.
5. surfacingAnswer — The honest answer to that question.

These are not filler — they're the agent's structured self-reflection: honest assessment of alignment gaps and verification steps, not a rubber stamp.

Required Fields

• sessionId — unique identifier (use the Claude Code session ID or generate one)
• the narrative body — full markdown content

Strongly Recommended Fields

• title, overarchingIntentTitle, targetUxIntentTitle — make it findable
• agentReasoning — structured self-reflection (5 fields above). Generate BEFORE composing other fields.
• principles[] — first-order concerns for future agents
• incompleteItems[] — so nothing gets lost
• howToConsumeThisWorkProduct — so humans can verify

How to Find Compactions

Default (local store): grep the compactions folder — grep -ril "your query" "$(alignment-harness records compactions)" — plus git log --oneline --all --grep="your query" and this project's other Claude Code sessions (grep -l "your query" ~/.claude/projects/*/*.jsonl). Say plainly when nothing turns up rather than guessing.

If institutional-memory search is set up (see /alignment-harness:harness-setup), use it instead — it will search compactions along with everything else it indexes.

If you built a hosted store, query its own list/search endpoint or admin UI.

How to Act on Compaction Findings

Incomplete Items

1. Check status — pending items need triage, approved items need execution
2. Create a task or start a session to complete the work
3. Update status to completed when done

Principles (FIRST-ORDER CONCERNS)

Principles are "When X then Y" statements that encode hard-won learnings. They should be:

• Stored with full context — not just the rule, but WHY it exists
• Tagged for discoverability — use tags like ["ux", "admin", "security", "performance"]
• Scored for leverage — leverageScore 0-100, where 100 = affects every session
• Promoted when high-leverage — a principle with leverageScore >= 70 is a candidate to add to this project's own CLAUDE.md or intent tracking, if it's genuinely universal to the project rather than specific to one session

UX Stories

These are human-readable descriptions of what changed. Use them in:

• Commit messages
• PR descriptions
• Changelogs

Discoverability Checklist

When creating or reviewing compactions, verify:

• Title clearly describes UX impact (not just technical change)
• Principles have scope field in "When X then Y" format
• Principles have leverageScore assigned
• Incomplete items have priority assigned
• Tags include project name and domain keywords
• howToConsumeThisWorkProduct has actionable steps

Cross-References

• Intent lifecycle: intent-lifecycle skill, if installed
• Discoverability audit: discoverability-audit-learnings-findable-by-agents skill, if installed
• If your project has a separate system for end-user (not agent) session summaries, keep the two stores distinct — this skill is for agent work sessions only.