pua-debugging-pro_skill

Overview

This skill implements a professional, evidence-first debugging protocol for agents that start looping, deflecting to users, or attempting premature termination. It enforces bounded escalation, structured verification, and dignified communication to improve diagnosis and reduce wasted cycles. Use it to turn repeated, low-agency failures into narrow, testable investigations.

How this skill works

The skill monitors iteration history, error outputs, and agent questions to detect trigger signals like repeated failures, unverified blame, or surface fixes. When triggered it applies an escalation ladder (L1–L3) and a 7-point diagnostic checklist to compel different hypotheses, capture exact evidence, and require validation steps. Outputs always include current hypothesis, actions executed, observed evidence, and the next step; if blocked after full escalation it produces a concise stop report with facts, eliminated options, unresolved uncertainty, and recommended next action.

When to use it

• After 2+ failed attempts toward the same objective
• When the agent keeps making micro-tweaks with no new signal
• If the agent deflects to the user without prior tool-based diagnosis
• When blame is asserted for environment/permissions/network without verification
• When completion is claimed without explicit validation or tests

Best practices

• Always gather and paste exact error text and relevant context before changing course
• Switch to a materially different hypothesis after repeated failures rather than repeating the same approach
• Run at least one external lookup or documentation check at L2 to avoid local blind spots
• Define clear pass/fail criteria for each attempt and record the validation result
• Use calm, factual language; avoid humiliation or defensive phrasing when communicating to users
• Stop and escalate when the 7-point checklist is complete and further attempts require external access or decisions

Example use cases

• Debugging a flaky test suite where fixes repeatedly fail to address failures
• Investigating a long-running script that silently exits or loops without producing useful logs
• Handling an agent that repeatedly asks the user for permission or input without first using available diagnostics
• Diagnosing environment-dependent failures where the agent blames versions or permissions without verification
• Producing a one-page handoff when an issue requires escalation to ops or a senior engineer