session-log-fixer

name	session-log-fixer
description	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).
version	3.0.0
license	MIT
metadata	{"domains":["ci","session-protocol","compliance","github-actions"],"type":"diagnostic-fixer","inputs":["run-id","pr-number"],"outputs":["fixed-session-file","commit"]}

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

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:

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:

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
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

---

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.

---

References

• Common Fixes - Fix patterns for common failures
• Template Sections - Copy-paste ready templates
• CI Debugging Patterns - Advanced job-level diagnostics
• scripts/validate_session_json.py - Deterministic validation script. In the rjmurillo/ai-agents repository; it does not ship with this skill.