# TODO: Top 10 Improvements

Prioritised by impact and effort. Each item references its detailed topic file in `improvements/`.

## 1. ~~Configure PostToolUse auto-formatting hook~~ → DONE
**Impact: High | Effort: Low** ✅
Composable multi-language linting system implemented. Canonical formatters in `formatters/` (py, sh, ts, sql, json + symlinks for js, yaml, md). PostToolUse dispatcher hook with checkpoint/revert. Pre-commit hook. Setup scripts. `/linter` skill for auditing.
See: [hooks-and-automation.md](improvements/hooks-and-automation.md)

## 2. ~~Create global `~/.claude/CLAUDE.md`~~ → DONE (parent symlink)
**Impact: High | Effort: Low** ✅
`~/dev/claude/CLAUDE.md` symlinked to `claude-foundations/CLAUDE.md`. All projects under `~/dev/claude/` inherit it automatically. Used parent-directory scope (option B) rather than global `~/.claude/` scope.
See: [global-configuration.md](improvements/global-configuration.md)

## 3. Configure PreToolUse security hook
**Impact: High | Effort: Low**
Block writes to secrets files, `.env`, lockfiles, and destructive commands. Deterministic protection vs. hoping Claude remembers the CLAUDE.md rule.
See: [hooks-and-automation.md](improvements/hooks-and-automation.md)

## 4. Install Context7 MCP server
**Impact: High | Effort: Medium**
Real-time, version-specific documentation for Helm charts, Kubernetes APIs, and any library. Eliminates knowledge-cutoff guesswork — particularly valuable for cluster-bootstrap.
See: [mcp-servers.md](improvements/mcp-servers.md)

## 5. Build `/catchup` skill
**Impact: Medium | Effort: Low**
Reads git diff, changed files, and relevant memory when resuming work. Automates the manual "what changed since last session?" flow.
See: [skills-and-progressive-disclosure.md](improvements/skills-and-progressive-disclosure.md)

## 6. Build `/validate` skill
**Impact: Medium | Effort: Low**
Codifies the "validate before deploying" principle into a single command. Runs helm template, kustomize build, linting as appropriate. Prevents deploy-crash-fix cycles.
See: [skills-and-progressive-disclosure.md](improvements/skills-and-progressive-disclosure.md)

## 7. Install Language Server plugin
**Impact: High | Effort: Medium**
`boostvolt/claude-code-lsps` gives Claude real-time types, go-to-definition, and find-references. "The single biggest productivity gain" per community consensus.
See: [plugins-and-language-servers.md](improvements/plugins-and-language-servers.md)

## 8. ~~Add PreCompact transcript backup hook~~ → DONE
**Impact: Medium | Effort: Low** ✅
Implemented in `~/.claude/hooks/pre-compact-backup.sh`. Fires on both auto and manual compaction. Reads `transcript_path` from stdin JSON, copies to `~/.claude/transcript-backups/` with timestamp, prunes backups older than 30 days.
See: [hooks-and-automation.md](improvements/hooks-and-automation.md)

## 9. Prune and restructure project CLAUDE.md
**Impact: Medium | Effort: Medium** — UNBLOCKED (item 2 complete)
After creating the global file (item 2), prune the project CLAUDE.md. Move discoverable info out, rewrite prohibitions as positive guidance, add verification commands section, put critical rules at the top.
See: [claude-md-refinements.md](improvements/claude-md-refinements.md)

## 10. Adopt Plan Mode as default workflow — DONE (used this session)
**Impact: High | Effort: Zero**
Use Shift+Tab twice before any non-trivial task. Iterate on the plan before executing. Boris from Anthropic says this "easily 2-3x's results." No tooling needed — just a habit change.
See: [planning-and-workflow.md](improvements/planning-and-workflow.md)

---

## Completed This Session (2026-03-12)

- **Best-practices library** — 11 topic files + BESTPRACTICES.md index extracted from cluster-bootstrap and custom-claude-skills. Auto-loaded by `context-load` per project.
- **Knowledge distillation pipeline** — Three new skills (`/log`, `/reflect-logs`, `/distill-best-practices`) with settings.yaml, state tracking, log pruning, and staleness detection.
- **Parent CLAUDE.md symlink** — `~/dev/claude/CLAUDE.md` → claude-foundations, all projects inherit automatically.
- **PreCompact transcript backup hook** — `~/.claude/hooks/pre-compact-backup.sh` with auto+manual matchers.
- **claude-foundations Gitea repo** — Created under skynet org, pushed.

## Completed (2026-03-13)

- **PostToolUse auto-formatting hook** — Composable multi-language linting system: 5 formatter scripts + 3 symlinks, PostToolUse dispatcher with git-blob checkpoints, pre-commit hook, setup scripts, `/linter` skill, `best-practices/linting.md`.