Audit agent workflow guidance in a reverse-engineering MCP tool's skill docs

What they did

The author noticed that the `trace_crash` prompt still recommended complete function dossiers even after `build_call_path` had gained retained-parent references (#8435, fixed in #8437). The existing tool-design audit checked tools and catalogs but never inspected the workflow advice agents actually receive. They extended the `rea-tool-design` skill with a short instruction that routes the audit to detailed guidance in `docs/tool-design.md`, and expanded that guide to cover inspecting relevant rendered prompts, guided workflows, and packaged skill advice, then exercising the suggested cross-tool handoffs against the live contracts. The guide also calls out that two renderers can agree on the same stale advice, that matching text alone does not establish correctness or agent selection, and that the installed skill and connected server may come from different revisions. The change is contributor guidance only: no provider capability, tool, runtime behavior, or authority was added, and no generated artifacts were committed. Validation was limited to `quick_validate.py` on the skill, `npm run docs:check` (including 9 README conformance tests), and `git diff --check`.

How it went

The skill and guide changes landed as a focused docs-only PR. All three validation commands passed, and the PR explicitly states it does not replace the actual prompt fix in #8437. The author notes no independent agent trial was run, so whether the updated process instruction changes future agent behavior is unproven.

Worth knowing

This is documentation and process guidance only; it fixes no prompt and changes no runtime behavior. The motivating Ghidra workflow, Kuna control, and MCP prompt regression live in #8435 and #8437 rather than this change. There is no evidence the instruction actually alters agent behavior, and the audit still depends on a human or agent comparing installed skill revisions against the connected server.

Wiring

Start from the tool-design skill at `.agents/skills/rea-tool-design/SKILL.md`; its short instruction routes the audit to `docs/tool-design.md`. In the guide, enumerate the renderers that produce agent-facing advice (prompts such as `trace_crash`, guided workflows, and packaged skill text like `.agents/skills/reverse-engineer-anything/SKILL.md`). For each, compare the recommended tool sequence against the live tool contracts, including newer capabilities such as retained-parent references from `build_call_path`. Then exercise the suggested handoffs end to end, checking session and source identity and available alternatives. Validate with `python3 .../quick_validate.py .agents/skills/rea-tool-design`, `npm run docs:check`, and `git diff --check` before committing.

Try it yourself

Audit the agent workflow guidance in this repo. Read the tool-design skill under .agents/skills/ and docs/tool-design.md, then list every rendered prompt, guided workflow, and packaged skill instruction that tells agents how to chain tools. For each one, check the suggested cross-tool handoffs against the current tool contracts and flag any advice that is stale, that two renderers agree on but is wrong, or that assumes a different revision of the installed skill or connected server. Report findings as a table with file, line, stale claim, and current contract. Do not change runtime behavior; propose doc edits only.