Journalist

Capture a concise, useful journal entry about the current session. The journal is local/private by default and lives under .journals/.

Layout

Use this repo-local structure:

.journals/
  index.md
  <date>/
    <date>_<topic-slug>_<title-slug>/
      assets/
      <date>_<topic-slug>_<title-slug>.md

Example: .journals/2026-06-13/2026-06-13_repo-tooling_setup-repo-skill/2026-06-13_repo-tooling_setup-repo-skill.md.

Entry Rules

• Do not record secrets, credentials, tokens, private keys, or sensitive personal data.
• Keep entries short, but preserve important context, decisions, evidence, links, and follow-ups.
• Support development journals, research journals, debugging notes, and design notes; do not force every entry into a development-only template.
• Use assets only when they materially help. Store them under the entry's assets/ directory and link with relative paths.
• If an entry for the same date, topic, and title already exists, update it in place and refresh updated_at; otherwise create a new entry.

Topic Selection

1. Read .journals/index.md if present, then scan journal frontmatter if needed.
2. Reuse an existing kebab-case topic when it fits the session.
3. Create a new kebab-case topic when no existing topic fits.
4. Ask the user only when multiple existing topics are plausible and the choice matters.

Entry Template

Use YAML frontmatter exactly like this:

---
created_at: <ISO-8601 timestamp>
updated_at: <ISO-8601 timestamp>
title: <short title>
topic: <kebab-case topic>
brief: <2-3 sentence summary>
---

## Notes

<Short narrative, bullets, research observations, decisions, links, or embedded tables/plots as appropriate.>

## Follow-ups

- <Open question or next action, if any.>

Adjust body sections to fit the session. Research entries may include tables, plots, quotes, methods, or findings inline instead of Notes/Follow-ups when that reads better.

Index And Query Scripts

Use this skill's bundled scripts; do not copy them into .journals/:

• scripts/update_journal_index.py <repo-root> recompiles .journals/index.md from entry frontmatter.
• scripts/query_journals.py <repo-root> [--topic TOPIC] [--date DATE] [--entry ENTRY] [--text TEXT] [--full] searches entries.

After writing or updating an entry, always run update_journal_index.py.

Index Format

The generated index is human-oriented, grouped by topic, and sorted by topic then newest entry first. It includes each entry's date, title, brief, and relative path.

Example:

# Journal Index

Generated from journal entry frontmatter.

## Repo Tooling

- **2026-06-13** [Setup Repo Skill](.journals/2026-06-13/2026-06-13_repo-tooling_setup-repo-skill/2026-06-13_repo-tooling_setup-repo-skill.md)
  - Updated repo setup defaults and non-destructive editing rules.

Setup Note

If .journals/ is not gitignored, add .journals/ to .gitignore without removing or rewriting existing ignore rules.