session-end

star 34

Validate and complete session logs before commit. Auto-populates session end evidence (commit SHA, lint results, memory updates) and runs validation. Use when finishing a session, before committing, or when session validation fails.

rjmurillo By rjmurillo schedule Updated 6/5/2026
play_arrow Run Skill in Manus View GitHub

name: session-end description: Validate and complete session logs before commit. Auto-populates session end evidence (commit SHA, lint results, memory updates) and runs validation. Use when finishing a session, before committing, or when session validation fails. version: 1.0.0 license: MIT model: claude-sonnet-4-6 metadata: domains: - session-protocol - compliance - automation

type: completion

Session End

Validate and complete session logs before commit. Complements session-init (which handles creation).

Quick Start

Automated (Recommended)

python3 .claude/skills/session-end/scripts/complete_session_log.py

The script will:

  1. Find the current session log automatically
  2. Auto-populate session end evidence from git state
  3. Run markdown lint on changed files
  4. Validate with validate_session_json.py
  5. Report pass/fail with actionable next steps

Preview Changes First

python3 .claude/skills/session-end/scripts/complete_session_log.py --dry-run

Triggers

Phrase Action
/session-end Complete and validate current session log
complete session Natural language activation
finalize session Alternative trigger
validate session end Alternative trigger
finish session Alternative trigger
Input Output Quality Gate
Session log (auto-detected or specified) Validated, completed session log Exit code 0 from validation

When to Use

REQUIRED before closing any session. The Stop hook at .claude/hooks/Stop/invoke_session_validator.py enforces this: sessions will not close until protocolCompliance.sessionEnd MUST items are complete. If you attempt to close without running session-end, the hook will force continuation.

Specifically:

  • Finishing a work session and ready to commit
  • Session log needs end-of-session evidence populated
  • Want to verify session compliance before pushing

Use session-init instead when:

  • Starting a new session (creating a session log from scratch)

Use session-log-fixer instead when:

  • CI already failed and you need to fix a specific validation error
  • Working with a session log from a previous PR

Process Overview

User Request: /session-end
    |
    v
+---------------------------------------------+
| Phase 1: FIND SESSION LOG                    |
| - Auto-detect most recent .json in           |
|   .agents/sessions/                          |
| - Prefer today's sessions                    |
| - Accept explicit -SessionPath               |
+---------------------------------------------+
    |
    v
+---------------------------------------------+
| Phase 2: GATHER EVIDENCE                     |
| - Ending commit SHA (git rev-parse)          |
| - HANDOFF.md modification check              |
| - Serena memory update check                 |
| - Run markdown lint on changed files         |
| - Check for uncommitted changes              |
+---------------------------------------------+
    |
    v
+---------------------------------------------+
| Phase 3: UPDATE SESSION LOG                  |
| - Auto-populate evidence fields              |
| - Mark completed items                       |
| - Evaluate checklist completeness            |
| - Write updated JSON                         |
+---------------------------------------------+
    |
    v
+---------------------------------------------+
| Phase 4: VALIDATE                            |
| - Run validate_session_json.py               |
| - Update validationPassed field              |
| - Report pass/fail with details              |
+---------------------------------------------+
    |
    v
Completed Session Log (or actionable errors)

What Gets Auto-Populated

Field Source Level
endingCommit git rev-parse --short HEAD Top-level
handoffNotUpdated Check git diff for HANDOFF.md MUST NOT
serenaMemoryUpdated Check .serena/memories/ changes MUST
markdownLintRun Run markdownlint on changed .md files MUST
changesCommitted Check git status for uncommitted changes MUST
checklistComplete Evaluate all MUST items MUST
validationPassed Run validate_session_json.py MUST

What You Must Provide Manually

  • Serena memory updates (create/edit .serena/memories/ files before running)
  • Commit your changes (run git commit before running)
  • Work log entries in the session JSON

Workflow

Step 1: Complete Your Work

Before running this skill, ensure you have:

  • Finished implementation tasks
  • Updated Serena memories if applicable
  • Staged and committed your changes

Step 2: Run Session End

# Auto-detect and complete
python3 .claude/skills/session-end/scripts/complete_session_log.py

# Or specify session explicitly
python3 .claude/skills/session-end/scripts/complete_session_log.py --session-path ".agents/sessions/2026-02-07-session-05.json"

# Preview only
python3 .claude/skills/session-end/scripts/complete_session_log.py --dry-run

Step 3: Address Any Failures

If validation fails, the output shows exactly what is missing:

[TODO] Serena memory not updated - update .serena/memories/ before completing
[TODO] Uncommitted changes exist - commit before completing

Fix the issues and re-run the skill.

Step 4: Commit Final State

After the skill reports PASS, commit the updated session log:

git add .agents/sessions/*.json
git commit -m "docs: complete session log"

Verification Checklist

Before reporting success, the script verifies:

  • Session log found and readable
  • Valid JSON structure
  • Ending commit SHA populated
  • HANDOFF.md NOT modified
  • Serena memory updated (or flagged)
  • Markdown lint passed on changed files
  • All changes committed (or flagged)
  • Validation script passes (exit code 0)

Anti-Patterns

Avoid Why Instead
Skipping session-end before commit Validation only catches errors at CI time Run /session-end before every commit
Manually editing session end fields Error-prone, misses evidence Let the script auto-populate
Running without committing first changesCommitted will fail Commit work, then run session-end
Ignoring TODO warnings Session will fail CI validation Address each TODO before final commit

Example Output

Success:

Auto-detected session log: .agents/sessions/2026-02-07-session-05.json

=== Session End Completion ===
File: .agents/sessions/2026-02-07-session-05.json

Running markdown lint...

--- Changes ---
  Set endingCommit: abc1234
  Confirmed HANDOFF.md not modified
  Confirmed Serena memory updated
  Markdown lint: 3 files linted
  All changes committed

Updated: .agents/sessions/2026-02-07-session-05.json

Running validation...

=== Session Validation ===
File: .agents/sessions/2026-02-07-session-05.json

[PASS] Session log is valid

[PASS] Session log completed and validated

Failure:

=== Session End Completion ===

--- Changes ---
  Set endingCommit: abc1234
  Confirmed HANDOFF.md not modified
  [TODO] Serena memory not updated - update .serena/memories/ before completing
  Markdown lint: 2 files linted
  [TODO] Uncommitted changes exist - commit before completing

[FAIL] Session validation failed. Fix issues above and re-run.

Scripts

Script Purpose Exit Codes
complete_session_log.py Auto-populate and validate session end 0=success, 1=validation failed

Parameters

Parameter Type Required Description
--session-path string No Path to session log. Auto-detects if omitted.
--dry-run flag No Preview changes without writing to file.

Related Skills

Skill Relationship
session-init Creates session logs (this skill completes them)
session-log-fixer Reactive fix after CI failure (this skill prevents the need)
session Session management utilities

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/ write (session logs) The completion script prints [FAIL] No session log found in .agents/sessions/ and exits non-zero. Create the directory or set the session path explicitly.
.agents/SESSION-PROTOCOL.md reference only The protocol reference link is informational; absence does not block the skill.

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

Pattern: Shift-Left Validation

This skill follows the shift-left principle: catch errors at development time, not CI time.

Aspect Without Skill With Skill
When errors found CI pipeline (minutes later) Before commit (immediately)
Feedback loop Push, wait, read logs, fix, push again Run script, see errors, fix, done
Cost CI minutes + developer context switch Seconds of local validation
Reliability Same script as CI Same script as CI
Install via CLI
npx skills add https://github.com/rjmurillo/ai-agents --skill session-end
Repository Details
star Stars 34
call_split Forks 9
navigation Branch main
article Path SKILL.md
More from Creator
rjmurillo
rjmurillo Explore all skills →