feat(find): hint for --task and --ai-model when a find leaves them out (v2.8.0)

[paulkr]

Why

Over the last 30 days, 62% of CLI finds arrived without --task (236 of 379, benchmark harness excluded), against 5% over the remote MCP. The skill, guide, README and --help all already ask for it. The misses come from agents that never read them:

Agent (via CLI)	Finds	No --task	Sent --ai-model
hermes	177	85%	4
claude-code	96	36%	20
(unnamed)	49	55%	15
codex	38	13%	24
cursor	20	100%	0

Hermes and cursor almost never send --ai-model either, which the same skill asks for. So they call one actions find without the skill loaded. The one thing every agent reads is the command's output.

What

• findHint(task, aiModel) (src/lib/find.ts): when a find comes without --task and/or --ai-model (blank counts as missing), it returns one line naming what was missing and why it matters. It returns nothing when both were sent.
• actions find adds it to the answer:
  • --agent mode: an optional top-level hint field on the JSON ({ answers, guide?, hint? }), the same name the validation errors already use;
  • human mode: a dim line after the answer.
• Unchanged: both flags stay optional, the find isn't blocked, and the answers and documentation are the same. The field is additive, so existing parsers ignore it.
• Docs: skills/one/SKILL.md, one guide (guide-content.ts) and the README say a find answer may carry a hint to act on.
• Version 2.8.0 (package.json and the lockfile's two version fields, hand-edited per CLAUDE.md).

Measuring it

The metrics dashboard's Task Requests tab already tracks this. Data completeness charts task coverage by source and agent, and Finds labels each miss "No --task given". After users update, hermes and cursor's task share should rise.

Test plan

• npm ci, tsc --noEmit, npm run build
• New find hint tests:
  • both missing → asks for both;
  • one missing → names only that;
  • blank task → missing;
  • both sent → no hint.
• Full suite: 669 pass. The 6 failures are the pre-existing resolveConfig macOS /var vs /private/var tmpdir assertions; the same 6 fail on main.
• Not run live against the API, so as not to write a test find into the production record.

🤖 Generated with Claude Code