>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3588806. --> Reported by: [ajv009](https://www.drupal.org/user/3653917) >>> <h3 id="summary-problem-motivation">Problem/Motivation</h3> <p>The research corpus documents at least four occasions across three sessions where skill consultation produced an immediate breakthrough after 10+ failed attempts by trial-and-error. In each case the agent was in a retry loop (wrong API endpoint, zombie component naming, wrong CLI syntax, wrong npm tooling), the user prompted "have you refered all the skills in your arsenal?", and on the next attempt after skill consultation the problem was resolved.</p> <p>The skills contain hard-won gotchas that trial-and-error cannot rediscover within a session: <code>PATCH 503</code> is permanent on the affected Acquia instance; <code>canvas:upload</code> is one <code>-c</code> flag at a time; <code>canvas:download</code> lists the registry; <code>npm run canvas:*</code> is the tooling. These were documented because they were non-obvious. Skill consultation produces the right approach in one step because the skip-past-obvious-fixes path already exists in the skill.</p> <p>The failure is structural: the agent does not self-consult skills proactively. It only does so when the user explicitly intervenes. Adding a rule ("if stuck for &gt;2 consecutive failures of the same operation, invoke ToolSearch and read the relevant skill") makes the self-rescue automatic and eliminates the dependency on user intervention. Concrete cost in the corpus: 15 failed component-upload attempts in one session resolved on the 16th attempt after the user's prompt; a 3-hour PATCH 503 zombie loop with 15 names tried.</p> <h4 id="summary-steps-reproduce">Steps to reproduce</h4> <ol> <li>Run a migration that hits a known retry-storm scenario (PATCH 503 on Canvas component update; menu POST with WAF redirect; <code>canvas:upload</code> with multi-component flags).</li> <li>Observe the agent retries with variations 10+ times before user intervention.</li> <li>Inspect the tool-call sequence: no <code>ToolSearch</code> call, no skill <code>Read</code>, until user prompts.</li> </ol> <h3 id="summary-proposed-resolution">Proposed resolution</h3> <p><strong>Step 1 &mdash; Add a "Retry and Recovery Protocol" to <code>migrate-site/SKILL.md</code></strong> (or to its common notes section):</p> <pre>## Retry and Recovery Protocol If the same operation fails 3 consecutive times: 1. STOP retrying. 2. Invoke ToolSearch to find the most relevant skill(s) for the failing operation. 3. Read the skill in full. 4. Only then attempt the operation again, following the skill's documented approach. This is NOT a rescue mechanism &mdash; it is a first step. Skill consultation before attempt 4 saves more time than it costs, even accounting for the context space. Operations most likely to benefit from skill consultation on failure: - canvas:upload / canvas:validate errors &rarr; component-authoring skill - Browser admin UI redirects / menu creation &rarr; migrate-site Phase 6 docs - JSON:API 403/405/503 &rarr; media-handler or component-authoring gotchas sections - Playwright / agent-browser failures &rarr; agent-browser CLAUDE.md</pre><p><strong>Step 2 &mdash; Add a one-liner to project-level <code>CLAUDE.md</code>:</strong> "On the 3rd consecutive failure of the same operation, invoke ToolSearch and read the relevant skill before attempt 4."</p> <p><strong>Step 3 &mdash; Per-agent retry protocol notes</strong> in agents that are known to encounter retry storms:</p> <ul> <li><code>component-builder.md</code>: "After 3 consecutive upload failures, stop and invoke ToolSearch to find the <code>component-authoring</code> skill before attempt 4."</li> <li><code>menu-builder.md</code> (if it exists): "After 3 consecutive POST failures, stop and re-read the migrate-site skill Phase 6 documentation before attempt 4."</li> <li><code>upload-verifier.md</code>: same pattern.</li> </ul> <p><strong>Step 4 &mdash; Optional orchestrator hook.</strong> If any dispatched agent reports more than 3 retries in its reply, the orchestrator proactively <code>ToolSearch</code>es before the next dispatch.</p> <p><strong>Why this works.</strong> Skills encode the solution path for non-obvious failure modes. Trial-and-error can only explore the space of things the agent already knows; it cannot reach "PATCH 503 is permanent on this Acquia instance" without the skill, because there's no heuristic that leads there. The skill has this information because a human with domain knowledge wrote it down after experiencing the pain. The reason the rule is needed: the cost of "read the skill" is perceived as high (context space + ToolSearch call), while the cost of "try one more thing" is perceived as low. By attempt 4 the cost of the retry storm already exceeds the cost of reading the skill &mdash; the rule forces the right cost comparison.</p> <h3 id="summary-remaining-tasks">Remaining tasks</h3> <ul> <li>Add "Retry and Recovery Protocol" block to <code>migrate-site/SKILL.md</code>.</li> <li>Add one-liner to project-level <code>CLAUDE.md</code>.</li> <li>Add per-agent notes to <code>component-builder.md</code>, <code>menu-builder.md</code>, <code>upload-verifier.md</code>.</li> <li>Optional: add ToolSearch as an explicit orchestrator error-handling step.</li> <li>Verify in a migration with a known failure scenario: agent's tool-call sequence shows a <code>ToolSearch</code> call before attempt 4, not after 10+ retries.</li> </ul> <h3 id="summary-ui-changes">User interface changes</h3> <p>None.</p> <h3 id="summary-api-changes">API changes</h3> <p>None.</p> <h3 id="summary-data-model-changes">Data model changes</h3> <p>None.</p> <h3 id="summary-internal-references">Internal references</h3> <ul> <li>Source markdown: <code>RESEARCH-2026-04-28/99-final/ISSUES/Sprint-8-Patterns-To-Encode/06-NEW-6-skill-as-cognitive-reset-trigger.md</code> (id: NEW-6)</li> <li>Pattern definition: <code>RESEARCH-2026-04-28/07-cross-cutting/what-actually-works.md</code> &sect; P6</li> <li>User prompt origin: <code>RESEARCH-2026-04-28/02-edu-site-mockup-ai/ce9e965e/screenshot-to-component-pattern.md</code> (L796 verbatim)</li> <li>Anti-pattern: <code>RESEARCH-2026-04-28/07-cross-cutting/session-anti-patterns.md</code> &sect; AP5</li> <li>Related retry storms: <code>RESEARCH-2026-04-28/99-final/consolidated-issues.md</code> &sect; P0-6 (menu-builder 64 min) and &sect; P1-2 (PATCH 503 3-hour zombie loop)</li> </ul> <h3 id="summary-open-questions">Open questions</h3> <ul> <li>Threshold &mdash; 3 or 2 failures? Pattern P6 says 3. Expensive operations (PATCH 503 takes minutes) may warrant 2; cheap operations (CLI flag errors) work fine at 3. Recommend single rule "3 failures for any operation" to avoid per-operation customization.</li> <li>Which skills to search? Add a lookup table to the recovery protocol: canvas:upload &rarr; <code>component-authoring</code>; Drupal admin &rarr; <code>migrate-site</code> Phase 6; JSON:API &rarr; <code>media-handler</code>.</li> <li>Conflict with existing designed retries? Some agents have explicit retry counts (verify-browser-session: retry up to 4&times;; menu-builder: retry on WAF redirect up to 4&times;). The skill consultation rule should not override these &mdash; only fire on unplanned consecutive failures.</li> </ul>