Add YAML frontmatter to journal entries for machine-queryable structure #1

New issue

Closed

opened 2026-04-20 13:41:40 +00:00 by jbr870 · 0 comments

jbr870 commented

2026-04-20 13:41:40 +00:00

Owner

Problem

Dev journals and validation journals are the primary evidence source for learning-analysis (see closeout/procedures/learning-analysis.md). They will become more valuable as we move toward analyzing patterns across features, repos, and projects — not just within a single closeout.

The current format is markdown headers + bold-label fields:

## [timestamp] STRUGGLE: brief title

**Problem:** ...
**Expected:** ...
**Actual:** ...
**Attempts:**
1. ...
**Solution:** ...
**Key insight:** ...
**Affected:** ...

Strong implicit typing already exists (STRUGGLE, DISCOVERY, $ISSUE_TYPE, COMPLETE) and fields are reasonably consistent. But it's only parseable via regex or markdown AST traversal — brittle to format drift, and a renamed field (Affected → Component) breaks parsers silently.

Proposed change

Add a small YAML frontmatter block to each journal entry containing the structured/queryable fields. Keep the long-form prose fields (Attempts, narrative) as markdown.

Example for a STRUGGLE entry:

## 2026-04-19T14:32 STRUGGLE: Vue hydration mismatch on SSR

```yaml
type: struggle
affected: vue-3, ssr
attempts: 3
resolved: true
tags: [hydration, reactivity]
```

**Problem:** [...]
**Expected:** [...]
**Attempts:**
1. [...]
2. [...]
**Solution:** [...]
**Key insight:** [...]

Benefits:

Humans read fluent markdown in the issue thread / file
Machines query the YAML directly — no NLP, no regex
Schema is explicit, so additions/renames are visible diffs
Forward-compatible: when journals start syncing to remote issues, extraction stays trivial

Schema sketch (to be refined)

Per entry type, the YAML carries:

All entries: type (struggle | discovery | issue | complete), tags (free list)
STRUGGLE: affected, attempts, resolved
DISCOVERY: pattern_kind, where
$ISSUE_TYPE: severity, domain-specific fields (already parameterized via $ISSUE_FIELDS)
COMPLETE: items_checked, issues_found

Final schema decided during implementation. The narrative/long-form fields stay below the YAML as prose.

Files affected

_shared/procedures/journal-template.md — primary template
develop/SKILL.md — has its own embedded journal format (see related issue on consolidation)
All *-validate skills that reference the journal template

Out of scope

Building the extractor/parser itself (separate work, lives outside the skills repo)
Migrating existing journals (forward-only; old journals stay as-is)
Deciding where journals are stored on the remote (issue comments, child issues, etc.) — that's a separate decision

Depends on resolving the journal template drift (see related issue) — should be done first or in the same change so there's only one schema to update.

## Problem Dev journals and validation journals are the primary evidence source for `learning-analysis` (see `closeout/procedures/learning-analysis.md`). They will become more valuable as we move toward analyzing patterns across features, repos, and projects — not just within a single closeout. The current format is markdown headers + bold-label fields: ``` ## [timestamp] STRUGGLE: brief title **Problem:** ... **Expected:** ... **Actual:** ... **Attempts:** 1. ... **Solution:** ... **Key insight:** ... **Affected:** ... ``` Strong implicit typing already exists (`STRUGGLE`, `DISCOVERY`, `$ISSUE_TYPE`, `COMPLETE`) and fields are reasonably consistent. But it's only parseable via regex or markdown AST traversal — brittle to format drift, and a renamed field (`Affected` → `Component`) breaks parsers silently. ## Proposed change Add a small YAML frontmatter block to each journal entry containing the structured/queryable fields. Keep the long-form prose fields (`Attempts`, narrative) as markdown. Example for a STRUGGLE entry: ````markdown ## 2026-04-19T14:32 STRUGGLE: Vue hydration mismatch on SSR ```yaml type: struggle affected: vue-3, ssr attempts: 3 resolved: true tags: [hydration, reactivity] ``` **Problem:** [...] **Expected:** [...] **Attempts:** 1. [...] 2. [...] **Solution:** [...] **Key insight:** [...] ```` Benefits: - Humans read fluent markdown in the issue thread / file - Machines query the YAML directly — no NLP, no regex - Schema is explicit, so additions/renames are visible diffs - Forward-compatible: when journals start syncing to remote issues, extraction stays trivial ## Schema sketch (to be refined) Per entry type, the YAML carries: - **All entries:** `type` (struggle | discovery | issue | complete), `tags` (free list) - **STRUGGLE:** `affected`, `attempts`, `resolved` - **DISCOVERY:** `pattern_kind`, `where` - **$ISSUE_TYPE:** `severity`, domain-specific fields (already parameterized via `$ISSUE_FIELDS`) - **COMPLETE:** `items_checked`, `issues_found` Final schema decided during implementation. The narrative/long-form fields stay below the YAML as prose. ## Files affected - `_shared/procedures/journal-template.md` — primary template - `develop/SKILL.md` — has its own embedded journal format (see related issue on consolidation) - All `*-validate` skills that reference the journal template ## Out of scope - Building the extractor/parser itself (separate work, lives outside the skills repo) - Migrating existing journals (forward-only; old journals stay as-is) - Deciding where journals are *stored* on the remote (issue comments, child issues, etc.) — that's a separate decision ## Related - Depends on resolving the journal template drift (see related issue) — should be done first or in the same change so there's only one schema to update.

jbr870 referenced this issue

2026-04-20 16:44:01 +00:00

Dev journal path mismatch between /develop and learning-analysis/simplify-report #3

jbr870 referenced this issue

2026-04-20 19:28:27 +00:00

Drop SR-N identifiers from closeout artifacts and SREQ template #4

jbr870 referenced this issue

2026-04-20 19:37:19 +00:00

Consider grouping journals (and reports) under subfolders in the feature folder #5

jbr870 referenced this issue

2026-04-20 19:42:02 +00:00

Dev journal path mismatch between /develop and learning-analysis/simplify-report #3