0c068ffd8b
Updated: gotchas-skills.md (+$VAR paths, $() subshells, relative path resolution), decisions.md (+CLAUDE_PROJECT_ROOT, settings.yaml relative paths), process-lessons.md (+research history before building validators). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1.8 KiB
Process Lessons
Always run git-status-report at session start
Previous sessions may leave uncommitted work. Running git-status-report (or checking git status) at session start catches this pattern before it compounds.
Use plan mode for architectural tasks
Plan mode (Shift+Tab twice) works well for designing systems before implementing. Explore existing patterns, design the architecture, get approval, then execute. Implementation is straightforward when the plan is thorough.
PostToolUse exit code 2 feeds errors back to Claude
Exit code 2 from a PostToolUse hook sends stderr content back to Claude as feedback without blocking the edit. Exit 0 = silent success. Exit 1 = hard block.
Agent-type hooks are read-only
Hooks with type: "command" cannot use Edit/Write tools. Lint fixing from hooks must happen via the Agent tool subagent, not directly in hooks.
All hooks in a matcher array run in parallel
Multiple hooks registered for the same matcher execute concurrently, not sequentially. Design hooks to be independent.
SSH key for ai_enablement is password-protected
Needs ssh-agent loaded before git push to Gitea. If push hangs, check that the key is added to the agent.
Research full failure history before building validators
When building a tool that detects known problems (like validate-skill), first research all historical failures across session logs and git commits. This reveals non-obvious patterns — e.g., $HOME (not just ${HOME}) being rejected by permission checkers, which wouldn't be found from docs alone. The upfront research investment pays off in comprehensive coverage.
Batch parallel file creation for efficiency
Creating many independent files in a single Write batch (e.g., 11 best-practices files at once) is significantly faster than sequential creation.