environment-memory

1# Environment Memory
2 
3## Overview
4 
5Trial-and-error against the same broken assumption — "maybe bash works this time" — wastes turns
6and tokens without new information. Any OS, shell, or tool quirk discovered once should be usable
7forever after, in every project, not just the one where it was found.
8 
9**Core principle:** a quirk discovered once should never be rediscovered by trial and error.
10 
11## The file
12 
13`~/.claude/craftsman-memory/environment-quirks.md` — deliberately outside this plugin's own
14install directory, so a plugin update never wipes it. Deliberately outside any single project's
15memory folder too, since quirks like "hooks run via CMD.exe not bash on this machine" apply
16everywhere, not just to the project where they were found.
17 
18Format: flat, append-only, one line per entry —
19```
20<symptom> → <fix> (discovered: <date>, context: <where>)
21```
22 
23No YAML frontmatter, no index, no categorization — this file is meant to be read in full whenever
24it's relevant, so keep it short and skimmable rather than structured for querying (token-cheap by
25design).
26 
27## Before retrying a failed command or approach
28 
291. Check `~/.claude/craftsman-memory/environment-quirks.md` for a matching symptom before trying
30   the same thing a second way, or a different way that might hit the same underlying constraint
31   (e.g. "PowerShell syntax works where bash syntax silently no-ops" applies to any bash-syntax
32   attempt, not just the exact command that first failed).
33…