session-log-fixer

Fix session protocol validation failures in GitHub Actions. Use when a PR fails with "Session protocol validation failed", "MUST requirement(s) not met", "NON_COMPLIANT" verdict, or "Aggregate Results" job failure in the Session Protocol Validation workflow. With deterministic validation, failures show exact missing requirements directly in Job Summary - no artifact downloads needed.

⭐3stars🔀0forks📁View on GitHub🕐Updated Jan 4, 2026

When & Why to Use This Skill

The Session Log Fixer is a specialized Claude skill designed to automatically diagnose and resolve session protocol validation failures within GitHub Actions. By leveraging deterministic validation feedback directly from CI Job Summaries, it identifies non-compliant session files, applies required structural fixes from templates, and commits the corrected files to ensure passing CI builds without manual intervention. This tool streamlines the developer workflow by eliminating the need to manually download artifacts or decipher complex CI logs for compliance issues.

Use Cases

  • Automatically fixing 'NON_COMPLIANT' verdicts and 'MUST requirement not met' failures in GitHub Actions workflows.
  • Repairing missing or malformed Session Start and Session End protocol tables by synchronizing them with the canonical SESSION-PROTOCOL.md template.
  • Resolving validation errors related to placeholder text by replacing 'pending' markers with actual commit SHAs and verified evidence.
  • Accelerating the Pull Request approval process by ensuring all session documentation meets compliance standards before human review.
  • Providing local validation of session files using scripts to ensure compliance before pushing changes to the remote repository.
namesession-log-fixer
descriptionFix session protocol validation failures in GitHub Actions. Use when
version3.0.0
licenseMIT
modelclaude-sonnet-4-5
typediagnostic-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

  • session-log-fixer: {run-id} - Fix specific workflow run
  • fix session validation for {PR/run} - Natural language activation
  • session protocol failed - When user reports a failure
  • NON_COMPLIANT session - Direct from CI output
  • MUST requirement not met - Direct from validation error
Input Output Quality Gate
Run ID or PR number Fixed session file with commit CI re-run passes

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-SessionJson.ps1 │
├───────────────────────────────────────────────────┤
│ 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
$errors = & .claude/skills/session-log-fixer/scripts/Get-ValidationErrors.ps1 -RunId 20548622722

# By PR number
$errors = & .claude/skills/session-log-fixer/scripts/Get-ValidationErrors.ps1 -PullRequest 799

# View errors
$errors | ConvertFrom-Json

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:

pwsh scripts/Validate-SessionJson.ps1 -SessionPath ".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:

Failure Fix
Missing Session Start table Copy template from SESSION-PROTOCOL.md
Missing Session End table Copy template from SESSION-PROTOCOL.md
"Pending commit" Replace with actual commit SHA from gh pr view
Empty evidence column Add evidence text: "Tool output present", "Content in context", or "Commit SHA: abc1234"
Unchecked MUST Mark [x] with evidence, or mark [N/A] with justification if truly not applicable

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

Avoid Why Instead
Recreating tables from memory Will miss exact structure Copy from SESSION-PROTOCOL.md
Marking MUST as N/A without justification Validation will fail Provide specific justification
Using placeholder evidence Validators detect these Use real evidence text
Fixing without checking Job Summary May miss actual failure Always check Job Summary first
Ignoring SHOULD requirements Creates future tech debt Mark appropriately

Troubleshooting

Problem Solution
gh run view fails Verify run ID is correct, check authentication
Can't find Job Summary Click "Summary" tab at top of workflow run page
Job Summary unclear Expand detailed validation results for specifics
Fix didn't work Check new Job Summary for remaining issues
Wrong session file Verify branch matches PR, check for multiple session files
Local validation differs from CI Ensure you're using latest SESSION-PROTOCOL.md

Scripts

Script Purpose Exit Codes
Get-ValidationErrors.ps1 Extract validation errors from GitHub Actions Job Summary 0=success, 1=run not found, 2=no errors found

Example Usage

# Get errors by run ID
$result = & .claude/skills/session-log-fixer/scripts/Get-ValidationErrors.ps1 -RunId 20548622722
$errors = $result | ConvertFrom-Json

# View non-compliant sessions
$errors.NonCompliantSessions

# View detailed errors for specific session
$errors.DetailedErrors.'2025-12-29-session-11'

# Get errors by PR number
$result = & .claude/skills/session-log-fixer/scripts/Get-ValidationErrors.ps1 -PullRequest 799

Skill Relationship
session-init Prevents need for this skill by correct initialization
analyze Deep investigation when fixes aren't obvious

References