jbr870/devwork-skills
1
0
Fork 0
Code Issues 2 Pull requests Projects Releases Packages Wiki Activity Actions

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

New issue
Closed
opened 2026-04-20 13:41:58 +00:00 by jbr870 · 1 comment
jbr870 commented 2026-04-20 13:41:58 +00:00
Owner
Copy link

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.
## 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
Copy link

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.
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
No results found.
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
jbr870/devwork-skills#2
No description provided.