Archiving Changes

Overview

After implementation is complete and verified, archive the changes by updating project documentation. This ensures future AI sessions have accurate context about the codebase.

Announce at start: "I'm using the evo-archiving skill to document the changes."

Triggering Scenarios

This skill is triggered in two scenarios with different context sources:

Scenario Context Source How to Gather Changes

After evo-executing-plans Plan + implementation Read the plan file, cross-reference with actual changes made

After manual changes Git diff + conversation Use git diff and git status to identify changes, ask user for intent if unclear

The Process

Step 1: Gather Context

Read existing documentation first:

• Read docs/architecture.md (understand current documented state)

• Read last 5 records in docs/ledger.jsonl (understand recent changes)

Identify what changed based on scenario:

If after evo-executing-plans:

• Read the plan file that was executed

• Cross-reference with actual implementation

• Note any deviations from plan

If after manual changes:

• Run git status to see changed files

• Run git diff --stat to understand scope of changes

• Ask user: "What was the goal of these changes?" (if not already clear from conversation)

Step 2: Summarize Changes

Before updating documentation, summarize:

• What was implemented/changed (from plan or user explanation)

• Architectural impact (new components, modified patterns, removed code)

• Key files added, modified, or deleted

Present summary to user: "Here's what I'll archive: [brief summary]. Proceed?"

Step 3: Update Architecture Document

File: docs/architecture.md

If file doesn't exist, create it with this structure:

Project Architecture

Auto-maintained by AI. Last updated: YYYY-MM-DD

Overview

[Brief description of what this project does]

Structure

[Key directories and their purposes]

Components

[Major components and how they interact]

Patterns

[Design patterns and conventions used]

Dependencies

[Key external dependencies and why they're used]

When updating:

• Keep descriptions concise (1-2 sentences per component)

• Focus on "what" and "why", not "how" (code shows how)

• Remove documentation for deleted components

• Update the "Last updated" date

• Preserve sections that haven't changed

Step 4: Append to Ledger

File: docs/ledger.jsonl

If file doesn't exist, create it (empty file, will append first record).

Append one JSON line per logical change:

{"date": "YYYY-MM-DD", "type": "feature|fix|refactor|docs|chore", "summary": "Brief description", "files": ["path/to/file1", "path/to/file2"], "impact": "none|low|medium|high", "source": "plan|manual"}

Field definitions:

• date : ISO date of the change

• type : Category of change

• feature : New functionality

• fix : Bug fix

• refactor : Code restructuring without behavior change

• docs : Documentation only

• chore : Maintenance (dependencies, configs)

• summary : One sentence describing the change (< 100 chars)

• files : Array of key files changed (max 5 most important)

• impact : Architectural impact level

• none : Isolated change, no architectural effect

• low : Minor addition, follows existing patterns

• medium : New component or pattern introduced

• high : Significant structural change

• source : How the change was made

• plan : Via evo-executing-plans

• manual : Direct manual changes

Step 5: Verify and Report

• Read back the updated architecture.md section

• Confirm ledger entry is valid JSON

• Report: "Archived: [summary]. Architecture and ledger updated."

When to Use

• After completing implementation via evo-executing-plans

• After significant manual code changes

• After refactoring sessions

• When cleaning up technical debt

When NOT to Use

• For trivial changes (typo fixes, comment updates)

• Mid-implementation (wait until complete)

• For experimental/temporary code

Key Principles

• Context first - Always read existing docs before updating

• Confirm before writing - Summarize changes and get user confirmation

• Preserve unchanged sections - Only update what actually changed

• Track change source - Distinguish plan-driven vs manual changes

• One logical change per ledger entry - Multiple related files = one entry

Example Ledger Entries

{"date": "2026-01-15", "type": "feature", "summary": "Add user authentication with JWT tokens", "files": ["src/auth/jwt.py", "src/middleware/auth.py", "tests/test_auth.py"], "impact": "medium"} {"date": "2026-01-18", "type": "refactor", "summary": "Extract database layer into repository pattern", "files": ["src/db/repository.py", "src/db/models.py"], "impact": "high"} {"date": "2026-01-20", "type": "fix", "summary": "Fix race condition in cache invalidation", "files": ["src/cache/manager.py"], "impact": "low"}

Key Principles

• Concise over complete - AI can read code for details

• Append-only ledger - Never modify past entries

• Architectural focus - Skip implementation details

• Honest impact assessment - Don't inflate or minimize

• Machine-readable - Valid JSON, consistent format