hyalo: Skill for Claude Code

Dogfood Session

A dogfood session exercises hyalo against real knowledgebases to find bugs, verify fixes, assess UX, and discover improvement opportunities. Sessions should feel like a real user working with the tool — not a mechanical checklist. Be curious, follow interesting leads, try edge cases that occur to you naturally.

Phase 1: Prepare

1. Build and install from source, then prove the hyalo on PATH is this tree. The PATH binary is a cargo install and goes stale silently: on 2026-09-04 it was three days and eleven PRs behind target/release/hyalo, and a DEC-284 check against it nearly got filed as a bug.

   cargo build --release
   cargo install --path crates/hyalo-cli --target-dir target --force
   test "$(hyalo --version | awk '{print $3}' | tr -d '(' | sed 's/+dirty$//')" = "$(git rev-parse --short=12 HEAD)" \
     && echo "hyalo on PATH is HEAD" || { echo "STALE hyalo on PATH: $(which hyalo)"; exit 1; }
   

   --target-dir target reuses the release build so the install takes seconds; the version string is hyalo X.Y.Z (<12-char hash>[+dirty] <date>), and +dirty is fine — it only means uncommitted edits such as the report you are about to write. If the check fails, fix the PATH before doing anything else — every later command in this skill, and every explorer agent you spawn, must run the same binary. Never fall back to ./target/release/hyalo for some commands and hyalo for others in one session.
2. Find the last dogfood report to establish the baseline:

   hyalo find --tag dogfooding --sort date --reverse --limit 1 --format text
   

   Read it to learn: which version was tested, which bugs were found, what was verified.
3. Discover what changed since then: Use git log --oneline from that report's date to HEAD. Look for merged iteration branches (iter-N/...). For each, read the iteration file in the knowledgebase to understand what was implemented:

   hyalo find --tag iteration --property "date>=YYYY-MM-DD" --sort date --format text
   

   Then hyalo read <iteration-file> --format text for each to understand the features, bug fixes, and UX changes. These are your priority test targets.
4. Check prior dogfood reports for open bugs to re-verify:

   hyalo find --tag dogfooding --sort date --reverse --limit 5 --format text
   

   Read the most recent reports and collect any bugs marked as found (not yet verified fixed).
5. Pick target knowledgebases: Use a mix of:
   • Own KB (hyalo-knowledgebase/, ~250 files) — well-structured, has schemas/views
   • MDN Web Docs (../mdn/files/en-us/, ~14K files) — large, stress-tests performance
   • GitHub Docs (../docs/content/, ~3.5K files) — complex nested YAML frontmatter
   • VS Code Docs (../vscode/, ~1K files) — mid-size, different structure