knowledge-persistence

Files (2)

• FILE-TEMPLATES.md
• SKILL.md

SKILL.md (first lines)

# Knowledge Persistence Skill

## Purpose

This skill extracts the agent's accumulated understanding from the current
session and persists it into a structured set of knowledge files on disk.
Use this skill at any checkpoint during or at the end of a productive
session, or when explicitly asked to "save context", "persist knowledge",
or "update knowledge file".

Persisting to disk is **not** the end of the skill: **every persistence run
finishes with its own commit and push** (SVN: `svn ci`) of the updated
knowledge files, referencing the active issue. Knowledge that is written but
not committed does not exist for the next agent — the run is only complete
once the changes are on the trunk.

## Target Structure

Ensure the following directory and files exist relative to the project root.
Create any missing files. Never delete entries from HISTORY.md (it is
an append-only archive). Do delete superseded entries from active files
by relocating them to HISTORY.md.

```text
docs/ai/
├── HANDOFF.md
├── DECISIONS.md
├── ARCHITECTURE.md
├── CONVENTIONS.md
├── PITFALLS.md
├── DOMAIN.md
├── STATE.md
└── HISTORY.md
```

**Active files** (must match current HEAD; no superseded entries):
HANDOFF.md, DECISIONS.md, ARCHITECTURE.md, CONVENTIONS.md, PITFALLS.md,
DOMAIN.md, STATE.md.

**Historical file** (chronological sink; superseded entries EXPECTED here):
HISTORY.md.

## Protocol

### 1. Discovery

- Read all existing files in `docs/ai/` to understand what is
  already persisted.
- If the directory does not exist, create it.
- If a file does not exist, create it with the template in
  [FILE-TEMPLATES.md](./FILE-TEMPLATES.md).

### 2. Diff Against Session

- Review the full conversation history of the current session.
- For each knowledge file, identify facts, decisions, patterns, or status
  changes that emerged during this session and are NOT yet in the file.
- Ignore transient chatter, failed attempts that were fully superseded,
  and speculative discussion that did not lead to a conclusion.

### 3. Write Updates

- Append new entries to the appropriate file.
- If an existing entry is now outdated, MOVE it to HISTORY.md (do not
  leave superseded content in active files).
- Never duplicate an entry that already exists.
- Write only facts. One item per bullet. No preamble, no commentary,
  no summaries at the top of the file.

### 3b. Prune Superseded Entries

For each active file being updated, scan for entries that no longer
match current reality:

- Entries contradicted by current code or configuration.
- Entries superseded by a later decision or implementation.
- Entries describing a reverted or removed change.

For each superseded entry found:

1. **Remove** it from the active file.
2. **Append** it to `HISTORY.md` with a header:
   `## YYYY-MM-DD (SUPERSEDED YYYY-MM-DD, origin: <FILE>, reason: <why or #NNN>): <Title>`
3. Include the original entry text below the header, plus one line
   noting the origin file and the reason it was superseded.
4. Leave a ONE-LINE pointer in the active file ONLY if a future reader
   would otherwise re-discover the same pitfall; otherwise delete
   cleanly.

**PITFALLS.md special case**: Distinguish between:
- **(a) Permanent non-obvious constraints** (e.g., "Room validates
  PRAGMA table_info, PK must be NOT NULL") — these stay in active
  PITFALLS.md.
- **(b) Bugs that were fixed** (e.g., "clearText+typeText race, fixed
  in #254") — these MOVE to HISTORY.md once the fix ships. Their value
  is historical, not advisory.

**Status-tag convention**: For active-file entries with a known
lifecycle (e.g., a workaround slated for removal), append an optional
trailing tag `[ACTIVE until #NNN]` so a future pruner knows to
relocate it.

### 4. Rewrite `ARCHITECTURE.md` (if structural changes occurred)

- Determine whether the session introduced any structural changes:
  new/removed/renamed commands, skills, knowledge files, or significant
  changes to data flows, dependencies, or component relationships.
- If no structural changes occurred, skip this step and leave
  `ARCHITECTURE.md` unchanged.
- If structural changes did occur, **overwrite** `docs/ai/ARCHITECTURE.md`
  with the current system snapshot using the template in
  [FILE-TEMPLATES.md](./FILE-TEMPLATES.md).
- Like STATE.md, this file is overwritten (not appended) because it
  represents a point-in-time structural map, not a chronological log.

### 5. Write `HANDOFF.md`

- Check the task list maintained during this session.
- If any tasks are still [PENDING] or [IN PROGRESS], write them to

From georgernstgraf/opencode-helpers, MIT.

More from georgernstgraf/opencode-helpers