dot_files/dot_claude/CLAUDE.md

# Claude Memory

## Instructions
- **Memory MCP is the ONLY memory system.** All memories (facts, preferences, decisions, project context) MUST be stored and recalled via the `memory_store` / `memory_recall` MCP tools. Do NOT use the file-based auto-memory system (`~/.claude/projects/*/memory/`).
- **"remember X"**: Store via `memory_store` MCP tool immediately. For project-specific static info (commands, architecture), also update the project's `.claude/CLAUDE.md`.
- **Recalling**: Always use `memory_recall` MCP tool to search for relevant context before responding to non-trivial requests.
- **Skills/agents**: Create in `~/.claude/skills/` or `~/.claude/agents/`, sync via chezmoi, commit to dotfiles repo.

## Preferences

### Chezmoi Sync
When making changes to dotfiles (including Claude files in `~/.claude/`), sync with chezmoi **only if it is installed** (`command -v chezmoi`):
1. Sync with chezmoi:
   - `chezmoi add <file>` for new files
   - `chezmoi re-add <file>` for updated files
2. Commit the changes in the chezmoi source directory:
   - `cd $(chezmoi source-path) && git add -A && git commit -m "<descriptive message>"`
If chezmoi is not installed, skip the sync steps and just make the changes directly.

### Claude Plugins
When installing new Claude plugins or marketplaces, update these files:
- `~/.local/bin/sync-dotfiles-remote.sh` - add new marketplace/plugin install commands
- `~/.local/share/chezmoi/run_once_after_install-claude-plugins.sh` - add to chezmoi run_once script
Then sync and commit both to chezmoi.

### Cluster Health Checks
- **Source of truth**: `infra/scripts/cluster_healthcheck.sh` — always run this script for cluster healthchecks
- The `cluster-triage` agent and `cluster-health` skill both use this script
- When checking cluster health, prefer spawning the `cluster-triage` agent (which runs the script and investigates FAIL/WARN results) over running the script directly
- Any new health checks must be added to the script, not done ad-hoc

### Skills/Agents Sync
All Claude Code skills, agents, and hooks live in the **dotfiles repo** (`~/.local/share/chezmoi/dot_claude/`), synced via chezmoi.
- **Add new skill/agent**: Create in `~/.claude/skills/` or `~/.claude/agents/`, then `chezmoi add ~/.claude/skills/<name>` and commit
- **OpenClaw**: Init container clones dotfiles repo and runs `executable_openclaw-install.sh` on pod start — no manual sync needed
- **After modifying skills/hooks**: `chezmoi re-add ~/.claude/skills && cd $(chezmoi source-path) && git add -A && git commit -m "update skills" && git push`

## Planning Mode Behavior

When in plan mode (system-reminder says "Plan mode is active"), follow this enhanced workflow:

### Interviewing Phase (BEFORE any research)
- **Challenge the goal itself.** Ask "Why?" at least once. Question whether the stated goal is the right goal.
- **Surface assumptions.** What is the user assuming about the problem, the solution, or the constraints?
- **Propose alternatives to the entire approach.** Before researching how to do X, ask whether X is even the right thing to do.
- **Ask about prior art.** Has this been attempted before? Are there existing solutions?
- **Use AskUserQuestion aggressively** — batch 2-4 targeted questions per round.
- **Do NOT proceed to research until the goal is crystal clear and challenged.**
- Minimum: 2 rounds of questions before any subagent research. Exception: truly trivial tasks (single-file edits, typo fixes).

### Research Phase (subagent-heavy)
- **Spawn subagents liberally** — no cap. Use judgment on quantity based on complexity.
- **Research ALL paths**, not just the obvious one. For each viable approach, spawn an agent to investigate.
- For each path, research: implementation complexity, tradeoffs, existing solutions, edge cases, maintenance burden.
- **Always research existing code** in the workspace that might already solve part of the problem.
- **Always research external solutions** (libraries, patterns, prior art) before proposing custom code.
- After research completes, present findings as a comparison table of approaches with clear tradeoffs.

### Gap Elimination Phase (BEFORE writing final plan)
- List every unknown, assumption, and risk explicitly.
- For each unknown: either resolve it via research or ask the user.
- **The plan is not ready until there are zero unresolved unknowns.**
- Ask: "What could go wrong?" and "What am I missing?" before finalizing.

### Complexity Detection (auto-trigger)
For non-trivial tasks (multi-file changes, new features, architectural decisions, anything involving more than ~20 lines of code), automatically engage the full planning workflow above. Skip only for:
- Typo fixes, single-line changes, renames
- Direct "just do it" / "skip planning" instructions from user