| name | grove-doctor |
| description | Use when something in the Grove setup is not working as expected, or when a user asks to diagnose or troubleshoot their Grove installation |
I'm using the grove-doctor skill to run a series of diagnostic checks on this Grove setup.
Workflow
Run each check in order. Collect all results and print the full report at the end.
Check 1: Platform
diskutil info / | grep "File System"
- PASS if output contains
APFS
- WARN if macOS but not APFS
- FAIL if not macOS
Check 2: CLI installed
command -v grove
Check 3: CLI version
grove version
- PASS — record the version string for the report
- FAIL if the command errors. Fix: reinstall the CLI
Check 4: Grove initialized
test -f .grove/config.json
- PASS if the file exists
- FAIL if not found. Fix: run the
grove:grove-config skill to initialize Grove in this repository
Check 5: Golden copy health
git status --porcelain
git rev-parse --abbrev-ref HEAD
git rev-parse --short HEAD
- PASS if
git status --porcelain produces no output (clean)
- WARN if there are uncommitted changes — report the count of dirty files. Suggestion: commit or stash changes before creating workspaces
- Record branch name and short commit hash in the report regardless
Check 6: Workspace directory
Read workspaceDir from .grove/config.json. Then:
test -d <workspaceDir> && test -w <workspaceDir>
df -h <workspaceDir>
- PASS if the directory exists, is writable, and has available disk space
- WARN if free space is under 5 GB
- FAIL if the directory does not exist or is not writable. Fix:
mkdir -p <workspaceDir> or adjust permissions
Check 7: Hooks
test -x .grove/hooks/post-clone
- PASS if the file exists and is executable
- FAIL if missing or not executable. Fix:
chmod +x .grove/hooks/post-clone
Check 8: Active workspaces
grove list --json
- PASS — report the count of active workspaces
- Flag any workspaces whose
created_at is more than 7 days ago as potentially stale
- FAIL if the command errors
Output Format
After all checks, print the report:
Grove Doctor Report:
[PASS] Platform: macOS (APFS)
[PASS] CLI: grove v0.1.0
[PASS] Initialized: .grove/config.json found
[WARN] Golden copy: 3 uncommitted changes
[PASS] Workspace dir: /tmp/grove/myproject (12GB free)
[FAIL] Hooks: .grove/hooks/post-clone not executable
Fix: chmod +x .grove/hooks/post-clone
[PASS] Workspaces: 2 active
For every FAIL, include a Fix line with a specific command or actionable suggestion. For every WARN, include a Suggestion line.
Quick Reference
| Check | Command |
|---|
| Platform | `diskutil info / |
| CLI installed | command -v grove |
| CLI version | grove version |
| Initialized | test -f .grove/config.json |
| Golden copy | git status --porcelain |
| Workspace dir | df -h <workspaceDir> |
| Hooks | test -x .grove/hooks/post-clone |
| Workspaces | grove list --json |
Common Mistakes
- Running grove-doctor outside a git repo — checks 4 and 5 will produce misleading results. Always run from the repository root.
- Reporting only failures — always print the full checklist including PASSes so the user can see what is healthy.
- Skipping the fix command — every FAIL must include a concrete remediation step, not just a description of the problem.
Red Flags
- Multiple FAILs starting from Check 2 — the CLI is not installed; later checks are meaningless. Stop early and fix the CLI first.
- Golden copy is on a detached HEAD — workspaces created from it will have no branch context.
- Workspace directory is on a non-APFS volume — CoW clones will not work; Grove requires APFS.
Integration
- Standalone — invoked manually when things go wrong; not called by other skills automatically
