Session Log Fixer

Session Log Fixer

Fix session protocol validation failures using deterministic validation feedback from Job Summary.

Quick Start

Just tell me what failed:

session-log-fixer: fix run 20548622722

or

my PR failed session validation, please fix it

The skill will read the Job Summary from the failed run, identify the non-compliant session file, and apply the necessary fixes.

Triggers

When to Use

Use this skill when:

• A PR fails the "Session Protocol Validation" GitHub Actions workflow
• Job Summary shows NON_COMPLIANT verdict or MUST requirement failures
• You need to fix session log structure to pass CI validation

Use session-init instead when:

• Starting a new session (prevents needing this skill at all)
• Creating a session log from scratch rather than fixing an existing one

Process Overview

GitHub Actions Failure
        │
        ▼
┌───────────────────────────────────────────────────┐
│ Phase 1: READ JOB SUMMARY                         │
│ • Extract run ID from URL or PR                   │
│ • Read Job Summary from GitHub Actions            │
│ • Identify NON_COMPLIANT session files            │
│ • Parse specific missing requirements             │
│ • View detailed validation results                │
├───────────────────────────────────────────────────┤
│ Phase 2: ANALYZE                                  │
│ • Read failing session file                       │
│ • Read SESSION-PROTOCOL.md template               │
│ • Diff current vs required structure              │
│ • Identify specific missing elements              │
├───────────────────────────────────────────────────┤
│ Phase 3: FIX                                      │
│ • Apply fixes based on Job Summary details        │
│ • Copy template sections exactly                  │
│ • Add evidence to verification steps              │
│ • Validate fix locally with validate_session_json.py │
├───────────────────────────────────────────────────┤
│ Phase 4: VERIFY                                   │
│ • Commit and push changes                         │
│ • Monitor re-run status                           │
│ • Confirm COMPLIANT verdict in new Job Summary    │
└───────────────────────────────────────────────────┘
        │
        ▼
   Passing CI

Workflow

Step 1: Read Job Summary

Option A: Use the script (recommended)

# By run ID
python3 .claude/skills/session-log-fixer/scripts/get_validation_errors.py --run-id 20548622722

# By PR number
python3 .claude/skills/session-log-fixer/scripts/get_validation_errors.py --pull-request 799

Option B: Manual (web UI)

Navigate to the failed GitHub Actions run and click the Summary tab. The Session Protocol Compliance Report shows:

1. Overall Verdict - PASS or CRITICAL_FAIL
2. Compliance Summary - Table with each session file, verdict, and MUST failure count
3. Detailed Validation Results - Expandable sections showing exact failures

Example Job Summary output:

## Session Protocol Compliance Report

> [!CAUTION]
> ❌ **Overall Verdict: CRITICAL_FAIL**
>
> 1 MUST requirement(s) not met. These must be addressed before merge.

### Compliance Summary

| Session File | Verdict | MUST Failures |
|:-------------|:--------|:-------------:|
| `2025-12-29-session-11.md` | ❌ NON_COMPLIANT | 1 |

### Detailed Validation Results

Click each session to see the complete validation report with specific requirement failures.

<details>
<summary>📄 2025-12-29-session-11</summary>

| Check | Level | Status | Issues |
|-------|-------|--------|--------|
| SessionLogExists | MUST | PASS | - |
| ProtocolComplianceSection | MUST | FAIL | Missing 'Protocol Compliance' section |
| MustRequirements | MUST | PASS | - |
| HandoffUpdated | MUST | PASS | - |
...
</details>

The detailed results tell you exactly which MUST requirements failed.

Step 2: Local Validation (Optional)

Validate locally before pushing:

python3 scripts/validate_session_json.py ".agents/sessions/<session-file>.json"

This uses the same script as CI, so results match exactly.

Step 3: Read Failing Session

Session files are at .agents/sessions/YYYY-MM-DD-session-NN-*.md

Identify what's missing by comparing against the Protocol Compliance section structure.

Step 4: Read Protocol Template

Read .agents/SESSION-PROTOCOL.md to get the canonical checklist templates for:

• Session Start (COMPLETE ALL before work)
• Session End (COMPLETE ALL before closing)

CRITICAL: Copy the exact table structure. Do not recreate from memory.

Step 5: Apply Fixes

Common fixes by failure type:

For SHOULD requirements: Use [N/A] when not applicable. Use [x] with evidence when completed.

For MUST requirements: Never leave unchecked without explanation.

Step 6: Commit

git add ".agents/sessions/<session-file>.md"
git commit -m "docs: fix session protocol compliance for <session-name>

Add missing <what was missing> to satisfy session protocol validation."
git push

Step 7: Verify

gh run list --branch (git branch --show-current) --limit 3
gh run view <new-run-id> --json conclusion

Check the Job Summary tab again. If validation still fails, the detailed results show what's still missing.

Verification Checklist

After applying fixes:

• Session file has Session Start Protocol table
• Session file has Session End Protocol table
• All MUST requirements are marked [x] with evidence
• No "pending" or placeholder text in evidence column
• Commit SHA is real (not "pending commit")
• Push succeeded without conflicts
• New workflow run triggered
• Job Summary shows COMPLIANT verdict

Anti-Patterns

Troubleshooting

Scripts

Example Usage

# Get errors by run ID
python3 .claude/skills/session-log-fixer/scripts/get_validation_errors.py --run-id 20548622722

# Get errors by PR number
python3 .claude/skills/session-log-fixer/scripts/get_validation_errors.py --pull-request 799

Related Skills

References

• Common Fixes - Fix patterns for common failures
• Template Sections - Copy-paste ready templates
• CI Debugging Patterns - Advanced job-level diagnostics
• validate_session_json.py - Deterministic validation script

Converted and distributed by TomeVault — claim your Tome and manage your conversions.