Files

Paul O'Reilly e94417b896 Add best practices, hooks, memory files, and scripts from recent sessions

Includes: spec-driven and test-driven development best practices,
reproduce-before-fixing debugging workflow, require-plan-file hook,
find-project-root script, session logs, memory files for decisions/
gotchas/process-lessons, and updates to existing best practice topics.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

2026-03-17 09:47:47 +13:00

2.5 KiB

Raw Blame History

Session Log — 2026-03-15

Summary

Fixed the /distill-best-practices skill which was broken due to hardcoded and relative paths in !command`` blocks. Replaced all paths with CLAUDE_PROJECT_ROOT env var for portability, added a find-project-root helper script, and updated settings.yaml to use relative paths. Also fixed the same relative-path issue in /log and /reflect-logs skills.

Decisions

Decision: Use CLAUDE_PROJECT_ROOT env var for all cross-project path resolution in skills — Rationale: Makes skills shareable with colleagues; hardcoded ~/dev/claude/ paths are user-specific and relative ../ paths break depending on CWD
Decision: Add Step 0 (detect project root) as runtime fallback in distill skill — Rationale: Skills should degrade gracefully if env var isn't set; Claude can walk up the directory tree to find highest CLAUDE.md
Decision: settings.yaml paths relative to CLAUDE_PROJECT_ROOT, not absolute — Rationale: Portability; projects_dir: projects instead of ~/dev/claude/projects
Decision: Added extra_projects section to settings.yaml for projects outside projects_dir — Rationale: small-scripts lives at root level, not under projects/

Gotchas Discovered

[skills] Symptom: /distill-best-practices failed with sandbox error — cat ../claude-foundations/... resolved to /home/paul/dev/claude-foundations/ (outside sandbox) when CWD was ~/dev/claude/ — Fix: Replace all relative and hardcoded paths with ${CLAUDE_PROJECT_ROOT} env var
[skills] Symptom: !command`` blocks can't use $() command substitution — Fix: Use env var expansion (${CLAUDE_PROJECT_ROOT}) which works, and fall back to runtime detection in skill instructions
[skills] Symptom: Claude Code Bash tool doesn't persist export across ;-separated commands in the same invocation when the variable is used in file path arguments — Fix: Use bash -c '...' wrapper or ensure var is in shell profile

Key Context

settings.yaml now tracks 6 projects under distill.projects plus small-scripts under extra_projects
Added projects: agent-runtimes, claude-foundations, cluster-apps/octopus-deploy, hugo-accelerator
find-project-root script created at claude-foundations/scripts/find-project-root — walks up from CWD to find highest CLAUDE.md
CLAUDE_PROJECT_ROOT export added to ~/.bashrc
Three skills updated: distill-best-practices (full rewrite of paths), log and reflect-logs (settings fallback path)

2.5 KiB Raw Blame History