Journal enrichment: add structured narrative sections and cross-reference with learnings/decisions

[v0lkan]

Context

After running the journal pipeline (export → normalize → enrich) on a real project, we found that enrichment produces useful YAML frontmatter (title, type, outcome, topics, technologies, summary) but the journal entries themselves still have a generic [Add your summary of this session] placeholder and jump straight into the raw conversation.

Adding structured narrative sections between the summary and the conversation turned out to be very valuable for making journal entries actually useful as reference material — not just conversation logs.

What We Did Manually (and it worked well)

After enriching journal entries, we manually added four sections after the Summary:

1. The Problem

What went wrong / what triggered this session. Written as a clear causal chain so anyone reading later understands the root cause without reading 100+ turns of conversation.

2. The Solution

What approach was taken and why. Concrete steps, not just "we fixed it." References to patterns, tools, or prior art that informed the solution.

3. What We Learned

Key takeaways — things that would change how you approach similar problems in the future. These are candidates for ctx add learning.

4. Artifacts Created

Table of files created or modified during the session, with one-line descriptions. Makes it easy to find the deliverables without scanning the conversation.

Cross-referencing with LEARNINGS.md and DECISIONS.md

After writing the narrative sections, we also ran:

ctx add learning "..." --context "..." --lesson "..." --application "..."
ctx add decision "..." --context "..." --rationale "..." --consequences "..."

This worked well but was manual. The enrichment process could automatically suggest learnings and decisions based on the session content and prompt the user to persist them.

Proposal

Option A: Enhance /ctx-journal-enrich (or -enrich-all)

Add a step after frontmatter extraction:

1. Generate narrative sections — extract problem/solution/learnings/artifacts from the conversation and insert them between Summary and Conversation.
2. Cross-reference check — scan the session for insights that look like learnings or decisions, compare against existing LEARNINGS.md and DECISIONS.md, and suggest new entries. For example:
   • "This session discovered that X causes Y → not yet in LEARNINGS.md. Add it?"
   • "This session chose approach A over B → not yet in DECISIONS.md. Add it?"
3. Summary replacement — replace [Add your summary of this session] with a generated summary (already partially done, but the narrative sections make it much richer).

Option B: Separate skill /ctx-journal-narrate

If enrichment is meant to stay lightweight (just frontmatter), a separate skill could handle the deeper extraction:

/ctx-journal-narrate 2026-02-10--80abb262

This would:

• Read the enriched journal entry
• Generate the four narrative sections
• Suggest learnings and decisions for ctx add
• Optionally apply them with user confirmation

Option C: Both

Enrichment adds frontmatter + summary. Narration adds structured sections + cross-references. The pipeline becomes: export → normalize → enrich → narrate → build.

Why This Matters

Journal entries with only frontmatter and raw conversation are searchable but not scannable. A 4-hour, 112-turn session is 9000+ lines — nobody's reading that. The narrative sections turn it into a 2-minute read that captures 90% of the value. Combined with cross-referencing to learnings/decisions, the journal becomes a genuine knowledge base rather than a transcript archive.

Example Structure

---
title: "Fixing compliance failure via post-build publish pattern"
date: 2026-02-10
type: bugfix
outcome: completed
topics: [compliance, packaging, ci-cd]
technologies: [go, make, docker, oci]
---

# 2026-02-10--80abb262

<details><summary>metadata</summary>...</details>

## Summary
One paragraph overview.

## The Problem
Clear causal chain of what went wrong.

## The Solution
What we did and why.

## What We Learned
- Insight 1 → persisted as learning
- Insight 2 → persisted as learning

## Artifacts Created
| Artifact | Description |
|----------|-------------|
| `docs/guide.md` | Comprehensive reference guide |
| `Makefile` | Updated build targets |

---

## Conversation
### 1. User (10:39:04)
...