Reflect 3 session logs into topic memory files

New: gotchas-skills.md (non-ASCII frontmatter, per-profile skill dirs).
Updated: gotchas-bash.md (+((var++)) with zero), decisions.md (+python3
for JSON), process-lessons.md (+cat -A diagnostic).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

.reflection-state.json

@@ -1,7 +1,10 @@
 {
   "version": 1,
-  "last_run": "2026-03-12T22:16:10Z",
+  "last_run": "2026-03-16T22:19:21Z",
   "processed": {
-    "log/2026-03-13.111440.md": "01d9e37a3340506255d87e0100b33ef1"
+    "log/2026-03-13.111440.md": "01d9e37a3340506255d87e0100b33ef1",
+    "log/2026-03-17.095436.md": "253f75f7ae43fb2547cd3377afb8d3b2",
+    "log/2026-03-17.105314.md": "9c81013e9ab545527a363f525eff93e3",
+    "log/2026-03-17.110414.md": "5ad1a211737b604f33e31e9ce754be74"
   }
 }

MEMORY.md

@@ -3,7 +3,8 @@
 <!-- Thin index only — one-line descriptions linking to memory/ topic files -->
 
 ## Gotchas
-- [Bash Gotchas](memory/gotchas-bash.md) — `set -e` silent failures, grep flag parsing, `local` scope, binary detection with `file` command
+- [Bash Gotchas](memory/gotchas-bash.md) — `set -e` silent failures, `((var++))` with zero, grep flag parsing, `local` scope, binary detection with `file` command
+- [Skills Gotchas](memory/gotchas-skills.md) — Non-ASCII frontmatter silently breaks loading, per-profile independent skills directories
 
 ## Decisions
 - [Decisions](memory/decisions.md) — OpenSpec format, mandatory dryrun, `set -uo pipefail` policy, dirty-state definitions, skynet org hosting

memory/decisions.md

@@ -16,6 +16,10 @@ Read-only/reporting scripts use `set -uo pipefail` instead of `set -euo pipefail
 
 In `git-status-report`, repos with no remotes or detached HEAD are considered clean unless they have local changes. "(no remotes)" is only shown as annotation when the repo already has uncommitted changes.
 
+## Use python3 for JSON parsing in bash scripts
+
+Scripts that need to read JSON (e.g., `.reflection-state.json`) use inline python3 rather than jq or fragile bash string parsing. python3 is reliably available on target systems and handles edge cases (nested keys, unicode, null values) that bash alternatives struggle with.
+
 ## Project hosted under `skynet` org
 
 `small-scripts` lives in the `skynet` org on Gitea (`gitea.oreillyit.nz`) as an AI-focused project — specifically a testbed for agent-driven, spec-first development workflows.

memory/gotchas-bash.md

@@ -16,6 +16,10 @@ Using `local` in the main script body (e.g., inside a `for` loop that isn't wrap
 
 `output=$(cmd)` where `cmd` exits non-zero will trigger `errexit` before `rc=$?` on the next line executes. Use `output=$(cmd) && rc=$? || rc=$?` or `output=$(cmd) || true` to safely capture output from commands expected to fail.
 
+## `((var++))` with var=0 triggers `set -e` exit
+
+Arithmetic expressions like `((PASS++))` return the *pre-increment* value. When PASS=0, the result is 0 (falsy), which `set -e` treats as a failure and silently exits the script. Use `PASS=$((PASS + 1))` instead — assignments always succeed regardless of the computed value.
+
 ## `file` command marks shell scripts as "executable"
 
 The `file` command returns strings like "Bourne-Again shell script, Unicode text, UTF-8 text executable" for shell scripts. Grepping for `executable` to detect binaries will false-positive on text scripts. Instead, grep for `binary|image|archive` and additionally check that the output does NOT contain `text`.

memory/gotchas-skills.md

@@ -0,0 +1,9 @@
+# Skills Gotchas
+
+## Non-ASCII characters in YAML frontmatter silently prevent skill loading
+
+Claude Code skills with em dashes (`---` U+2014), smart quotes, or other non-ASCII in the YAML frontmatter `description` field will fail to load with "Unknown skill" — no error message, no warning. The body below frontmatter can contain any characters. Claude commonly generates em dashes, so this is a recurring risk. Always run `validate-skill` before committing a skill.
+
+## Each Claude profile has independent skills directories
+
+Skills symlinked into `~/.claude/skills/` are NOT available in other profiles (e.g., `~/.claude-octopus/skills/`). Each profile maintains a completely independent skills directory. The `CLAUDE_CONFIG_DIR` env var identifies the active profile at runtime — use `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/skills` in install scripts.

memory/process-lessons.md

@@ -8,6 +8,10 @@ Debugging `set -e` failures in scripts that aggregate data from multiple sources
 
 The spec → implement → test workflow caught real bugs during development (grep flag parsing, `local` keyword misuse, binary detection false positives). Writing tests that exercise dryrun against spec expectations is an effective pattern for this project.
 
+## Use `cat -A` to diagnose invisible character issues
+
+When a file looks correct but tooling rejects it, `cat -A` reveals non-printing characters (e.g., `M-bM-^@M-^T` for em dashes that appear identical to regular dashes). Essential for debugging YAML frontmatter, config files, and any context where encoding matters.
+
 ## Use `git diff --numstat` for binary detection instead of `file`
 
 The `file` command is unreliable for distinguishing binary from text files (marks shell scripts as "executable"). `git diff --numstat` shows `-` for binary files and is more reliable since git already has its own binary detection heuristics.