Kora Journal

Kora Journal — Continuous Improvement for Kora Skills

Kora sub-skill — obey the kora-v1 meta rules on every task: R0 ensure .kora-agent/ docs+examples are cloned · R1 read this sub-skill before writing code · R2 Kora APIs only — no Spring/Micronaut/Quarkus, no invented annotations or config keys · R3 journal any incorrect Kora usage. Add comments/Javadoc only if asked.

Location: ~/.kora-journal/<project>/<module>/<YYYY-MM-DD>_slug.md

Format: Each entry is a separate Markdown file for easy management, export, and integration.

⚠️ READ FIRST — Purpose & Scope

Purpose: Journal for recording Kora Framework incorrect usage discovered during development — when the agent used Kora incorrectly and realized it or the user pointed it out.

⚠️ SCOPE — Kora Incorrect Usage ONLY:

Trigger: When YOU (agent) realize OR USER points out that you used Kora Framework incorrectly.

Why: Journal feeds skill improvements. Non-Kora entries clutter the journal and dilute its value.

Quick Start

# Add entry (creates separate .md file, tags auto-generated)
python kora-journal/scripts/kora_journal.py add "Fixed HTTP client example" \
  --context "Implementing interceptor" \
  --problem "Example missing error handling" \
  --solution "Added try-catch and logging" \
  --files kora-http-client/references/interceptors-reference.md

# Add entry with custom tags
python kora-journal/scripts/kora_journal.py add "OAuth2 token refresh" \
  --context "..." --problem "..." --solution "..." --files ... \
  --tags auth oauth2 client token

# Search journal by keywords (use AFTER reading references)
python kora-journal/scripts/kora_journal.py search "http interceptor auth" --limit 5

# Search by tags only (more precise)
python kora-journal/scripts/kora_journal.py search "auth oauth2" --by-tags

# View recent entries
python kora-journal/scripts/kora_journal.py list --limit 10

# Export pending entries from date
python kora-journal/scripts/kora_journal.py export --since 2026-05-01 --status pending

# Mark entry as integrated after applying to skills
python kora-journal/scripts/kora_journal.py integrate 2026-06-20_fixed-http-client.md

# Check status
python kora-journal/scripts/kora_journal.py status

Storage Structure

Global location: ~/.kora-journal/ (shared across ALL sessions and projects)

~/.kora-journal/
├── kora-skills/                    # Project name (from git repo)
│   └── kora-iter4/                 # Gradle module name
│       ├── 2026-06-20_fixed-http-client-example.md
│       ├── 2026-06-19_jdbc-repository-mapper-auto-discovery.md
│       ├── 2026-06-18_openapi-oneof-workaround.md
│       └── ...                     # Each entry is a separate file
├── another-project/
│   └── service-module/
│       └── ...
└── ...

Filename format: YYYY-MM-DD_slug-from-title.md

Benefits:

• ✅ Each entry is atomic — easy to manage, move, delete
• ✅ No merge conflicts (separate files)
• ✅ Easy to export specific entries
• ✅ Status tracking per entry (pending → integrated → archived)
• ✅ All sessions share the same journal location
• ✅ Survives project deletion

Git: Excluded via ~/.kora-journal/ in global .gitignore.

Workflow

1. During Session — Record Discovery

When you fix a Kora issue or discover a pattern:

python kora-journal/scripts/kora_journal.py add "Title" \
  --context "What you were doing" \
  --problem "What went wrong / was unclear" \
  --solution "How you fixed it" \
  --files skills/kora-xxx/SKILL.md

Creates: ~/.kora-journal/<project>/<module>/YYYY-MM-DD_slug.md

2. Before Similar Work — Review Journal

# Last 10 pending entries
python kora-journal/scripts/kora_journal.py list --limit 10 --status pending

# All entries
python kora-journal/scripts/kora_journal.py list

3. Export for Integration

# Export only pending entries from date
python kora-journal/scripts/kora_journal.py export --since 2026-05-01 --status pending

4. Apply Changes to Skills

Review exported entries and apply changes to:

• skills/kora-xxx/SKILL.md
• skills/kora-xxx/references/xxx-reference.md

5. Mark as Integrated

After applying changes:

python kora-journal/scripts/kora_journal.py integrate 2026-06-20_fixed-http-client.md

Updates entry status: pending → integrated

Entry File Format

Each entry is a Markdown file with YAML frontmatter:

---
title: "Fixed HTTP client example"
date: 2026-06-20
project: kora-skills
module: kora-iter4
author: dsudomoin
tags: []
---

# Fixed HTTP client example

**Date:** 2026-06-20  
**Project:** kora-skills  
**Module:** kora-iter4  
**Author:** dsudomoin

---

## Context

What you were doing when you encountered this issue.

## Problem

What went wrong? What was unclear? What blocked you?

## Solution

How you fixed it. Include code/config snippets if helpful.

## Files Affected

- `skills/kora-http-client/SKILL.md`
- `skills/kora-http-client/references/interceptors-reference.md`

---

## Metadata

- **Created:** 2026-06-20_14-30-00
- **Status:** pending  # pending → integrated → archived
- **Integrated:** 

Status Lifecycle

pending ──→ integrated ──→ archived
  │            │              │
  │            │              │
  └─ New entry └─ Applied to  └─ Old entries
     created      skills        (cleanup)

Commands Reference

Tags System

Tags are auto-generated from title and problem/solution text when you add an entry. Common auto-detected tags:

Override auto-generated tags:

python kora-journal/scripts/kora_journal.py add "OAuth2 token refresh" \
  --context "..." --problem "..." --solution "..." --files ... \
  --tags auth oauth2 client token

Search by tags (more precise than content search):

python kora-journal/scripts/kora_journal.py search "auth oauth2" --by-tags

Common Pitfalls

Best Practices

1. Add immediately — Record right after solving, don't rely on memory
2. Be specific — Include exact files, code snippets, commands
3. Use status lifecycle — pending → integrated → archived
4. Export weekly — export --since YYYY-MM-DD --status pending
5. Integrate monthly — Don't let pending entries accumulate beyond 20
6. Archive quarterly — Clean up old integrated entries

See Also

• Journal Workflow — Detailed workflow
• Entry Template — Entry format template