logmind: log decisions as you work

Applies when the project has .logmind/config.yml or an AGENTS.md mentioning logmind. Log a decision before writing non-trivial code.

When to log

• An architectural or design choice
• A choice between alternatives
• Significant new code (> 20 lines or a new module)
• A non-obvious change to existing functionality
• Adding or removing a dependency
• A security or performance decision

When in doubt, log it — an entry is cheap; recovering the context later is not. But don't log every tiny edit: the 20-line rule is a guideline; use judgement.

logmind log "Use PostgreSQL" -r "Need ACID + joins" -a "MongoDB" -a "SQLite" -i "Pooling"

logmind log IS the commit primitive — no manual git around it

One invocation replaces git add + git commit. This skill describes logmind v1.2.0, the latest release; logmind version shows yours.

1. Appends to docs/decisions-branches/<sanitized-branch>.md on a feature branch (decisions.branch_aware, on by default) — one file per branch, append-only. On the default branch, a detached HEAD or a non-git directory it appends to docs/decisions.md instead. logmind log routes this, you don't.
2. Stages the whole working tree (--stage all, the default) so the decision and its code land in one commit — don't git add first. --stage scoped stages only the decision file when you have unrelated WIP you don't want swept in.
3. git commit with message logmind: <decision>. It does not push — git.auto_push is in the config but v1.2.0 never reads it. Run git push yourself.
4. Link-checks the markdown. On findings it prints an advisory; in a terminal it offers up to three fix-and-recheck tries, and --no-interactive (or piped stdin) skips the prompt and exits 0. The prompt path exits 1 on q or after three failed rechecks. The commit has landed either way.

logmind log does not regenerate the derived docs — see below. After it you owe only the push.

Enforcement: a local hook and a PR gate

• The pre-commit hook (logmind check-decisions) blocks (exit 1) a sizeable commit with no decision-file update. It never reads [skip-logmind]; its escape is git commit --no-verify.
• logmind init also installs check-decisions.yml, a PR gate on 20+ non-doc changed lines. It honors [skip-logmind] in the PR title only.
• In a commit subject, [skip-logmind] only makes the commit-msg hook echo a notice; nothing else reads it.

Reading prior context

Before non-trivial work, read in order:

1. docs/timeline.md — the generated union of decision entries across every branch, brief by default (first and last entry per month; logmind timeline --full prints every one).
2. docs/decisions-branches/<your-branch>.md if present — earlier decisions on this branch, in full.
3. docs/decisions.md and docs/decisions-archive.md — default-branch decisions; grep them for a term before re-deciding it.
4. docs/file-structure.md — project tree, capped at depth 2 by default (--max-depth N on logmind file-structure / logmind tree; 0 = unbounded).

Derived docs are generated — never hand-edit them

docs/timeline.md and docs/file-structure.md are computed from sources (the decision files above; a tree walk). Edit the sources instead.

regen-timeline.yml regenerates both on every PR. If they are stale it pushes the fix to the branch when LOGMIND_AUTO_REGEN_PAT is set; with no PAT, or on a fork PR, it fails red with Stale derived docs. The fix is regeneration, not a hand edit and not a copy from another branch:

logmind timeline --write docs/timeline.md
logmind file-structure --write docs/file-structure.md

Commit both. Add --check to either for a CI exit status without writing. The same regeneration resolves a merge conflict in either file: re-run it, never pick a side. It reads only your checkout's sources, so there is no base or tip copy to choose between.

Parallel-PR merges

Two PRs that both run logmind log don't conflict on the derived docs: logmind init installs a .gitattributes merge-driver block, the per-clone git config defining the drivers, and a .git/hooks/post-merge sweep that regenerates what the driver missed (unstaged — the next logmind log picks it up); logmind doctor reports drift on all three. Client-side only — it can't help a server-side merge.

Authoring skills — logmind skill …

For skills in your own project (.claude/skills/<name>/SKILL.md): new scaffolds; test validates frontmatter + structure; bench measures per-call token cost, suggests trims, buckets by loaded cost (tight / typical / verbose / over-budget); audit reports each local SKILL.md's bytes, decision-mentions and staleness, flagging ghost (loaded every context, author never iterates) and aging (untouched 90+ days) skills; suggest --since 30d drafts a candidate-skill issue from tokens repeated across decisions. Pair with clud-bug usage --health (loads vs. citations on real PRs).

Local and read-only against remotes except push: without --dry-run it clones the catalog, pushes a branch, and opens a real pull request the moment you run it — no confirmation prompt. Run logmind skill push <name> --dry-run first, every time. Nomination isn't publication: the catalog's editor gate decides, and can say no. suggest is also not local by default: with ANTHROPIC_API_KEY set it sends pattern candidates and evidence to api.anthropic.com; pass --no-llm.

Setup and health

brew install thrillmade/tap/logmind # or: curl -fsSL https://logmind.dev/install.sh | bash
logmind init   # scaffolds docs/, AGENTS.md, workflows, merge drivers, hooks
logmind doctor # confirm clean install

logmind init --with-skdd accepts the flag but currently defers — it prints a note to run npx clud-bug@latest init yourself. Run them separately.

logmind doctor flags stale workflow templates, stale hooks, merge-driver drift and an outdated AGENTS.md block-version, exiting non-zero on drift so it's CI-pluggable (--json for scripts, --exit-zero for informational runs). It has no clud-bug probe, and its installed-vs-latest version line is not reliable in v1.2.0 — don't read it as "up to date".

Don'ts

• Don't write the decision after the fact in past tense for trivial code.
• Don't reword a decision someone else already logged — link or extend it.
• Don't bypass the auto-commit (--no-commit) unless the project's branch protection requires it.

Cross-references

• token-frugal-tooling — token-frugal defaults for agent sessions.
• clud-bug-collaboration — the review half.