Skip to content

feat: add comment-checker-setup skill with doctor script - #85

Merged
ryanleecode merged 8 commits into
masterfrom
feature/comment-checker-setup-skill
Aug 30, 2026
Merged

feat: add comment-checker-setup skill with doctor script#85
ryanleecode merged 8 commits into
masterfrom
feature/comment-checker-setup-skill

Conversation

@systemfsoftware-maker

Copy link
Copy Markdown
Collaborator

Adds a comment-checker-setup skill that lets any agent install or repair the comment-checker PostToolUse hook from the repo alone. The hook's failure mode is resolution: a hook that cannot find its binary checks nothing. The skill names the resolution chain (PATH -> direnv exec -> fail-loud) and ships a doctor.ts that proves each link end-to-end.

The doctor probes, from a clean environment:

  • binary resolution on PATH
  • binary identity (claude-code-comment-checker <semver>)
  • the exit-code contract (blocks a restating comment with exit 2, spares clean input with 0)
  • hook wiring (parses the hook file for a comment-checker PostToolUse entry, not just presence)
  • the direnv bridge (PATH-first: reports "not needed" when the binary already resolves)
  • the flake dev shell, when a flake.nix provides the checker

It exits 0 only when every check passes, and each broken check carries a fix hint an agent can act on. The npm README points at the skill so the setup path is discoverable from the registry page.

Verification:

  • Doctor verified against three fixtures: a working npm-global setup (all checks pass, exit 0), a project with no .envrc (correctly broken), and a shadowing fake wrapper (correctly flagged by identity) — including running from a foreign cwd.
  • deno check + deno lint clean in scripts/; cargo gate (fmt, clippy, test) green.
  • The eval suite passed the blind-verifier gate: every eval fails half its needles on a fresh-context probe with no skill body, so the suite measures skill doctrine, not echoed prompts.
  • Body is a routing layer (138 lines): rules name deterministic gates, one reference routed by name, description is the sole trigger.

Lesson captured in docs/solutions/integration-issues/diagnostic-hook-needs-fixtures-on-both-sides.md: a diagnostic must be proven against healthy and broken fixtures, from a foreign cwd, before it ships.

@ryanleecode
ryanleecode merged commit c29d02e into master Aug 30, 2026
12 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants