# 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.