chore: improve notes claude skills (#276)

mprov### TL;DR

Replaced hardcoded notes directory validation with a centralized script for better error handling and consistency.

### What changed?

- Created a new script `echo-notes-dir.sh` that validates the `./.notes` directory and provides helpful error messages
- Updated all skills to use this script instead of inline bash validation
- Removed the outdated `notes/SKILL.md` file
- Updated path references in `notes-layout.md` to use the correct script paths
- Made the scripts more robust by using the new validation script

### How to test?

1. Verify that all skills load correctly with a valid `./.notes` symlink
2. Test error handling by temporarily removing the `./.notes` symlink:
   ```bash
   mv .notes .notes.bak
   # Try using a skill that requires notes
   # Verify you get a helpful error message
   mv .notes.bak .notes
   ```
3. Check that the scripts work correctly:
   ```bash
   ./.claude/skills/notes/scripts/echo-notes-dir.sh
   ./.claude/skills/notes/scripts/list-titles scratch/
   ./.claude/skills/notes/scripts/search "pattern"
   ```

### Why make this change?

- Centralizes the notes directory validation logic to avoid duplication
- Provides more helpful error messages when the notes directory is missing or inaccessible
- Makes the code more maintainable by having a single source of truth for directory validation
- Removes dependency on environment variables, making the scripts more portable and reliable

Author: jumski

.claude/skills/idea-refine/SKILL.md

@@ -6,7 +6,7 @@ allowed-tools: Read, Edit, Bash, Grep, Glob
 
 # Idea Refinement
 
-**Notes directory:** !`test -d ./.notes && test -r ./.notes && test -w ./.notes && echo "./.notes" || echo "ERROR: ./.notes is not a valid readable/writable directory! Ask user to create the symlink."`
+**Notes directory:** !`./.claude/skills/notes/scripts/echo-notes-dir.sh`
 
 **Context:** @../notes/shared/directory.md @../notes/shared/conventions.md
 

.claude/skills/notes/SKILL.md

@@ -1,19 +1,16 @@
 # Troubleshooting
 
-## Scripts can't find $notes
+## .notes directory not found
 
-**Error:** `Error: $notes environment variable not set`
+**Error:** `ERROR: .notes directory not found at ./.notes`
 
 **Fix:**
 ```bash
-# Check if set
-echo $notes
+# Create symlink to your notes directory
+ln -s /path/to/your/notes-directory .notes
 
-# Set temporarily
-export notes="/path/to/notes"
-
-# Set permanently (add to ~/.bashrc or ~/.zshrc)
-echo 'export notes="/path/to/notes"' >> ~/.bashrc
+# Example:
+ln -s ~/Documents/pgflow-notes .notes
 ```
 
 ## Scripts not executable
@@ -22,7 +19,7 @@ echo 'export notes="/path/to/notes"' >> ~/.bashrc
 
 **Fix:**
 ```bash
-chmod +x .claude/skills/roadmap/scripts/*
+chmod +x .claude/skills/notes/scripts/*
 ```
 
 ## No search results
@@ -34,7 +31,7 @@ chmod +x .claude/skills/roadmap/scripts/*
 
 **Try:**
 - Broader pattern: `"feature"` instead of `"feature-x-implementation"`
-- Check directory: `ls "$notes/roadmaps/"`
+- Check directory: `ls ./.notes/`
 - Verify pattern syntax (regex)
 
 ## Git errors
@@ -43,7 +40,7 @@ chmod +x .claude/skills/roadmap/scripts/*
 
 **Fix:**
 ```bash
-cd "$notes"
+cd ./.notes
 git init
 git add .
 git commit -m "Initial commit"

.claude/skills/notes/TROUBLESHOOTING.md

@@ -93,8 +93,8 @@ Add to "Cross-Feature Constraints" section if:
 ### 4. Commit
 
 ```bash
-git -C "$notes" add roadmap.md
-git -C "$notes" commit -m "Update: roadmap reordering (moved X before Y)"
+git -C ./.notes add roadmap.md
+git -C ./.notes commit -m "Update: roadmap reordering (moved X before Y)"
 ```
 
 ## Key Principles
@@ -123,8 +123,8 @@ After (C is urgent):
 
 Git commit:
 ```bash
-git -C "$notes" add roadmap.md
-git -C "$notes" commit -m "Update: prioritize Feature C (customer blocker)"
+git -C ./.notes add roadmap.md
+git -C ./.notes commit -m "Update: prioritize Feature C (customer blocker)"
 ```
 
 ## Marking Complete

.claude/skills/notes/organize-roadmap.md

@@ -20,7 +20,7 @@ Promote an idea when:
 
 ```bash
 # Move from scratch to brewing
-git -C "$notes" mv scratch/idea-name.md brewing/
+git -C ./.notes mv scratch/idea-name.md brewing/
 ```
 
 ### 2. Update the title (optional)
@@ -41,15 +41,15 @@ Add a few lines about:
 ### 4. Git commit
 
 ```bash
-git -C "$notes" add brewing/idea-name.md
-git -C "$notes" commit -m "Promote: idea-name to brewing"
+git -C ./.notes add brewing/idea-name.md
+git -C ./.notes commit -m "Promote: idea-name to brewing"
 ```
 
 ## Example
 
 ```bash
 # Move the file
-git -C "$notes" mv scratch/taskless-maps.md brewing/
+git -C ./.notes mv scratch/taskless-maps.md brewing/
 
 # File content (brewing/taskless-maps.md):
 # IDEA: Taskless Map Steps
@@ -65,8 +65,8 @@ git -C "$notes" mv scratch/taskless-maps.md brewing/
 # Question: How do dependents handle empty arrays?
 
 # Commit
-git -C "$notes" add brewing/taskless-maps.md
-git -C "$notes" commit -m "Promote: taskless-maps to brewing"
+git -C ./.notes add brewing/taskless-maps.md
+git -C ./.notes commit -m "Promote: taskless-maps to brewing"
 ```
 
 ## Key Principles

.claude/skills/notes/promote-brewing.md

@@ -20,7 +20,7 @@ Create a feature spec when:
 
 ```bash
 # Move the file
-git -C "$notes" mv brewing/idea-name.md features/feature-name.md
+git -C ./.notes mv brewing/idea-name.md features/feature-name.md
 ```
 
 ### 2. Structure the spec
@@ -76,8 +76,8 @@ What problem does this solve? What value does it provide?
 ### 3. Commit the feature
 
 ```bash
-git -C "$notes" add features/feature-name.md
-git -C "$notes" commit -m "Add: feature spec for feature-name"
+git -C ./.notes add features/feature-name.md
+git -C ./.notes commit -m "Add: feature spec for feature-name"
 ```
 
 ### 4. Add to roadmap
@@ -97,14 +97,14 @@ Update roadmap.md with this feature's position:
 
 ```bash
 # Move from brewing
-git -C "$notes" mv brewing/manual-execution.md features/manual-execution.md
+git -C ./.notes mv brewing/manual-execution.md features/manual-execution.md
 
 # Edit to add full spec structure
 # (Add objective, prerequisites, implementation steps, etc.)
 
 # Commit
-git -C "$notes" add features/manual-execution.md
-git -C "$notes" commit -m "Add: feature spec for manual execution"
+git -C ./.notes add features/manual-execution.md
+git -C ./.notes commit -m "Add: feature spec for manual execution"
 ```
 
 ## Next Steps

.claude/skills/notes/refine-features.md

@@ -14,13 +14,13 @@ Scratch contains quick captures written by the Memory skill. This workflow helps
 ### 1. List scratch items
 
 ```bash
-./.claude/skills/roadmap/scripts/list-titles "scratch/"
+./.claude/skills/notes/scripts/list-titles "scratch/"
 ```
 
 ### 2. Search for specific topics
 
 ```bash
-./.claude/skills/roadmap/scripts/search "subflow" "scratch/"
+./.claude/skills/notes/scripts/search "subflow" "scratch/"
 ```
 
 ### 3. Read promising items

.claude/skills/notes/review-scratch.md

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# echo-notes-dir.sh - Validate and echo the notes directory path
+#
+# Usage:
+#   In bash scripts: NOTES_DIR=$(bash path/to/echo-notes-dir.sh)
+#   In markdown: !`path/to/echo-notes-dir.sh`
+#
+# Exit codes:
+#   0 - Success, echoes "./.notes" to stdout
+#   1 - Error, prints error message to stderr
+
+set -euo pipefail
+
+NOTES_DIR="./.notes"
+
+# Check if .notes directory exists
+if [ ! -d "$NOTES_DIR" ]; then
+  echo "ERROR: .notes directory not found at $NOTES_DIR" >&2
+  echo "" >&2
+  echo "Please create a symlink to your notes directory:" >&2
+  echo "  ln -s /path/to/your/notes-directory .notes" >&2
+  echo "" >&2
+  echo "Example:" >&2
+  echo "  ln -s ~/Documents/pgflow-notes .notes" >&2
+  exit 1
+fi
+
+# Check if .notes is readable
+if [ ! -r "$NOTES_DIR" ]; then
+  echo "ERROR: .notes directory is not readable: $NOTES_DIR" >&2
+  echo "Please check permissions." >&2
+  exit 1
+fi
+
+# Check if .notes is writable
+if [ ! -w "$NOTES_DIR" ]; then
+  echo "ERROR: .notes directory is not writable: $NOTES_DIR" >&2
+  echo "Please check permissions." >&2
+  exit 1
+fi
+
+# Success - echo the path
+echo "$NOTES_DIR"
+exit 0