| name | core-journaling |
| description | Ensure this skill is active before every journal write — new entry, edit, restructure, or activity log append. Provides the graph protocol (bidirectional links, indexes), the directory layout, and the activity log format that keep the journal consistent. |
| user-invocable | false |
Skill: core-journaling
The Journal is a bidirectional graph knowledge base plus a chronological log book. Every note links to related notes; every link has a reverse (backlink). The root index.md is your Heads-Up Display. The activity-log/ subtree records what was done over time.
Ensure this skill is active before every journal write — once activated it stays loaded for the session, so checking costs nothing (the System Context shows active skills). Skipping the protocol on "small" writes is how the journal becomes a half-graph: some notes linked, others orphaned. The graph protocol IS the routine — not a special mode.
Directory Structure
<journal-root>/ # CFG_LLM_JOURNAL_DIR
├── index.md # HUD: critical user prefs, active constraints, recent insights
├── user/
│ ├── index.md
│ └── <topic>.md # who the user is — role, context, history
├── preferences/
│ ├── index.md
│ └── <topic>.md # collaboration preferences, taboos
├── projects/
│ ├── index.md
│ └── <project>.md # per-project facts, decisions, layout
├── technical/
│ ├── index.md
│ └── <topic>.md # cross-project know-how, patterns, gotchas
└── activity-log/ # chronological log of significant LLM actions
├── index.md # links each year
└── YYYY/
├── index.md # links each month
└── YYYY-MM/
├── index.md # links each day
└── YYYY-MM-DD.md # all entries for that day
Each directory MUST have an index.md that links to every file in it. Exception: date-leaf directories under activity-log/YYYY/YYYY-MM/ do not — the month index covers them.
Two Kinds of Writes
| Kind | Where | Purpose |
|---|
| Insight | user/, preferences/, projects/, technical/ | What was learned — durable facts, decisions, conventions |
| Activity | activity-log/YYYY/YYYY-MM/YYYY-MM-DD.md | What was done — timestamped log of significant tasks |
Both apply the graph protocol below. Both can cross-link to each other.
Graph Protocol
Link Convention
Use standard markdown links for all internal references. Paths are relative to the file that contains the link (standard markdown semantics) — climb out of a subdirectory with ../:
- From the root
index.md: [asyncio patterns](technical/python-asyncio.md)
- From
projects/my-app.md to a technical note: [jwt notes](../technical/jwt.md)
- From an
activity-log/YYYY/YYYY-MM/ day file to a project note: [zrb project](../../../projects/zrb.md)
journal-lint.py resolves links this way. A link written relative to the journal root resolves correctly only from the root index.md; from any other file it is flagged as a broken link.
Backlink Rule (Non-negotiable)
Every note (except index.md files) must have a ## Backlinks section at the bottom. When you create a forward link, immediately append a backlink to the target. Backlink paths are file-relative too — written from the note that holds them.
For example, inside technical/jwt.md:
## Backlinks
- [my-app project](../projects/my-app.md) — referenced for auth architecture
- [2026-06-02 log](../activity-log/2026/2026-06/2026-06-02.md) — algorithm chosen here
Rules:
- Add a backlink immediately when you create a forward link.
- When deleting a link, remove the corresponding backlink in the target.
- Keep backlink entries short — path + one-phrase reason.
Graph Invariants
- BIDIRECTIONAL — every forward link has a backlink entry in the target.
- NO ORPHANS — every file is reachable from
index.md via forward links.
- ATOMICITY — one concept per file; split if too large.
- RHIZOMATIC — link liberally between related concepts across directories.
Companion Templates
When writing a specific kind of entry, Read the matching template from this skill's directory:
| Writing | Template |
|---|
An insight note (user/, preferences/, projects/, technical/) | templates/insight-note.md |
| A day's activity log entry | templates/activity-entry.md |
Companion Tools
Writing an Insight Note (Step-by-Step)
- Decide the file path under
user/, preferences/, projects/, or technical/ (atomic — one concept per file).
- Write the note body using the format in
templates/insight-note.md.
- Add forward markdown links to related notes throughout the body.
- Add a
## Backlinks section at the bottom (initially empty, or pre-populated if you know who will link here).
- For each forward link you added, open the target file and append this note to its
## Backlinks section.
- Add a markdown link to the new note from the relevant directory
index.md.
- If noteworthy enough for the HUD, also add a link from outer
index.md under Recent Insights.
Writing an Activity Log Entry (Step-by-Step)
- Compute today's path:
activity-log/YYYY/YYYY-MM/YYYY-MM-DD.md.
- If the file does not exist, create it with an
# YYYY-MM-DD heading. Then create or update the month index, year index, and activity-log/index.md as needed.
- Append a new section using the format in
templates/activity-entry.md.
- Cross-link from the entry to any insight notes touched — a day file sits three levels deep, so climb out:
[<topic>](../../../technical/<topic>.md), [<project>](../../../projects/<project>.md). Add the reverse backlink from those notes to this entry's path under ## Backlinks if the link is durable (not for trivial mentions). Use markdown links, never [[wikilinks]].
Maintenance
- Every directory needs
index.md linking to all files in it (except date-leaf directories under activity-log/).
- When refactoring (rename, split, delete): update all backlinks that reference the old path. Run
tools/journal-lint.py after.
- Merge tiny stubs; split files that grow beyond ~80 lines.
- Verify no orphans after structural changes.
