Comprehensive diagnostic of the Session Ecosystem — 16 categories across 5 domains with composite health scoring, trend tracking, patch suggestions, and interactive finding-by-finding walkthrough. Covers session lifecycle hooks, state persistence, compaction resilience layers, cross-session safety, and integration configuration.
Document Version: 1.0 Last Updated: 2026-02-23 Status: ACTIVE
<!-- prettier-ignore-end -->Deep diagnostic of the entire Session Ecosystem — lifecycle skills
(session-begin, session-end), hooks
(session-start.js, commit-tracker.js, pre-compaction-save.js,
compact-restore.js), state files (handoff.json,
commit-log.jsonl, session-notes.json), and the compaction resilience
system. Produces per-category scores, a composite health grade (A-F), trend
tracking across runs, and an interactive walkthrough with patch suggestions.
Invocation: /session-ecosystem-audit
When to use: When you want to understand the overall health of the session
management system, identify gaps in lifecycle coverage, validate compaction
resilience layers, check cross-session safety invariants, or verify hook
registration alignment. Complementary with /hook-ecosystem-audit (that skill
audits ALL hooks; this skill audits the SESSION SYSTEM specifically).
/session-ecosystem-audit.claude/tmp/session-audit-progress.json if it exists and is < 2 hours old.
Never re-present findings that were already decided./add-debt if the project supports itAudits are long-running interactive workflows vulnerable to context compaction. To survive compaction, save progress after every decision and check for existing progress on startup.
Path: .claude/tmp/session-audit-progress.json
Schema:
{
"auditTimestamp": "ISO timestamp of audit run",
"score": 85,
"grade": "B",
"totalFindings": 42,
"currentFindingIndex": 8,
"decisions": [
{
"findingIndex": 1,
"category": "session_begin_completeness",
"message": "finding description",
"decision": "skip",
"note": "reason"
}
],
"fixesApplied": ["description of fix"],
"findingsData": []
}
.claude/tmp/session-audit-progress.json exists and is < 2 hours
oldcurrentFindingIndexAfter each AskUserQuestion response, immediately save progress:
currentFindingIndex to the next findingdecisions arrayfixesApplied.claude/tmp/session-audit-progress.jsonAfter the summary is presented, delete the progress file (audit is complete).
node .claude/skills/session-ecosystem-audit/scripts/run-session-ecosystem-audit.js
Parse the v2 JSON output from stdout (progress goes to stderr).
Create a session decision log file:
.claude/tmp/session-audit-session-{YYYY-MM-DD-HHMM}.jsonl.claude/tmp/ directory if it doesn't existSave initial progress state to .claude/tmp/session-audit-progress.json with
currentFindingIndex: 0, the full findings data, score, and grade.
Present a compact header with composite grade and domain breakdown:
Session Ecosystem Health: {grade} ({score}/100) | Trend: {sparkline} ({delta})
{errors} errors · {warnings} warnings · {info} info | {patches} patch suggestions
┌──────────────────────────────────┬───────┬──────────┬──────────────┐
│ Category │ Score │ Rating │ Trend │
├──────────────────────────────────┼───────┼──────────┼──────────────┤
│ D1: Session Lifecycle Mgmt │ │ │ │
│ Session Begin Completeness │ {s} │ {rating} │ {trend} │
│ Session End Completeness │ {s} │ {rating} │ {trend} │
│ Session Counter Accuracy │ {s} │ {rating} │ {trend} │
│ Session Documentation Freshness│ {s} │ {rating} │ {trend} │
├──────────────────────────────────┼───────┼──────────┼──────────────┤
│ D2: State Persistence & Handoff │ │ │ │
│ Handoff File Schema │ {s} │ {rating} │ {trend} │
│ Commit Log Integrity │ {s} │ {rating} │ {trend} │
│ Task State File Health │ {s} │ {rating} │ {trend} │
│ Session Notes Quality │ {s} │ {rating} │ {trend} │
├──────────────────────────────────┼───────┼──────────┼──────────────┤
│ D3: Compaction Resilience │ │ │ │
│ Layer A: Commit Tracker │ {s} │ {rating} │ {trend} │
│ Layer C: Pre-Compaction Save │ {s} │ {rating} │ {trend} │
│ Layer D: Gap Detection │ {s} │ {rating} │ {trend} │
│ Restore Output Quality │ {s} │ {rating} │ {trend} │
├──────────────────────────────────┼───────┼──────────┼──────────────┤
│ D4: Cross-Session Safety │ │ │ │
│ Begin/End Balance │ {s} │ {rating} │ {trend} │
│ Multi-Session Validation │ {s} │ {rating} │ {trend} │
├──────────────────────────────────┼───────┼──────────┼──────────────┤
│ D5: Integration & Configuration │ │ │ │
│ Hook Registration Alignment │ {s} │ {rating} │ {trend} │
│ State File Management │ {s} │ {rating} │ {trend} │
└──────────────────────────────────┴───────┴──────────┴──────────────┘
Rating badges: good = "Good", average = "Avg", poor = "Poor"
Then say: "Found N findings to review. Walking through each one (impact-weighted)..."
Sort all findings by impactScore descending (highest impact first).
For each finding, present a context card:
━━━ Finding {n}/{total} ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
{SEVERITY} | {domainLabel}: {categoryLabel} | Impact: {impactScore}/100
{message}
Evidence:
{details}
If the finding has patchable: true, also show:
Patch Available:
Target: {patch.target}
Action: {patch.description}
Preview:
{patch.preview or patch.content}
Then use AskUserQuestion with options based on severity:
ERROR findings:
WARNING findings:
INFO findings:
Fix Now:
Defer:
Suppress:
After all findings are reviewed, present the summary:
━━━ Audit Summary ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Composite: {grade} ({score}/100) | {trend}
Decisions:
Fixed: {count} findings
Deferred: {count} findings
Skipped: {count} findings
Suppressed: {count} findings
Patches Applied: {count}/{total patchable}
Top 3 Impact Areas:
1. {category} — {brief description}
2. {category} — {brief description}
3. {category} — {brief description}
Next Steps:
- {actionable recommendation based on worst categories}
- {actionable recommendation}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
If the state file has previous entries, show improvement/regression:
━━━ Trend Report ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Composite Trend: {sparkline} {direction} ({delta})
Improving:
{category}: {before} → {after} (+{delta})
Declining:
{category}: {before} → {after} ({delta})
Stable:
{category}: {score} (no change)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
| Category | What It Checks |
|---|---|
| Session Begin Completeness | All /session-begin sections backed by scripts/npm commands that exist |
| Session End Completeness | All /session-end sections backed by scripts/npm commands that exist |
| Session Counter Accuracy | SESSION_CONTEXT.md counter matches commit-log.jsonl session numbers |
| Session Documentation Freshness | SESSION_CONTEXT.md within limits: line count, staleness, section quality |
| Category | What It Checks |
|---|---|
| Handoff File Schema | handoff.json has all 11 required fields + gitState sub-fields |
| Commit Log Integrity | commit-log.jsonl entries valid JSON, required fields, file size managed |
| Task State File Health | task-*.state.json files valid JSON, no orphaned completed tasks |
| Session Notes Quality | session-notes.json valid, entries have timestamps/text, no stale entries |
| Category | What It Checks |
|---|---|
| Layer A: Commit Tracker | commit-tracker.js registered, Bash matcher, file exists, content OK |
| Layer C: Pre-Compaction Save | pre-compaction-save.js registered, captures key state fields |
| Layer D: Gap Detection | check-session-gaps.js exists, npm script, reads commit-log + context |
| Restore Output Quality | compact-restore.js registered with "compact" matcher, reads handoff |
| Category | What It Checks |
|---|---|
| Begin/End Balance | Session begin count matches end count in .session-state.json |
| Multi-Session Validation | session-start.js has validation logic, SESSION_CONTEXT.md current |
| Category | What It Checks |
|---|---|
| Hook Registration Alignment | Core session hooks registered in settings.json + files exist |
| State File Management | .claude/state/ gitignored, no oversized files, tmp cleanup |
Internal benchmarks are defined in scripts/lib/benchmarks.js. Each category
scores 0-100 with ratings: good (90+), average (70-89), poor (<70). The
composite grade uses weighted average across all 16 categories with domain