Kora Journal

Kora Journal — Continuous Improvement for Kora Skills

Kora sub-skill — obey the kora-v2 meta rules on every task: R0 ground the workspace on Kora 2.0 refs before starting (framework source at tag 2.0.0.RC1 + kora-examples at migration/2.0; kora-docs is 1.x only) · R1 read this sub-skill before writing code · R2 Kora 2.0 APIs only — no Spring/Micronaut/Quarkus, no Kora 1.x APIs, no invented annotations or config keys · R3 journal any incorrect Kora usage. Add comments/Javadoc only if asked.

This skill is tooling, not Kora API documentation. It is the R3 feedback loop: a CLI that records Kora mistakes so the next session does not repeat them.

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

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

Kora line: the store is shared with the Kora 1.x package. Entries written by this package carry kora: "2.x" in their front matter; entries without that field are older and must be re-checked against Kora 2.0 before you apply them. search prints the line for every hit.

⚠️ 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 (same table as R3 in the meta-skill):

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

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

The highest-value entries in a 2.0 project are the silent ones — code that compiles and a build that stays green while the service is wrong. @Tag(HttpServerModule.class) on a global interceptor, a db { } config section, publicApiHttpPort, telemetry left at its false default. Those are exactly the mistakes nobody remembers a month later. See §4 of the meta-skill.

Running the CLI

python3 skills/kora-journal/scripts/kora_journal.py <command> ...

• The script path is relative to this skill package, not to the project you are working in. From the kora-starter mirror it is ../kora-journal/scripts/kora_journal.py. When the package is installed as a plugin, use the absolute path: the directory holding this SKILL.md, plus scripts/kora_journal.py.
• Run it with the project as the working directory. Project and module are derived from cwd (git remote name, then settings.gradle[.kts] rootProject.name), so running it from elsewhere files the entry under the wrong project.
• Use python3. On macOS and most Linux distributions there is no python on PATH. On a Windows install where only python exists, swap the two.
• No third-party packages. Python 3.7+.

Quick Start

# Add entry (creates a separate .md file, tags auto-generated from the text)
python3 skills/kora-journal/scripts/kora_journal.py add "Global interceptor tagged with HttpServerModule never ran" \
  --context "Adding an API-key auth interceptor to a Kora 2.0 HTTP server" \
  --problem "Used @Tag(HttpServerModule.class); it compiled, the graph built, and the interceptor was never invoked" \
  --solution "2.0 collects global interceptors as @Tag(HttpServer.class) All<HttpServerInterceptor> in HttpServerModule.publicHttpApiRouter; retagged and added a test asserting 401" \
  --files skills/kora-http-server/SKILL.md

# Add entry with custom tags
python3 skills/kora-journal/scripts/kora_journal.py add "Carried ru.tinkoff.kora imports into a 2.0 service" \
  --context "..." --problem "..." --solution "..." --files ... \
  --tags kora1x migration di

# Search the journal by keywords (use AFTER reading references, BEFORE implementing)
python3 skills/kora-journal/scripts/kora_journal.py search "http interceptor auth" --limit 5

# Search by tags only (more precise)
python3 skills/kora-journal/scripts/kora_journal.py search "kora1x migration" --by-tags

# View recent entries of the current module
python3 skills/kora-journal/scripts/kora_journal.py list --limit 10

# Export pending entries from a date, across the whole store
python3 skills/kora-journal/scripts/kora_journal.py export --since 2026-08-01 --status pending

# Mark an entry as integrated after folding it into the skills
python3 skills/kora-journal/scripts/kora_journal.py integrate 2026-08-22_global-interceptor-tagged-with-httpservermodule-ne.md

# Check status
python3 skills/kora-journal/scripts/kora_journal.py status

Storage Structure

Shared location: ~/.kora-journal/ — one store for all projects, sessions, and Kora skill packages.

~/.kora-journal/
├── billing-service/                # Project name (git remote, else directory name)
│   └── billing-api/                # Gradle module (rootProject.name, else directory name)
│       ├── 2026-08-22_global-interceptor-tagged-with-httpservermodule-ne.md
│       ├── 2026-08-21_jdbc-config-section-still-named-db.md
│       ├── 2026-08-20_openapi-client-config-path-not-lower-camel.md
│       └── ...                     # Each entry is a separate file
├── another-project/
│   └── service-module/
│       └── ...
└── ...

Filename format: YYYY-MM-DD_slug-from-title.md (a repeated title on the same day gets _1, _2, …)

Why one shared store rather than one per Kora version:

• The store is keyed by project and module, not by framework version. A service mid-migration legitimately holds both 1.x and 2.0 entries; splitting them would cut one project's history in two.
• Entries written under the 1.x package stay valuable — most describe what an aspect, processor or config key actually does, which is still true, and the ones that describe a 1.x API are precisely the material you need when that API shows up in a 2.0 project.
• Both packages can be installed at once. A version-specific path would silently show a different journal depending on which one the agent happened to route through.
• The one real risk — applying a 1.x entry verbatim to 2.0 code — is handled by the kora: stamp and the kora1x tag, not by hiding the entries.

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, projects and Kora packages share one journal
• ✅ Survives project deletion

Git: the store lives in your home directory, outside every repository — there is nothing to .gitignore.

Scope of a Command

Every read command takes --scope:

search defaults to all on purpose: a mistake made in another service is exactly the one you want to find. Results outside the current module are printed as <project>/<module>/<file>.md, which integrate accepts verbatim.

Workflow

1. Before Implementing — Search First

Step 3 of the meta-skill's per-task procedure. Search before writing anything non-trivial:

python3 skills/kora-journal/scripts/kora_journal.py search "http interceptor auth" --limit 5

Hit → apply it, then integrate <entry-file>. Miss → continue, and expect to add an entry under R3.

2. During Session — Record the Mistake

When you realise you used Kora incorrectly:

python3 skills/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

Always use the CLI. Hand-writing a file into the store skips the slug, the front matter, the kora: stamp and the tags, so search and integrate will not see the entry properly.

3. Review Pending Work

# Last 10 pending entries of this module
python3 skills/kora-journal/scripts/kora_journal.py list --limit 10 --status pending

# Everything, everywhere
python3 skills/kora-journal/scripts/kora_journal.py list --scope all

4. Export for Integration

python3 skills/kora-journal/scripts/kora_journal.py export --since 2026-08-01 --status pending

5. Apply Changes to Skills

Review the exported entries and apply them to:

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

An entry whose Kora line is unset was written before the stamp existed, possibly against Kora 1.x — verify its claim against the 2.0 source before folding it into a 2.x skill.

6. Mark as Integrated

python3 skills/kora-journal/scripts/kora_journal.py integrate 2026-08-22_global-interceptor-tagged-with-httpservermodule-ne.md

Updates entry status: pending → integrated. Exits non-zero if the entry could not be resolved, and refuses any path outside ~/.kora-journal/.

Entry File Format

Each entry is a Markdown file with YAML front matter:

---
title: "Global interceptor tagged with HttpServerModule never ran"
date: 2026-08-22
project: billing-service
module: billing-api
author: dsudomoin
kora: "2.x"
tags: ["di", "http-server", "kora1x"]
---

# Global interceptor tagged with HttpServerModule never ran

**Date:** 2026-08-22
**Project:** billing-service
**Module:** billing-api
**Author:** dsudomoin
**Kora line:** 2.x

---

## Context

Adding an API-key auth interceptor to a Kora 2.0 HTTP server.

## Problem

Wrote `@Tag(HttpServerModule.class)` on the `HttpServerInterceptor`. It compiled and the graph
built — `HttpServerModule` still exists in 2.0 — but nothing looks interceptors up by it, so every
request went through unauthenticated.

## Solution

`HttpServerModule.publicHttpApiRouter` collects `@Tag(HttpServer.class) All<HttpServerInterceptor>`.
Retagged with `io.koraframework.http.server.common.HttpServer` and added a test asserting 401.

## Files Affected

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

---

## Metadata

- **Created:** 2026-08-22_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

--status values: pending, integrated, archived (search also takes all, its default). --scope values: module, project, all.

Tags System

Tags are auto-generated from the whole entry text (title + context + problem + solution) when you add an entry. The vocabulary is fixed and Kora-specific, so --by-tags stays precise:

When nothing matches, add says so and the entry is stored untagged — pass --tags to make it findable by tag.

Override auto-generated tags:

python3 skills/kora-journal/scripts/kora_journal.py add "Carried ru.tinkoff.kora imports into a 2.0 service" \
  --context "..." --problem "..." --solution "..." --files ... \
  --tags kora1x migration di

Search by tags (more precise than content search):

python3 skills/kora-journal/scripts/kora_journal.py search "kora1x" --by-tags

Common Pitfalls

Best Practices

1. Search first — step 3 of the per-task procedure, before you write the code
2. Add immediately — record right after solving, don't rely on memory
3. Be specific — exact annotation, exact config key, exact error message, exact files
4. Prefer the silent failures — a mistake the compiler caught is already self-correcting; one that left a green build is what the journal exists for
5. Use the status lifecycle — pending → integrated → archived
6. Export weekly — export --since YYYY-MM-DD --status pending
7. Integrate monthly — don't let pending entries accumulate beyond 20
8. Archive quarterly — clean up old integrated entries

See Also

• Journal Workflow — Detailed workflow
• Entry Template — Entry format template
• kora-v2 meta-skill — R3 and the silent-failure list