044a04fd0d
* docs: add workflow guide for command entry points * Refine workflow guidance into advice-only routing Reuse the existing routing reference and docs map instead of shipping a parallel workflow catalog. Add reference-backed command comparisons, advice-only tests, and explicit-command precedence coverage. AI-assisted maintainer revision prepared with Codex. * Include routing guidance in behavior-test triggers AI-assisted maintainer revision prepared with Codex. * Constrain routing behavior tests to fixture-safe tools Keep the real context loader but reject arbitrary host shell searches in the new advice scenarios. Preserve observable project writes and protect the staged skill; cover the restriction with offline regression tests. AI-assisted maintainer revision prepared with Codex. * Require actual reference reads in restricted routing tests Do not count rejected shell reads as reference loading. Record the nine measured advice cases; explicit-command measurements remain pending the stricter retest. AI-assisted maintainer revision prepared with Codex. * Record measured workflow-routing baseline All twelve focused cases pass across Claude Sonnet 5, GPT-5.6 Terra, and Gemini 3.7 Flash, including the stricter explicit-command retest. AI-assisted verification prepared with Codex. * Trim workflow routing guidance Reduce added skill prose from 286 to 59 words while retaining the routing regression assertions. Record the missing-context reference-read flake and passing repeat. AI assistance: prepared and verified with Codex under maintainer direction. --------- Co-authored-by: Paul Bakaus <paul.bakaus@gmail.com>
3.2 KiB
Command guidance
Workflow questions
Give advice without executing commands; the menu below is only for bare invocations. Consult relevant command references as needed for prerequisites and scope. Link to the docs for the broader workflow guide. If the user also requests execution, follow that request.
No-argument routing: the context-aware menu
Read this when the user invokes {{command_prefix}}impeccable with no argument. They are asking "what should I do?" Make the menu context-aware instead of static.
Setup has already run impeccable context. If that reported NO_PRODUCT_MD, the project has no captured context yet: lead the menu with /impeccable init as the top recommendation (one line on why) and still show the rest below; don't silently jump into init. Otherwise run {{scripts_path}}/impeccable signals once and read its JSON, then lead with the 2-3 highest-value next commands, each with a one-line reason pulled from the signals, followed by the full menu (the Commands table in SKILL.md, grouped by category). Never auto-run a command; the recommendation is a suggestion the user confirms.
Reason over the signals; there is no score to obey:
setup.hasDesignfalse whilesetup.hasCodetrue →document(capture the visual system).critique.latestisnull→ the project has never been critiqued; for a set-up project with a real surface, offering/impeccable critique <surface>is a strong default.critique.latestwith a lowscoreor non-zerop0/p1→polish(it reads that snapshot as its backlog and closes it when stale or cleared).git.changedFilespointing at one surface → scopeauditorpolishto those files specifically, naming them.devServer.runningtrue →liveis available for in-browser iteration; if false, don't lead withlive.liveand the bundledimpeccable detectare web-only. Ifsetup.platformisios,android, oradaptive, don't lead with either; the browser overlay and the HTML rule engine don't apply to native app code.- Otherwise group by intent (build new / improve what's there / iterate visually), tailored to the current surface and
setup.platform.
If scan.targets is non-empty and setup.platform is not ios/android/adaptive, run {{scripts_path}}/impeccable detect --json <scan.targets joined by spaces> once (the bundled detector over local files: no network, no npx; it reads HTML/CSS, so skip it for native projects). scan.via tells you what they are: git-changes (the markup/style files in your dirty tree, the most relevant set), source-dir (e.g. src, app), html, or root. Fold the hits into your picks: many quality / contrast hits → audit or polish; a specific slop family → the matching command (gradient text or eyebrows → quieter / typeset, flat or gray palette → colorize, and so on). It's a real, current signal that beats guessing. If detect errors or the tree is large and slow, skip it and recommend the user run audit themselves; never block the suggestion on it.
Keep it to 2-3 pointed picks with the exact command to type. The menu stays the fallback; the recommendation is the lede.