Full journal pipeline: import unimported sessions, then batch-enrich all unenriched entries. Use when the user says 'process the journal' or to catch up on the backlog.
Instrucciones de origen · Vista previa de solo lectura
name
ctx-journal-enrich-all
description
Full journal pipeline: import unimported sessions, then batch-enrich all unenriched entries. Use when the user says 'process the journal' or to catch up on the backlog.
Full journal pipeline: import if needed, then batch-enrich.
When to Use
When the user says "enrich everything" or "process the journal"
When there is a backlog of unenriched or unimported sessions
Periodically to catch up on recent sessions
After the check-journal hook reports unimported or unenriched entries
When NOT to Use
For a single specific session (use /ctx-journal-enrich instead)
Process
Step 0: Import If Needed
Before enriching, check whether there are unimported sessions. If
the journal directory has no .md files at all, or if there are
.jsonl session files newer than the newest journal entry, import
them first.
Report how many sessions were imported (or "none needed") before
moving to enrichment.
Step 1: Find Unenriched Entries
List all journal entries that lack enrichment using the state file:
# List .md files in journal dir and check state
CTX_PATH=$(ctx system bootstrap -q)
for f in"$CTX_PATH/journal/"*.md; do
name=$(basename"$f")
ctx system mark-journal --check "$name" enriched || echo"$f"done
Or read .state.json in the journal directory directly and list
entries without an enriched date set.
Fallback: Detect Enrichment from Frontmatter
If mark-journal --check is unavailable (no state file, command
fails), fall back to frontmatter inspection. An entry is considered
already enriched if its YAML frontmatter contains bothtype
and outcome fields: these are set exclusively by enrichment, never
by import.
Do NOT use title or date to detect enrichment: those are always
present from import. The enrichment-only fields are:
Field
Set by
title
Import
date
Import
time
Import
model
Import
tokens_in
Import
tokens_out
Import
session_id
Import
project
Import
type
Enrichment
outcome
Enrichment
topics
Enrichment
technologies
Enrichment
summary
Enrichment
If all entries already have enrichment recorded, report that and stop.
Step 2: Filter Out Noise
Skip entries that are not worth enriching:
Locked entries: a file is locked if .state.json has a
locked date OR the frontmatter contains locked: true. Never
modify locked files: neither metadata nor body. Check via:
ctx system mark-journal --check <filename> locked
or look for locked: true in the YAML frontmatter.
Suggestion sessions: files under ~20 lines or containing
only auto-complete fragments. Check with:
wc -l <file>
Multi-part continuations: files ending in -p2.md, -p3.md
etc. Enrich only the first part; continuation parts inherit
the frontmatter topic.
Report how many entries will be processed and how many were
filtered out.
Step 3: Process Each Entry
For each entry, read the conversation and extract:
Title: a short descriptive title for the session
Type: feature, bugfix, refactor, exploration, debugging,
or documentation
Outcome: completed, partial, abandoned, or blocked
Topics: 2-5 topic tags
Technologies: languages, frameworks, tools used
Summary: 2-3 sentences describing what was accomplished
After writing frontmatter to each file, update the state file:
ctx system mark-journal <filename> enriched
Step 5: Report
After processing, report:
How many sessions were imported (or "none needed")
How many entries were enriched
How many were skipped (already enriched, too short, etc.)
Remind the user to rebuild: ctx journal site --build
Confirmation Mode
Interactive (default when user is present): show a summary
of proposed enrichments before applying. Group by type/outcome
so the user can scan quickly rather than reviewing one by one.
Unattended (when running in a loop or explicitly told
"just do it"): apply enrichments directly and report results.
Large Backlogs (20+ entries)
For large backlogs, use the heuristic enrichment script bundled
in references/enrich-heuristic.py. This script infers type,
outcome, topics, and technologies from the title and filename
patterns, then inserts frontmatter and marks state automatically.
How to use
Build a file list of eligible entries (non-multipart, 20+ lines,
missing type: and outcome: fields):
Run the heuristic enrichment script. The script path is relative
to this skill's directory: copy it to /tmp or reference it via
the full embedded path:
The script handles everything: reads files, inserts frontmatter,
runs ctx system mark-journal for each, and reports counts.
When to use heuristic vs. per-file enrichment
Backlog size
Approach
1-5 entries
Read each file, enrich manually with full context
6-20 entries
Sequential processing in the main conversation
20+ entries
Use enrich-heuristic.py for bulk processing
The heuristic script produces good-enough enrichment from titles
and filenames. For higher quality, follow up with manual review
of entries where the type or topics look wrong.
Subagent parallelization is an alternative for 20+ entries, but
requires that subagents have Edit and Bash permissions granted.
If permissions are restricted, the heuristic script is faster
and more reliable.
Quality Checklist
Unimported sessions detected and imported before enrichment
Suggestion sessions and multi-part continuations filtered
Each enriched entry has all required frontmatter fields
Summary is specific to the session, not generic
User was shown a summary before applying (unless unattended)
