claude-foundations/memory/process-lessons.md

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.

Evaluate the right home for new content before building

Before creating a new system or document, discuss where it belongs conceptually (e.g., MEMORY.md vs SPEC vs dedicated catalog). Different content types have different lifecycles — accumulated learnings vs authoritative maintained maps vs behavioral contracts. Picking the wrong home means future maintenance friction.

Add SSH-authenticating user as collaborator when creating repos via API

When creating Gitea repos via API token (e.g., ai_admin), the SSH alias may authenticate as a different user (e.g., cluster-administrator). Always add the SSH user as admin collaborator via API before pushing.

Use background agents for parallel independent research

When researching multiple topics that don't depend on each other, launch background subagents simultaneously. Both API design and LLM security research completed in ~5 minutes each, producing structured output with citations. Review results as they complete. Don't duplicate research work the subagent is doing.

Include more surrounding context when Edit tool matches are ambiguous

The Edit tool fails if old_string matches multiple locations. When editing files with repeated patterns (like FUTURE.md items that all end with "Depends on: M9"), include unique surrounding lines (a heading, the preceding paragraph) to disambiguate. Don't use replace_all: true as a workaround — it changes all instances.

Best-practices repo is separate from claude-foundations

Best practices live in skynet/best-practices (cloned at ~/dev/claude/projects/best-practices/). ~/dev/claude/BESTPRACTICES.md is a symlink to its index. context-load doesn't show the best-practices directory in the tree — remember it exists when working on best practices topics.

Keep skill and script symlinks in sync across all profiles

Every profile (~/.claude, ~/.claude-octopus, ~/.claude-oreillyit) is independent — missing a symlink in one profile breaks that profile's slash commands without affecting others. When adding or renaming a skill or skill-helper script, verify symlinks exist in every active profile. Example that bit: ~/.claude-octopus/skills/switch-mode symlink was missing while ~/.claude/skills/switch-mode worked. Audit with ls -la ~/.claude*/skills/ when touching skill layout.

Verify subagent output paths use the project's absolute path

When /log (or any skill that spawns a subagent) writes files on the project's behalf, always verify the first real run that the subagent wrote to the project's absolute memory/log/ path, not a relative path resolved from an unexpected cwd. A relative path silently lands in the wrong directory and the log looks missing.