6.2 KiB
name, description
| name | description |
|---|---|
| tag-entries | Retroactively tag existing entries in `./docs/JOURNAL.md` (the same file `init-entry` writes to) by reading each untagged entry, deciding whether a coherent theme is present, and inserting `[name](tag://name)` links directly under the timestamp heading. Use when the user invokes /tag-entries or asks to "tag the journal", "go back and tag entries", "add tags to old entries", or similar. Conservative by default — entries without a clear theme stay untagged. |
Tag existing journal entries
A one-shot pass over ./docs/JOURNAL.md that adds tag lines under entry headers where a coherent theme is obvious. Tags are conditional: most entries should stay untagged. The aim is to make a future grep across the journal useful, not to label every entry.
The journal is append-only for body content. Adding a tag line under an existing header is allowed because tags are metadata the entry was eligible for at write time but didn't get. Never edit body prose, reorder entries, or change timestamps.
Format reminder
Each entry looks like:
## YYYY-MM-DD HH:MM
[github](tag://github) [postgres](tag://postgres)
<body prose>
- Tag line sits directly under the timestamp heading — no blank line between header and tags, then one blank line before the body.
- Tags are markdown links with the
tag://URI scheme:[name](tag://name). Multiple tags are space-separated on one line. - Label and URI value are usually the same word; differ only with a real reason (e.g.
[GitHub Actions](tag://github)).
Step 1 — Locate the journal
From the current working directory:
- If
./docs/JOURNAL.mdexists → continue. - Otherwise → stop and tell the invoker no journal exists yet. Do not create one. This skill only retro-tags;
/init-entryis the entry point for new journals.
Step 2 — Parse entries and existing tags
Read the file. Walk it from top to bottom and extract:
- Each entry: header line (
## YYYY-MM-DD HH:MM), the optional tag line if present, and the body up to the next##header or EOF. - The set of tag URIs already in use anywhere in the file (e.g.
postgres,github,incident-2026-04). This is the existing tag vocabulary.
Skip entries that already have a tag line. Their author already made the call. Don't second-guess, don't add to them, don't reorder them.
Step 3 — Propose tags for each untagged entry
For each untagged entry, decide whether a coherent theme is present. The bar is high:
Tag when the entry is centrally about a specific named thing that could plausibly recur — a tool (postgres, github), a subsystem (auth, worker-pool), a recurring concern (flaky-tests, oncall), a discrete incident (incident-2026-04-29), or a project / workstream that spans multiple entries.
Don't tag when the entry is a passing thought, a one-off observation, a meta note about the journal itself, or touches several topics without a center of gravity. "It mentions Postgres in one sentence" is not enough — the entry has to be about Postgres.
Reuse existing tags first. If the existing vocabulary contains postgres and the new entry is about Postgres, use postgres — don't invent pg or postgresql. Only mint a new tag when nothing in the existing vocabulary fits.
New tag conventions:
- Lowercase slug, hyphens for spaces (
worker-pool, notworker_poolorworkerPool). - Singular over plural (
migration, notmigrations) unless the plural is the natural name. - Specific over generic (
postgresbeatsdatabase;oauth-callbackbeatsauth) — but only if the specificity is justified by the entry's actual focus. - 1–3 tags per entry is the typical range. If you find yourself reaching for a 4th, the entry probably doesn't have a single coherent theme and should stay untagged.
If an entry has no clear theme, leave it untagged. Restraint is the point.
Step 4 — Show the plan and wait for confirmation
Before writing anything, present the proposal as a compact table or list. For each entry that would change:
- Timestamp.
- Proposed tags.
- A short (≤ 12 word) reason — what theme you saw.
Also list, separately, any new tags that would be added to the vocabulary (i.e. not already in use elsewhere), so the invoker can spot inconsistent naming before it lands.
Wait for explicit confirmation. The invoker may:
- Approve as-is.
- Edit the proposed tags for specific entries.
- Tell you to drop tags from specific entries (leave them untagged).
- Tell you to remint a new tag using a different name.
Apply their feedback and re-show only if the changes are non-trivial. Otherwise proceed.
Step 5 — Apply
Edit ./docs/JOURNAL.md in place. For each approved entry:
- Insert the tag line on the line directly after the
## YYYY-MM-DD HH:MMheader. - Ensure exactly one blank line between the tag line and the body.
- If the entry currently has a blank line between header and body, replace that blank line with the tag line followed by a blank line — net effect: tag line where the blank line was, blank line after.
Do not touch:
- Headers, timestamps, or entry order.
- Body prose, including whitespace inside the body.
- Entries that already had a tag line.
- The file's top-of-file preamble (the
# Journalheader and the convention note).
Use Unix line endings, no trailing whitespace, no emojis.
Step 6 — Report
One short summary:
- Path to the file.
- How many entries were tagged, how many were left untagged on purpose.
- The list of new tags added to the vocabulary, if any.
Stop there.
Hard rules
- Never edit body prose. The journal is append-only for content. Tag lines are the only retro-edit allowed.
- Never reorder, merge, split, or delete entries.
- Never re-tag entries that already have a tag line. The author already decided.
- Never invent themes. If nothing themes-up cleanly, leave the entry untagged. Most entries should stay untagged.
- Reuse existing tags before minting new ones. Inconsistent vocabulary is worse than no tags.
- No emojis. No backdating. No new headers or sections.
- Don't volunteer to do anything else — don't propose an index, a tag glossary file, a TOC, or summaries. The journal stays text-only.