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

Triggers

Trigger Phrase	Operation
`fix session validation failure`	Detect and fix session log issues
`session protocol failed in CI`	Read Job Summary and apply fixes
`fix the failing session check`	Context-aware CI failure resolution
`NON_COMPLIANT session log`	Direct from CI validation output
`my PR failed session validation`	Natural language activation

Input	Output	Quality Gate
Run ID or PR number	Fixed session file with commit	CI re-run passes

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:

Overall Verdict - PASS or CRITICAL_FAIL
Compliance Summary - Table with each session file, verdict, and MUST failure count
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:

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_validation_errors.py	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
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

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

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

session-log-fixer

Session Log Fixer

Quick Start