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. Do NOT use to complete a session log locally before commit (use session-end).
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. Do NOT use to complete a session log locally before commit (use session-end).
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
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
## 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:
uv run python 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, run the bundled validator and require exit 2 (no errors found):
python3 .claude/skills/session-log-fixer/scripts/get_validation_errors.py --run-id "$RUN_ID"echo"exit=$?"# must be 2 (no errors found = validation passed); exit 1 = run not found; exit 0 = errors still present
get_validation_errors.py exited 2 (no validation errors found in the new run); any other exit code means validation is not yet passing
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
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
Prevents need for this skill by correct initialization
analyze
Deep investigation when fixes aren't obvious
Vendored install
This skill depends on upstream-only paths. In a vendored install (a consumer
repo that is not rjmurillo/ai-agents) these paths do not exist:
Path
Direction
Behavior when absent
.agents/sessions/
reference target (session logs being fixed)
No upstream session logs are available to repair; provide the affected log path/content from the consumer repo.
.agents/SESSION-PROTOCOL.md
reference source (template sections)
Copy-paste template sections come from the protocol file; without it, supply the template content explicitly.
The HTML comment above is the machine-readable declaration the
check_skill_md_portability.py validator (Issue #2050) reads to confirm this
skill has disclosed its path dependencies instead of hiding them in prose.
