Sections marked with TODO are experience samples to be supplemented through practice (incremental content that does not affect usability); for triage status, see skills/README.md.

maa-evidence

1. Evidence First: Every diagnostic conclusion must be supported by real-time observation evidence — current frame, recognition hit/miss and score, logs, comparison between box and click position; "maybe" must be converted into a verifiable hypothesis before testing, and conclusions based on guessing are prohibited (aligned with the exploration-first principle of maafw-pipeline).
2. One Variable at a Time: Only one of threshold / ROI / template / parameter is changed at a time, and retest immediately after the change with records kept; result changes from simultaneous multiple changes cannot be attributed — this is the top discipline in debugging mode.
3. Use Framework Pipeline: Screenshots and clicks for diagnosis must go through the framework's screenshot pipeline (observation base / framework screenshot API / runtime tool), external screenshot tools are not allowed — resolution and image space must be consistent with recognition input (the pixel space consistency principle inherits from maafw-pipeline asset standards).
4. Position Only, Do Not Fix: This skill produces "root cause conclusion + evidence". Boundary: temporary changes for hypothesis verification followed by immediate retest are allowed (Hard Guardrail 2 "One Variable at a Time" is exactly for this purpose), but the deliverable is still conclusion + evidence. Fix implementation goes through handover (recognition/flow → maafw-pipeline, integration/options → maafw-interface, custom → maafw-custom; minor adjustments like ROI fine-tuning are already included in the modification track) — no structural changes while positioning.
5. Judgment Hierarchy: Distinguish between call success (whether the command finishes execution), task success (task-level result + actual recognition hit), and business acceptance success (functional behavior meets expectations) — the three layers cannot replace each other, and call-layer signals (outer ok / exit code) cannot be used as task or acceptance conclusions; specific judgment fields and exit code semantics depend on the tool (for maafw-live, see judgment points in tooling.md). A single successful run ≠ stability — acceptance requires repeated runs, including cold start and reconnection scenarios.
6. Preserve Debugging Scenes Promptly: Key frames during debugging should be promptly promoted to the key frame library (preserved by the observation base), as the scene cannot be reproduced once passed; offline post-hoc analysis is transferred to

   maa-evidence

   .

• references/diagnosis-tree.md — Troubleshooting Tree: symptom → check items → common root causes (configuration layer details, silent disconnection surface list, threshold and ROI empirical values)
• references/tooling.md — Evidence Collection Methods and Tool Matrix: working modes, maafw-live default execution path and judgment points, alternative tool capability mapping, check points for each layer and tool replacement judgment

• Log interpretation rules for each branch of the troubleshooting tree (log snippet → conclusion interpretation samples)
• Recognition slowdown (performance) troubleshooting branch; debugging points for ColorMatch / And / Or / self-trained model nodes
• Standard minimum reproduction process and evidence snapshot checklist for each layer (including the "minimum evidence sequence" template for the flow layer)
• Acceptance record template (verification object, scope, actual result, evidence, implementation fingerprint — aligned with the tested semantics of state-plan, pending its schema freeze)

Inline TODOs in the troubleshooting tree / tool documentation are only position markers, and this section is the sole checklist and completion criterion.