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

1. 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).
2. 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