From 60c0cf977a34c99afa7942466625aeba74969bdf Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Sun, 1 Nov 2026 17:53:37 +0800 Subject: [PATCH] docs: clarify recovery for valid lookup failures --- .agents/skills/rea-tool-design/SKILL.md | 4 +++- docs/design/limits-and-recovery.md | 8 ++++++-- docs/testing.md | 4 ++++ docs/tool-design.md | 21 +++++++++++++++++++++ 4 files changed, 34 insertions(+), 3 deletions(-) diff --git a/.agents/skills/rea-tool-design/SKILL.md b/.agents/skills/rea-tool-design/SKILL.md index ca069df009..3dd31ffdb1 100644 --- a/.agents/skills/rea-tool-design/SKILL.md +++ b/.agents/skills/rea-tool-design/SKILL.md @@ -13,7 +13,9 @@ documentation, and live catalogs may describe different versions. For provider-backed work, exercise the analyst's task through REA and compare relevant native provider and independent artifact observations where available. Check applicable partial results, recovery and session boundaries; report what -was not exercised. Use [workflow verification](../../../docs/testing.md#provider-backed-workflow-verification) +was not exercised. For failure guidance, follow [design recovery around the +failure](../../../docs/tool-design.md#design-recovery-around-the-failure). +Use [workflow verification](../../../docs/testing.md#provider-backed-workflow-verification) to select evidence for the proposed contract instead of seeking provider API parity. diff --git a/docs/design/limits-and-recovery.md b/docs/design/limits-and-recovery.md index 94d9642010..4ccf0c4da2 100644 --- a/docs/design/limits-and-recovery.md +++ b/docs/design/limits-and-recovery.md @@ -316,8 +316,12 @@ request to change it. `runtime-configuration:` check. Re-run `rea setup` for that client when the setting is on the registration allowlist, then reconnect so the new process sees it. -- `invalid_request`: correct the reported fields from the current schema or - CLI help. Do not repeat the unchanged call. +- `invalid_request`: follow the specific recovery and reported issue. Inspect + the schema or CLI help when the input violates the contract or the response + asks for `inspect_input_contract`. A valid selector can instead require a + different choice, such as selecting a reported address; an inventory miss + does not establish that the target lacks the item. Do not repeat the + unchanged call when the response says it cannot succeed unchanged. A restart is required to adopt a changed launch environment or registration. The curated runtime settings above require no REA restart. It is not the first step for a transient diff --git a/docs/testing.md b/docs/testing.md index 671688f133..3b13ad19c3 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -438,6 +438,10 @@ affected consumer. - Where relevant, continue after a mixed success, failed request, cancellation or close/reopen. Verify the next supported recovery and preservation of prior results and resource ownership. Use the applicable lifecycle regressions below. +- For lookup failures, distinguish malformed input from a valid missing or + ambiguous selector. Check the returned candidate and input identity, follow + an actionable recovery where possible, and verify that an inventory miss is + not presented as artifact-wide absence. Test schema-repair advice separately. - Record the provider version, host, fixture, actual entrypoint, controlled faults and skipped or unavailable coverage. A simulated provider tests the integration boundary; a scripted sequence tests that sequence, not an agent's diff --git a/docs/tool-design.md b/docs/tool-design.md index e6a0ea5e60..ec7afbaf56 100644 --- a/docs/tool-design.md +++ b/docs/tool-design.md @@ -99,6 +99,27 @@ include the smallest useful reproduction, impact and coverage limits. Do not claim autonomous-agent selection from a scripted trace. Check related reports before proposing another issue, and avoid treating lack of API parity as a bug. +## Design recovery around the failure + +Distinguish a request that violates its input contract from a valid selection +that the current target, provider inventory, or project cannot resolve. The +same `invalid_request` code can represent either. Suggest schema inspection +only when the input contract is the problem; for a valid lookup, preserve the +caller's exact selector, the observed reason and any candidates, and give a +next step that addresses that outcome. An inventory miss does not prove that +the artifact lacks the requested item. + +Keep recovery within the selected target, provider, project and authority. If +another context could help, describe it as an explicit choice and state any +relevant loss of state; do not switch or select a candidate automatically. +Preserve uncertainty, partial observations, and session or cleanup state. A +suggested retry must be safe and explain any required change or wait. + +Verify recovery through the public workflow: reproduce the failure, follow +the suggested next step when feasible, and check the result and session state. +Include a malformed-input control so schema guidance remains available when it +is actually needed. Compare CLI and MCP when both expose the operation. + ## Define the contract - Use strict inputs with explicit target identity and required fields. Preserve