Environment Memory
Overview
Trial-and-error against the same broken assumption — "maybe bash works this time" — wastes turns
and tokens without new information. Any OS, shell, or tool quirk discovered once should be usable
forever after, in every project, not just the one where it was found.
Core principle: a quirk discovered once should never be rediscovered by trial and error.
The file
~/.claude/craftsman-memory/environment-quirks.md — deliberately outside this plugin's own
install directory, so a plugin update never wipes it. Deliberately outside any single project's
memory folder too, since quirks like "hooks run via CMD.exe not bash on this machine" apply
everywhere, not just to the project where they were found.
Format: flat, append-only, one line per entry —
<symptom> → <fix> (discovered: <date>, context: <where>)
No YAML frontmatter, no index, no categorization — this file is meant to be read in full whenever
it's relevant, so keep it short and skimmable rather than structured for querying (token-cheap by
design).
Before retrying a failed command or approach
- Check
~/.claude/craftsman-memory/environment-quirks.md for a matching symptom before trying
the same thing a second way, or a different way that might hit the same underlying constraint
(e.g. "PowerShell syntax works where bash syntax silently no-ops" applies to any bash-syntax
attempt, not just the exact command that first failed).
- If a matching entry exists, apply its fix directly — don't re-verify from scratch unless the
context has genuinely changed (different machine, different Claude Code version).
After discovering a new quirk
- Confirm it's actually environment/tool-specific (OS, shell, PATH, tool version) and not a
one-off bug in the current task — this file is for durable facts about the machine/toolchain,
not task-specific notes (those belong in
KNOWN_ISSUES.md for the project instead).
- Append one line in the format above. Don't ask before appending to this file specifically —
unlike creating a new project file, this is pure append-only record-keeping with no
file-creation side effect the first time it's used organically; do ask before creating the file
itself if it doesn't exist yet, since that's a new file outside the current project.
Notion / Obsidian
- Obsidian: the whole
~/.claude/craftsman-memory/ folder is a valid Obsidian vault as-is (plain
markdown, no export step). Users can Open folder as vault on it to get search, backlinks, and
graph view over the quirks log while Claude Code keeps writing the same files. Nothing here needs
to change to support that — just keep the plain-markdown format intact.
- Notion: only mirror an entry to Notion when the user explicitly asks, or when closing out an
entry they flagged as important. Never mirror automatically — this file is checked frequently
and a network round-trip on every check would defeat the point of keeping it cheap.
1---2name: environment-memory3description: Use before retrying any command, tool, or approach that failed once, and immediately after discovering any OS/shell/tool-specific quirk — checks and updates a stable cross-project quirks file so failed approaches are never silently repeated.4---56# Environment Memory78## Overview910Trial-and-error against the same broken assumption — "maybe bash works this time" — wastes turns11and tokens without new information. Any OS, shell, or tool quirk discovered once should be usable12forever after, in every project, not just the one where it was found.1314**Core principle:** a quirk discovered once should never be rediscovered by trial and error.1516## The file1718`~/.claude/craftsman-memory/environment-quirks.md` — deliberately outside this plugin's own19install directory, so a plugin update never wipes it. Deliberately outside any single project's20memory folder too, since quirks like "hooks run via CMD.exe not bash on this machine" apply21everywhere, not just to the project where they were found.2223Format: flat, append-only, one line per entry —24```25<symptom> → <fix> (discovered: <date>, context: <where>)26```2728No YAML frontmatter, no index, no categorization — this file is meant to be read in full whenever29it's relevant, so keep it short and skimmable rather than structured for querying (token-cheap by30design).3132## Before retrying a failed command or approach33341. Check `~/.claude/craftsman-memory/environment-quirks.md` for a matching symptom before trying35 the same thing a second way, or a different way that might hit the same underlying constraint36 (e.g. "PowerShell syntax works where bash syntax silently no-ops" applies to any bash-syntax37 attempt, not just the exact command that first failed).382. If a matching entry exists, apply its fix directly — don't re-verify from scratch unless the39 context has genuinely changed (different machine, different Claude Code version).4041## After discovering a new quirk42431. Confirm it's actually environment/tool-specific (OS, shell, PATH, tool version) and not a44 one-off bug in the current task — this file is for durable facts about the machine/toolchain,45 not task-specific notes (those belong in `KNOWN_ISSUES.md` for the project instead).462. Append one line in the format above. Don't ask before appending to this file specifically —47 unlike creating a new project file, this is pure append-only record-keeping with no48 file-creation side effect the first time it's used organically; do ask before creating the file49 itself if it doesn't exist yet, since that's a new file outside the current project.5051## Notion / Obsidian5253- Obsidian: the whole `~/.claude/craftsman-memory/` folder is a valid Obsidian vault as-is (plain54 markdown, no export step). Users can **Open folder as vault** on it to get search, backlinks, and55 graph view over the quirks log while Claude Code keeps writing the same files. Nothing here needs56 to change to support that — just keep the plain-markdown format intact.57- Notion: only mirror an entry to Notion when the user explicitly asks, or when closing out an58 entry they flagged as important. Never mirror automatically — this file is checked frequently59 and a network round-trip on every check would defeat the point of keeping it cheap.
ccplugins