Consolidate drifted journal templates (shared template vs develop/SKILL.md)

jbr870 commented

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

Owner

Problem

The journal entry format is defined in two places that have drifted:

_shared/procedures/journal-template.md (the canonical shared template):

## [timestamp] STRUGGLE: [brief title]

**Problem:** [what you were checking]
**Expected:** [what should have happened]
**Actual:** [what went wrong]
**Solution:** [what finally worked or what you concluded]
**Key insight:** [the thing you wish you'd known]

develop/SKILL.md (its own embedded journal format):

## [timestamp] STRUGGLE: [brief title]

**Problem:** [what you were trying to do]
**Expected:** [what should have happened]
**Actual:** [what went wrong]
**Attempts:**
1. [what you tried first, why it didn't work]
2. [what you tried next, why it didn't work]
**Solution:** [what finally worked]
**Key insight:** [the thing you wish you'd known before starting]
**Affected:** [library/framework/pattern name]

Differences:

develop adds Attempts (numbered list) and Affected fields that the shared template doesn't have
develop doesn't reference the shared template at all
DISCOVERY entries also differ: develop has Where: and Not in CLAUDE.md: fields; the shared template has Pattern: and Why it matters:

Why this matters

Anyone editing the schema has to remember to update both locations — silent drift guaranteed
A parser/extractor would need to handle both formats
Blocks the YAML frontmatter work (separate issue) — need one schema before adding structure

Proposed change

Make _shared/procedures/journal-template.md the single source of truth
Extend it to cover the dev-journal-specific entries (Attempts, Affected, Where, Not in CLAUDE.md) — either as additional optional fields on existing types, or as a separate DEV_STRUGGLE / DEV_DISCOVERY variant if dev journals genuinely need different shapes
Update develop/SKILL.md to reference the shared template instead of redefining the format inline (same pattern the validate skills use)
Grep for any other inline journal format definitions in the skills tree and consolidate

Decision needed during implementation

Whether dev journals and validation journals share entry types with optional fields, or have their own variants. Lean toward shared types with optional fields — the underlying purpose (capture struggles and discoveries) is the same.

Blocks / co-requires: YAML frontmatter for journal entries (separate issue) — both should land together so there's only one round of template editing.

## Problem The journal entry format is defined in two places that have drifted: **`_shared/procedures/journal-template.md`** (the canonical shared template): ``` ## [timestamp] STRUGGLE: [brief title] **Problem:** [what you were checking] **Expected:** [what should have happened] **Actual:** [what went wrong] **Solution:** [what finally worked or what you concluded] **Key insight:** [the thing you wish you'd known] ``` **`develop/SKILL.md`** (its own embedded journal format): ``` ## [timestamp] STRUGGLE: [brief title] **Problem:** [what you were trying to do] **Expected:** [what should have happened] **Actual:** [what went wrong] **Attempts:** 1. [what you tried first, why it didn't work] 2. [what you tried next, why it didn't work] **Solution:** [what finally worked] **Key insight:** [the thing you wish you'd known before starting] **Affected:** [library/framework/pattern name] ``` Differences: - `develop` adds `Attempts` (numbered list) and `Affected` fields that the shared template doesn't have - `develop` doesn't reference the shared template at all - DISCOVERY entries also differ: `develop` has `Where:` and `Not in CLAUDE.md:` fields; the shared template has `Pattern:` and `Why it matters:` ## Why this matters - Anyone editing the schema has to remember to update both locations — silent drift guaranteed - A parser/extractor would need to handle both formats - Blocks the YAML frontmatter work (separate issue) — need one schema before adding structure ## Proposed change 1. Make `_shared/procedures/journal-template.md` the single source of truth 2. Extend it to cover the dev-journal-specific entries (`Attempts`, `Affected`, `Where`, `Not in CLAUDE.md`) — either as additional optional fields on existing types, or as a separate `DEV_STRUGGLE` / `DEV_DISCOVERY` variant if dev journals genuinely need different shapes 3. Update `develop/SKILL.md` to reference the shared template instead of redefining the format inline (same pattern the validate skills use) 4. Grep for any other inline journal format definitions in the skills tree and consolidate ## Decision needed during implementation Whether dev journals and validation journals share entry types with optional fields, or have their own variants. Lean toward shared types with optional fields — the underlying purpose (capture struggles and discoveries) is the same. ## Related - Blocks / co-requires: YAML frontmatter for journal entries (separate issue) — both should land together so there's only one round of template editing.

jbr870 commented

2026-04-20 16:43:49 +00:00

Author

Owner

Addressed in branch chore/consolidate-journal-templates (commit 5370286).

Summary:

Extended _shared/procedures/journal-template.md with optional fields (Attempts, Affected, Where, Not in CLAUDE.md) and two COMPLETE variants (validation-style and dev-style)
develop/SKILL.md now references the shared template instead of redefining the format inline
Also consolidated the 5 <domain>-validate/SKILL.md files that inlined the same STRUGGLE/DISCOVERY/COMPLETE blocks — they now reference journal-template.md + their _shared/domains/<domain>.md issue-type definitions

Decision: went with shared types + optional fields (the lean in the issue). COMPLETE is the one exception — validation and dev COMPLETEs are genuinely different shapes, so both are documented in the shared template as variants.

Addressed in branch `chore/consolidate-journal-templates` (commit 5370286). **Summary:** - Extended `_shared/procedures/journal-template.md` with optional fields (`Attempts`, `Affected`, `Where`, `Not in CLAUDE.md`) and two COMPLETE variants (validation-style and dev-style) - `develop/SKILL.md` now references the shared template instead of redefining the format inline - Also consolidated the 5 `<domain>-validate/SKILL.md` files that inlined the same STRUGGLE/DISCOVERY/COMPLETE blocks — they now reference `journal-template.md` + their `_shared/domains/<domain>.md` issue-type definitions **Decision:** went with shared types + optional fields (the lean in the issue). COMPLETE is the one exception — validation and dev COMPLETEs are genuinely different shapes, so both are documented in the shared template as variants.

jbr870 referenced this issue from a commit

2026-04-20 16:43:58 +00:00

Consolidate journal templates to a single source of truth

jbr870 closed this issue

2026-04-20 16:43:58 +00:00

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 from a commit