---
name: avizmarlon/ledger-auto-updates
source: https://app.decimal.ai/s/avizmarlon-ledger-auto-updates@1/SKILL.md
source_sha256: 70c7d5024b8d
---

## Ledger Auto-Updates — Automatic Session Closure with Living Documentation

Ledger updates (CHANGELOG + session-handoff or project equivalents) are part of session closure — not a manual decision tree, and not something the user should have to request. If the user had to ask "should we update the ledger?", the agent failed.

### Principle

The agent detects session-end conditions and automatically updates the project's living documentation to reflect:
1. **What changed** during this session (CHANGELOG entry)
2. **State for the next agent** picking up the work (session-handoff entry)

This ensures continuity across multiple AI-agent sessions without explicit handoff ceremony each time.

### Triggers — Update without asking when you detect:

- **Farewell signals**: natural language indicating the session is ending (e.g., "thanks, see you later", "that's all for now", "wrapping up", "good night")
- **Explicit wrap-up request**: user says "close the session", "prepare for next phase", "create handoff", "open new session"
- **Clear topic pivot**: moving to an unrelated topic after completing a coherent block of work (e.g., finished a bugfix phase, now asking about a different project)
- **User explicitly asks about the ledger**: *"Should we update CHANGELOG/handoff?"* or similar. If they're asking, you missed the trigger. Update immediately **and acknowledge the miss**.
- **Session running long**: approaching context limit (>50% full) with substantive work completed
- **Before declaring work complete**: any message framing closure ("all set", "ready for next session", "finished") must be preceded by ledger updates

### Criterion: What counts as "substantive work"

Update the ledger if ANY of these happened:

- Code merged into main branch (commit, PR, or direct push)
- Non-trivial architectural or product decision made
- Bug root cause identified and fixed, with a reusable lesson for other teams
- Changes to rules, instructions, or multi-tool agent configuration
- Significant debugging session that produced a new finding or pattern
- Repository state changed meaningfully (deleted worktrees, removed stale branches, refactoring)
- New tool, wrapper, script, or reusable helper created
- Configuration, MCP setup, or credentials changed in a way that affects workflow

**Do NOT update** (negative cases):

- Pure exploration or discussion ("how does X work?", "what are your thoughts on Y?")
- Only reading/searching without making changes
- Routine single-issue support that has no impact on the project as a whole

### Required Actions at Trigger

When a trigger is detected:

1. **Update CHANGELOG.md** (or project equivalent):
   - Add a new entry at the top
   - Follow the project's existing format (semantic versioning, conventional commits, or whatever is already in use)
   - Include: what changed, why it matters, and affected files/modules

2. **Update session-handoff.md** (or equivalent):
   - Add a new entry at the top with timestamp
   - Record: final repository state, any pending decisions for the next session, **non-obvious learnings for the next AI** (gotchas, surprising failure modes, commands that failed unexpectedly, paths that don't work)
   - This is continuity fuel for a future agent with zero context

3. **Commit and push**:
   - Direct commit to main if it's a solo repository with low-risk changes
   - Pull request if the change affects shared code or policy
   - Do not wait for user approval — the rule itself grants authority for this action

4. **Report to the user**:
   - 1–2 sentences: *"Updated CHANGELOG + session-handoff with [summary]. Commit [sha] pushed."*
   - No excessive detail; the real content is in the files

### Anti-Patterns (Prohibited)

- **Waiting for the user to ask**: if they're asking "did you update the ledger?", you already failed
- **Updating only one document**: CHANGELOG and session-handoff serve different purposes (changelog = immutable history; handoff = live context for next agent). Both are required.
- **Deferring with "let me propose this first"**: the ledger update is not a design decision to propose. It is a closure action, already authorized by this rule. (New tooling or rules still require explicit approval under the "permanent learning" rule — but ledger updates do not.)
- **Declaring work complete before updating the ledger**: e.g., *"✅ All done, pushed to main, clean"* without having already updated CHANGELOG and handoff. Reorder: ledger first, then closure report.

### Detecting a Miss During the Session

If you catch yourself about to report session closure without having updated the ledger:

1. **Stop.** Do not report closure yet.
2. **Update both documents immediately.**
3. **Then report** — no need for apology, just action.

---

## Scope

**Applies to:** any project using version control (Git, etc.) with a CHANGELOG and/or handoff file as living documentation. Works for all AI agents in all sessions.

**Related rules and skills:**
- **Blind-AI-bootstrap** — the principle that every AI must reconstruct full context from durable artifacts. Session-handoff is your contribution to that goal.
- **Permanent learning protocol** — differs from ledger updates. New rules, tools, and architectural decisions require explicit approval; ledger updates (documenting what happened) do not.
- **Git-PR-rules** — when to use pull requests vs. direct commits. Ledger updates usually warrant a direct commit to main unless the project requires all changes to go through review.

---

## Example Patterns

### Example 1: Feature completion

**Session event**: User says *"Thanks, I think we've got a good foundation here. Chat later!"*

**Trigger**: Farewell signal + coherent block of work completed

**Ledger entry (CHANGELOG)**:
```
## [Unreleased]

### Added
- New WebSocket event handler for real-time notifications
- Integration test suite covering edge cases in event dispatch

### Changed
- Refactored message queue to use connection pooling for efficiency
```

**Ledger entry (session-handoff)**:
```
## Session: 2026-06-14

### Completed
- Implemented WebSocket events, all tests green
- Pushed to `feature/realtime-events` branch

### For next session
- Branch ready to merge after final review
- Watch out: event loop hangs if queue drains before listener reconnects — use backpressure signal (see commit abc1234)

### Appraisal
- Design surface solid; future changes to routing logic might need queue refactor
```

### Example 2: Bug investigation that produced a lesson

**Session event**: User pivots from the bug investigation to asking about unrelated architecture questions.

**Trigger**: Clear topic pivot after debugging session

**Ledger entry (CHANGELOG)**:
```
## [Unreleased]

### Fixed
- Race condition in task scheduler when cancellation arrives during execution
  - Root cause: missing mutex guard in shutdown handler
  - Affected all long-running jobs; very low probability but high impact

### Documentation
- Added concurrency pattern guide to docs/
```

**Ledger entry (session-handoff)**:
```
## Session: 2026-06-14

### Completed
- Identified and fixed race in scheduler; added test that catches it deterministically

### Lessons learned
- Shutdown handlers must use the same locking primitive as the main loop — mixing mutexes and atomic flags caused a data race
- The race only shows up under load; normal testing didn't catch it
- See test `test_scheduler_cancel_under_load` for reproduction

### For next sessions
- If you modify shutdown paths, run the full concurrent test suite with stress mode
```

### Example 3: Refactor or cleanup

**Session event**: User says *"I'm going to move on to something else. This cleanup is done."*

**Trigger**: Explicit wrap-up after refactor completion

**Ledger entry (CHANGELOG)**:
```
## [Unreleased]

### Changed
- Removed deprecated `old_api.ts` module; all consumers migrated to `new_api.ts`
- Flattened worktree structure; deleted stale feature branches
```

**Ledger entry (session-handoff)**:
```
## Session: 2026-06-14

### Cleanup completed
- Removed 3 stale branches; deleted unused worktrees
- Deprecated API fully removed; no callers remaining

### For next session
- Repo is clean; no pending structural debt noted
```

---

## Implementation Tips

1. **Build context capture into your hook or startup**: at the very start of a session, load and read the existing CHANGELOG and session-handoff so you understand the project's format and recent history.

2. **Timestamp entries**: include dates in session-handoff entries so future agents know recency and order.

3. **Make handoff entries scannable**: use clear headers and bullet points. Future agents are busy and will skim.

4. **Include the "why" in handoff**: not just what happened, but why it matters for the next session and what gotchas to watch.

5. **Keep CHANGELOG immutable**: once an entry is in CHANGELOG and committed, do not edit it. Session-handoff is the living, mutable record.

6. **Link to commits when relevant**: "See commit abc1234 for the full diff" gives the next agent a shortcut to understanding.

---

## Validation

Before you claim "ledger updates complete," verify:

- [ ] CHANGELOG.md exists and has a new entry at the top with this session's changes
- [ ] session-handoff.md (or equivalent) exists and has a new entry with timestamp, state, and lessons
- [ ] Both files have been committed and pushed (or are staged, pending user approval if that's the project's workflow)
- [ ] The user has been notified of the update in 1–2 lines