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.
Fix session protocol validation failures using deterministic validation feedback from Job Summary.
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.
| 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 |
Use this skill when:
Use session-init instead when:
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.ts │
├───────────────────────────────────────────────────┤
│ Phase 4: VERIFY │
│ • Commit and push changes │
│ • Monitor re-run status │
│ • Confirm COMPLIANT verdict in new Job Summary │
└───────────────────────────────────────────────────┘
│
▼
Passing CI
# By run ID
bun run ${CLAUDE_SKILL_DIR}/scripts/get_validation_errors.ts --run-id 20548622722
# By PR number
bun run ${CLAUDE_SKILL_DIR}/scripts/get_validation_errors.ts --pull-request 799
Navigate to the failed GitHub Actions run and click the Summary tab. The Session Protocol Compliance Report shows:
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.
Validate locally before pushing:
bun run scripts/validate_session_json.ts ".agents/sessions/<session-file>.json"
This uses the same script as CI, so results match exactly.
Session files are at .agents/sessions/YYYY-MM-DD-session-NN-*.md
Identify what's missing by comparing against the Protocol Compliance section structure.
Read .agents/SESSION-PROTOCOL.md to get the canonical checklist templates for:
CRITICAL: Copy the exact table structure. Do not recreate from memory.
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.
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
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.
After applying fixes:
[x] with evidence| 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 |
| 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 |
| Script | Purpose | Exit Codes |
|---|---|---|
| get_validation_errors.ts | Extract validation errors from GitHub Actions Job Summary | 0=success, 1=run not found, 2=no errors found |
# Get errors by run ID
bun run ${CLAUDE_SKILL_DIR}/scripts/get_validation_errors.ts --run-id 20548622722
# Get errors by PR number
bun run ${CLAUDE_SKILL_DIR}/scripts/get_validation_errors.ts --pull-request 799
| Skill | Relationship |
|---|---|
| session-init | Prevents need for this skill by correct initialization |
| analyze | Deep investigation when fixes aren't obvious |
validate_session_json.ts - Deterministic validation script