# Journal Entry Creator

> Create structured journal entries with YAML frontmatter, template-based sections, and compliance validation. Use when user asks to 'create journal entry', 'new journal', 'document [topic]', 'journal about [topic]', or needs to create timestamped .md files in YYYY/MM/ directories. Supports six entry types: general journal entries, troubleshooting sessions, learning notes, article summaries, ticket-refinement sessions, and ticket-kickoff sessions. Keywords: journal, documentation, troubleshooting, learning, article-summary, ticket-refinement, ticket-kickoff, YAML frontmatter, template schemas, validation.

- Skill: `pantheon-org/journal-entry-creator` (Agent Skill, multi-file: 31 files)
- Install (CLI): `npx skillmds@latest add pantheon-org/journal-entry-creator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/pantheon-org/journal-entry-creator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: pantheon-org (https://skillmd.com/u/pantheon-org)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/pantheon-org/journal-entry-creator

---


# Journal Entry Creator

Automate creation of structured journal entries with template schemas, frontmatter validation, and compliance checking.

## Mindset

Every entry is a durable, queryable record, not a scratch note: get the frontmatter, triple-synced dates, and structure right the first time so future search and tooling can rely on them. Know **when not to** use this skill: a throwaway note with no frontmatter needs no ceremony.

## Prerequisites

This skill is a companion to the `journal` CLI and is normally installed by it
(`pantheon-journal skill install`). Its features split into two tiers:

- **Self-contained** (no binary needed): interactive gathering, entry-type
  selection, entry authoring, and structural validation via the bundled
  `scripts/validate-journal-entry.sh`.
- **CLI-backed** (require the `journal` binary on `PATH`): corpus-wide tag lint
  (`pantheon-journal lint`) and any other `pantheon-journal` subcommand this skill references.

Before running any `journal ...` command, confirm the binary is present:

```bash
pantheon-journal --version
```

If it is missing, the skill was installed without its companion CLI. Install the
`journal` CLI (its release binary, or `cargo install`), then retry. Until then,
skip the CLI-backed steps; the self-contained workflow still applies.

## When to Use This Skill

Use journal-entry-creator when:
- **Documentation requirement**: User explicitly asks to "create journal entry", "document this", or "write about [topic]"
- **Structured output needed**: Standard journal workflows require YAML frontmatter, triple-sync dates, and template compliance
- **Multiple entry types**: Need to select between troubleshooting, learning, article summary, or general journal
- **Validation critical**: Entry must pass compliance checks before commit (automated validation available)

**Do NOT use for:**
- Quick markdown notes without frontmatter (use simple file creation instead)
- External documentation systems (Confluence, Notion) — this skill is for local .md files only
- Retrospective backfilling of frontmatter across many old entries: use `pantheon-journal backfill` for that one-pass batch repair instead

## Entry Type Selection

**Decision criteria:**
- **Problem resolution?** → Troubleshooting
- **New knowledge/skills?** → Learning  
- **External content summary?** → Article Summary
- **Fleshing out or amending a ticket (refinement prep, backlog grooming)?** → Ticket Refinement
- **Understanding a ticket before starting work on it (pull CoS/AC, spot gaps, build a work checklist and Proof of Work plan)?** → Ticket Kickoff
- **Otherwise** → Journal Entry

| User Intent Signals | Type | Template | Required Tag |
| -------------------- | ---- | -------- | ------------ |
| "error", "fix", "resolved", "incident" | Troubleshooting | `troubleshooting.yaml` | `troubleshooting` |
| "learned", "tutorial", "discovered" | Learning | `learning.yaml` | `learning` |
| URL/source, "read", "watched", "summarize" | Article Summary | `article-summary.yaml` | `article`/`video`/`podcast`/`talk` |
| "refine", "flesh out", "groom", "amend ticket" | Ticket Refinement | `ticket-refinement.yaml` | `ticket-refinement` |
| "pull the ticket", "kickoff", "start [ticket]", "what needs to happen", "work checklist", "proof of work" | Ticket Kickoff | `ticket-kickoff.yaml` | `ticket-kickoff` |
| General documentation, investigation | Journal Entry | `journal-entry.yaml` | (flexible) |

**Trade-off:** When intent is ambiguous, prefer the more specific type (Troubleshooting > Ticket Refinement > Ticket Kickoff > Learning > General).

**Ticket Refinement vs Ticket Kickoff:** Refinement rewrites an under-specified ticket's *description* (the ticket is the problem). Kickoff assumes the ticket is already implementation-ready and instead plans the work — a checklist and a Proof of Work plan (the work ahead is the subject). If a kickoff surfaces gaps serious enough to need rewriting, switch to — or first do — a Ticket Refinement.

## Template Schema System

**MANDATORY - READ BEFORE PROCEEDING:**

Before generating any entry, you MUST read the complete template schema file:

```bash
# Based on entry type selected, read ENTIRE file:
skills/journal-entry-creator/assets/templates/troubleshooting.yaml
skills/journal-entry-creator/assets/templates/learning.yaml
skills/journal-entry-creator/assets/templates/article-summary.yaml
skills/journal-entry-creator/assets/templates/ticket-refinement.yaml
skills/journal-entry-creator/assets/templates/ticket-kickoff.yaml
skills/journal-entry-creator/assets/templates/journal-entry.yaml
```

**Do NOT generate entries without loading the schema first.** The schema defines required sections, frontmatter fields, heading hierarchy, and validation rules.

**When to load references:**

- Load schema: ALWAYS before creating entry (mandatory)
- Load `compliance.md`: Only if validation fails and you need detailed rules
- Load `edge-cases.md`: Only for complex or unusual edge cases
- Load `example-*.md`: Only if user asks for examples or you need clarification on structure
- Do NOT load: `journal-command.md` (superseded by this skill)

## Domain-Specific Compliance Rules

Beyond standard markdown, this journal system enforces:

### Date Consistency (Triple Sync)

All three must match exactly:

1. Filename: `2025-02-24-topic.md` (slug lowercase-only)
2. Frontmatter: `date: 2025-02-24`
3. H1 title: `# Topic - February 24, 2025` (Month D, YYYY format)

### Location Hierarchy

File must be in `YYYY/MM/` directory matching its date:

- `2025-02-24-*.md` → Must be in `2025/02/`
- `2025-11-05-*.md` → Must be in `2025/11/`

### Single H1 Format

Exactly ONE H1 in the entire document with precise format:

```markdown
# [Title] - [Month D, YYYY]
```

**Not allowed:**

- Multiple H1 headings
- H1 without date
- Wrong date format (YYYY-MM-DD in H1)

### Tag Consistency

Tags must:

1. Match between frontmatter array and final `## Tags` section
2. Be lowercase with hyphens (not underscores, not camelCase)
3. Include entry type tag when required (troubleshooting, learning, article/video/podcast/talk)
4. Prefer the canonical vocabulary defined in the taxonomy (see below)

**Example:**

```yaml
tags:
  - troubleshooting
  - api-gateway
  - aws-lambda
```

Must match:

```markdown
## Tags

`troubleshooting` | `api-gateway` | `aws-lambda`
```

### Tag Taxonomy (Controlled Vocabulary)

Beyond tag *shape*, this system maintains a controlled tag *vocabulary* to keep
the corpus queryable and prevent tag sprawl. The vocabulary lives in a
`taxonomy.json` at the journal root (a generic default ships with the skill under
`assets/taxonomy.default.json`; its shape is documented in
`assets/schemas/taxonomy.schema.json`).

The taxonomy defines:

- `facets`: named groups of canonical tags (for example `type`, `tech`, `topic`).
- `aliases`: non-canonical spellings that collapse onto a canonical one (for
  example `teams` becomes `ms-teams`).
- `threshold`: how many times an unfaceted tag may appear before it is flagged.
- `ticketPattern`: the regex that marks issue-tracker keys, which are exempt.

When choosing tags for an entry, prefer a tag already listed in a facet, and
prefer a canonical spelling over a near-duplicate. Corpus-wide tag hygiene is
checked separately from single-entry validation by the CLI (requires the
`journal` binary; see Prerequisites):

```bash
pantheon-journal lint            # advisory: alias suggestions and unfaceted tags
pantheon-journal lint --strict   # non-zero exit on findings (for CI)
```

`lint` is advisory and never rewrites the taxonomy or an entry; it reports
candidates for a human to fold into `taxonomy.json`.

The corpus can also be indexed into a queryable NDJSON source of truth plus a
rendered markdown browse view (grouped by recent, month, type, tag, and ticket):

```bash
pantheon-journal index            # writes docs/journal-index.{ndjson,md}
pantheon-journal index --validate # check the committed index, do not regenerate
```

### Code Block Language Specifiers

ALL code blocks MUST have language identifiers. No bare triple backticks allowed.

**Valid:**

````markdown
```bash
git status
```
````

**Invalid:**

````markdown
```
git status
```
````

### Assets / Screenshots Convention

Each entry that includes screenshots or attachments MUST use an **entry-specific sibling directory**:

```text
YYYY/MM/YYYY-MM-DD-slug.md          ← entry file
YYYY/MM/YYYY-MM-DD-slug/assets/     ← entry assets (gitignored, local-only)
```

Reference assets in markdown with a relative path from the entry file:

```markdown
![Alt text](YYYY-MM-DD-slug/assets/NN-description.png)
```

**Why:** A shared `screenshots/` or `assets/` directory at the month level causes filename collisions
when multiple entries use the same numbering scheme (e.g. `01-cloudwatch-alarm.png`). Scoping assets
under the entry slug directory makes every path unique.

**Note:** The `assets/` directories are gitignored — screenshots are local-only. The markdown image
references are tracked in git as documentation of what evidence was captured.

### Proposed Ticket Description (Ticket-Refinement Entries)

Applies to ticket-refinement sessions: fleshing out or amending an issue-tracker ticket (refinement prep, backlog grooming, turning a one-line ticket into a refinement-ready one). Use the `ticket-refinement.yaml` type.

**HARD RULE: this skill NEVER edits the ticket directly.** The amended ticket content lives inside the journal entry as a ready-to-paste markdown block. Applying it to the tracker is a separate step the user explicitly confirms, performed outside this skill.

When an entry refines a ticket, you MUST:

1. Set `refinement_ticket: <KEY>` in the frontmatter (e.g. `refinement_ticket: TICKET-123`). Use this field, not `jira_ticket` — the deliverable is a ticket description, not a comment.
2. Add a `## Proposed Ticket Description` section holding the full amended description inside a fenced markdown block:

````markdown
## Proposed Ticket Description

Draft for TICKET-123 - review before applying; not yet applied to the ticket.

```markdown
**Summary:** <one-line summary>

**Background**

<full, self-contained amended ticket description>
```
````

Rules for the proposed description:

- It is a DRAFT and has NOT been applied. Lead with a `Draft for [TICKET] - review before applying; not yet applied.` line, and never write it to the tracker from this skill.
- It MUST sit inside a fenced code block with a language specifier so it copies verbatim and its inner headings do not become document headings (this keeps the single-H1 rule intact). Use a 4-backtick outer fence when the ticket content itself contains 3-backtick code blocks.
- It must be self-contained: a ticket reader has not seen the journal entry, so the description stands on its own.
- Follow your team's ticket-writing standard if one exists.
- If the work touches regulated or personal data, state the constraint and route final sign-off to the appropriate function.

The validator (`validate-journal-entry.sh`) enforces this: when `refinement_ticket` is present in frontmatter, a `## Proposed Ticket Description` section is required. It is a no-op when the field is absent, so other entries are unaffected.

### Ticket Kickoff (Understanding a Ticket Before Starting Work)

Applies to ticket-kickoff sessions: understanding an issue-tracker ticket before implementation, distinct from Ticket Refinement (kickoff plans work assuming the ticket is implementation-ready; it never rewrites the ticket description). Use `ticket-kickoff.yaml`. Setting `kickoff_ticket: <KEY>` makes five sections REQUIRED (enforced by the validator, no-op otherwise). Full requirements, examples, and the "never leave Open Questions blank" rule: [Ticket Kickoff Rules](references/compliance.md#ticket-kickoff-rules).

### Continuation Links (Multi-Entry Investigations)

Applies to ANY entry type when work spans more than one dated entry. Never fold a later day's narrative into an earlier entry inline — create a new dated entry and link both directions with `continues_from`/`continued_by` frontmatter so a reader landing on either finds the other. Validated bidirectionally, no-op when unset. Full frontmatter/banner/section requirements and the markdown pattern: [Continuation Links](references/compliance.md#continuation-links).

### Executive Summary (Optional, Any Entry Type)

Optional, at the author's discretion. Fixed placement: MUST be the H2 immediately after `## Session Overview`, before every other section — enforced by the validator, no-op when absent. Keep it short: problem, why it's non-trivial, options, ask.

## Success Criteria & Validation Rules

Entry is complete when ALL criteria are met:

**Critical violations (NEVER):**
- Using emojis, bare code blocks (without language), or skipping heading levels
- Creating entries without reading template schema first
- Proceeding with failed validation or overwriting files without confirmation

**Triple sync validation:**
- ✅ File location: `YYYY/MM/YYYY-MM-DD-slug.md` (or `YYYY/MM/YYYY-MM-DD-JIRA-TICKET-slug.md` for troubleshooting with ticket)
- ✅ YAML frontmatter with all required fields  
- ✅ Date consistency: filename = frontmatter = H1 title
- ✅ Tag consistency: frontmatter array = Tags section
- ✅ All required sections present per schema, including type-specific ones (`refinement_ticket`/`kickoff_ticket` sections; reciprocal `continues_from`/`continued_by` links; `## Executive Summary` immediately after `## Session Overview` if present)
- ✅ Validation script passes with zero errors
- ✅ Prettier formatting and markdownlint pass

## Four-Phase Workflow

### Phase 1: Interactive Gathering

**Principles (high freedom):**

- Be conversational and adaptive
- Extract meaningful keywords for slug generation
- Identify entry type from context clues
- Default to current date unless user specifies otherwise

**Key questions to ask:**

1. Topic/issue being documented
2. Entry type (or infer from context)
3. Date (default: today)
4. Type-specific context per table above

**Slug generation:** Extract 3-6 meaningful keywords (see Phase 3 for detailed rules)

### Phase 2: Schema Loading (MANDATORY)

**Low freedom - exact steps:**

1. Determine entry type from Phase 1
2. Read complete template schema file (troubleshooting.yaml, learning.yaml, article-summary.yaml, ticket-refinement.yaml, ticket-kickoff.yaml, or journal-entry.yaml)
3. Review required sections, frontmatter fields, and structure order
4. Do NOT proceed without schema loaded

**Fallback:** If schema file missing or unreadable, STOP and report error. Do not guess structure.

### Phase 3: Generation

**Medium freedom - guided by schema:**

1. Create directory if needed: `mkdir -p YYYY/MM`
2. Generate filename using slug principles below:
   - Troubleshooting with Jira ticket: `YYYY-MM-DD-JIRA-TICKET-slug.md` (e.g. `2026-04-07-proj-1234-verify-details-alarm.md`)
   - All other entries: `YYYY-MM-DD-slug.md`
3. Populate YAML frontmatter per schema requirements
4. Create metadata block with bold keys
5. Fill all required sections from schema in correct order
6. Add code blocks with language specifiers
7. Create Tags section matching frontmatter
8. Write file to correct location

**Slug generation principles:**

- Extract 3-6 meaningful keywords from topic/title
- Remove common words ("the", "a", "and", "for", "with", "to")
- **MUST be lowercase-only with hyphens** (NO uppercase/underscores)
- Target 30-50 characters for readability
- **Troubleshooting + Jira ticket:** prefix slug with the ticket ID in lowercase: `YYYY-MM-DD-proj-1234-slug.md`
- **Do NOT include the Jira ticket again in the slug** — it appears once as the prefix only
- Examples: `2026-04-07-proj-1234-verify-details-alarm`, `opencode-killed-process-fix`, `aws-bedrock-inventory`

### Phase 4: Validation & Formatting (LOW FREEDOM)

**Exact commands in sequence:**

```bash
# 1. Validate structure
bash skills/journal-entry-creator/scripts/validate-journal-entry.sh YYYY/MM/YYYY-MM-DD-slug.md

# 2. Format (only if validation passes)
npx prettier --write YYYY/MM/YYYY-MM-DD-slug.md

# 3. Lint and auto-fix
npx markdownlint-cli2 YYYY/MM/YYYY-MM-DD-slug.md --fix

# 4. Re-validate to confirm
bash skills/journal-entry-creator/scripts/validate-journal-entry.sh YYYY/MM/YYYY-MM-DD-slug.md
```

**If validation fails:**

1. Show specific errors to user
2. Fix automatically where safe (formatting, code block languages, heading hierarchy)
3. Ask user for clarification on content issues (missing sections, unclear context)
4. Re-run validation after fixes
5. Do NOT proceed to git commit if validation fails

## Edge Case Handling

**Common scenarios:** File exists, date mismatch, schema missing, validation failures, custom structure requests.

**Quick reference:**

- **File exists:** Ask to overwrite or suggest alternative filename
- **Date mismatch:** Confirm intended date, update all three locations
- **Schema missing:** STOP immediately, list available schemas
- **Validation fails:** Auto-fix formatting issues, ask user for content clarifications

**For detailed resolution strategies:** Load `skills/journal-entry-creator/references/edge-cases.md` only when encountering an unusual or complex edge case.

## Git Integration (Optional)

After successful validation, offer to commit:

```bash
git add YYYY/MM/YYYY-MM-DD-slug.md
git commit -m "Add journal entry: [Brief Description] (YYYY-MM-DD)"
```

**Commit message format:**

- Prefix: `Add journal entry:`
- Brief description (30-50 chars)
- Date in parentheses (YYYY-MM-DD)
- Example: `Add journal entry: OpenCode process fix (2025-02-24)`

## Anti-Patterns

### NEVER create entries without reading the template schema first

- **WHY**: guessing structure leads to validation failures and missing required sections.
- **BAD**: immediately write journal entry based on assumptions about structure.
- **GOOD**: `cat skills/journal-entry-creator/assets/templates/troubleshooting.yaml` first, review required fields, then generate.

### NEVER proceed with failed validation

- **WHY**: invalid entries break parsing tools and violate compliance rules.
- **BAD**: validation script shows 3 errors → ignore and commit anyway.
- **GOOD**: fix all validation errors (or ask user for clarification), re-run validation until passing, then commit.

### NEVER use bare code blocks without language specifiers

- **WHY**: bare triple backticks fail markdownlint and reduce syntax highlighting readability.
- **BAD**: ` ```\ngit status\n``` ` (no language).
- **GOOD**: ` ```bash\ngit status\n``` ` (explicit language).

### NEVER create date mismatches between filename, frontmatter, and H1

- **WHY**: triple sync requirement ensures consistency; mismatches cause directory placement errors and broken date queries.
- **BAD**: filename `2025-02-24-*.md`, frontmatter `date: 2025-02-25`, H1 `March 1, 2025`.
- **GOOD**: all three match exactly - `2025-02-24` in filename, `date: 2025-02-24` in frontmatter, `February 24, 2025` in H1.

### NEVER edit the ticket directly when refining it

- **WHY**: this skill produces a reviewable draft; applying changes to the tracker is a separate, user-confirmed step outside the skill.
- **BAD**: refine a ticket and push the edit straight to the issue tracker.
- **GOOD**: set `refinement_ticket` and put the amended content in a `## Proposed Ticket Description` fenced block; the user applies it separately.

### NEVER skip a required ticket-kickoff section or fold a later day's work into an old entry

- **WHY**: a kickoff entry's value is a complete, checkable record; a folded-in "Update (DD-MM-YYYY)" paragraph breaks the single-date H1 and buries current status.
- **BAD**: skip `## Open Questions & Gaps`; append today's continued work as a new paragraph in yesterday's entry.
- **GOOD**: set `kickoff_ticket` and populate all five required sections (`None identified` when nothing is open); for multi-day work, create a new dated entry and link both directions per "Continuation Links".

### NEVER place Executive Summary anywhere other than immediately after Session Overview

- **WHY**: a fixed position means a reader always finds it in the same place across every entry; the validator fails otherwise.
- **BAD**: add `## Executive Summary` after `## Context` or near the end of the document.
- **GOOD**: place it as the H2 immediately following `## Session Overview`, before every other section.

## References

### Template Schemas (assets/templates/)

- `journal-entry.yaml` - General purpose entries
- `troubleshooting.yaml` - Problem resolution sessions
- `learning.yaml` - Knowledge acquisition documentation
- `article-summary.yaml` - External content summaries
- `ticket-refinement.yaml` - Issue-tracker ticket refinement (amended ticket captured in-entry, never written to the tracker)
- `ticket-kickoff.yaml` - Issue-tracker ticket kickoff (CoS/AC, gaps, supporting info, work checklist, Proof of Work plan)

Load with relative paths: `skills/journal-entry-creator/assets/templates/[file]`

### Scripts (scripts/)

- `validate-journal-entry.sh` - Compliance validation (run before commit)

### References (references/)

- `compliance.md` - Detailed validation rules (load only if validation fails)
- `edge-cases.md` - Detailed edge case resolution strategies (load only for complex scenarios)
- `example-journal-entry.md` - Real entry example (load only if user asks)
- `example-with-frontmatter.md` - Frontmatter example (load only if needed)
- `journal-command.md` - Legacy workflow (superseded, do not use)