{"id":53995,"plugin_id":"plugins_6ac9709535408191a8dc938884a91227","kind":"skill","collection_source":"plugin_package","comparison_source":null,"observed_at":"2026-10-24T13:55:40.397Z","digest":"af8878bd925697defb2bb422e030377baf286cda9ce4c67a7949642d591cd5ef","against":null,"payload":{"description":"Diagnose and fix PlatformIO build, upload, and configuration failures. Use when resolving compiler errors, missing libraries, platformio.ini issues, memory overflows, port conflicts, permission errors, failed uploads, crash backtraces, or firmware size analysis.","included_files":[],"name":"platformio-debug","skill_md_contents":"---\nname: platformio-debug\ndescription: Diagnose and fix PlatformIO build, upload, and configuration failures. Use when resolving compiler errors, missing libraries, platformio.ini issues, memory overflows, port conflicts, permission errors, failed uploads, crash backtraces, or firmware size analysis.\n---\n\n# PlatformIO Debug\n\n> **Reading results:** a non-zero exit means look at BOTH streams. An operation\n> that ran but failed (a build with errors) puts `success: false` on **stdout**;\n> one that could not run (bad arguments, policy, a busy port) puts `errorType` on\n> **stderr** with stdout empty. Capture stdout and stderr separately with `--json`. See the\n> `pio-manager` skill for the full contract.\n\n## Purpose\n\nUse this skill when a PlatformIO project fails to build, upload, or pass static checks.\n\n## Safety Rules\n\n- Do not hide raw error logs. Summarize them and preserve the log path.\n- Do not make broad dependency changes without explaining why.\n- Do not flash firmware unless the user explicitly approves.\n\n## Workflow\n\n1. Call `pio-agent project context --project-dir <dir>`, resolve one environment, and run `pio-agent agent-build-diagnose --project-dir <dir> --environment <env>`.\n2. Use its structured diagnostics, `nextSteps`, task ID, and log paths before reading broad logs.\n3. Extract the smallest redacted error snippet.\n4. Identify the likely root cause.\n5. Patch code, dependencies, or `platformio.ini`.\n6. Rebuild with `pio-agent build --project-dir <dir> --environment <env> --json`. Retry automatically only when `safeToAutoRetry` is true and the retry remains bounded.\n7. Repeat until build succeeds or a configuration, dependency, policy, approval, or hardware blocker is identified.\n8. Summarize the exact fix.\n\n## Error Types\n\nClassify failures as one of:\n\n```text\nMissingHeader\nMissingLibrary\nWrongBoard\nWrongFramework\nSyntaxError\nLinkerError\nMemoryOverflow\nDeviceBusy\nPermissionDenied\nUploadFailed\nUnknown\n```\n\nFor upload failures, resolve the target binding again before retrying. Treat port drift as safe only when the stable device fingerprint still matches; stop on substitution or ambiguity.\n\n## Dependency audit\n\nUse `deps_check` with `projectDir` and an optional `environment` to inspect\ndeclarations and installed library manifests. `build` defaults to false. An\nexplicit `build: true` requires separate build permission and returns LDF graph\nevidence. Inspect `inventoryComplete`, diagnostics, and graph status before\nclaiming the audit is clean. Name collisions and leftover-library findings do\nnot prove which library was linked. Scoped approvals are separate for the\noverall request, configuration, inventory and optional build stages.\n\n## Crash and size analysis\n\nUse `decode_backtrace` with `projectDir`, `environment`, and the captured `text`.\nKeep `includeAllHex` false unless the trace format requires it; arbitrary hex\nvalues need not be code addresses. Supply `expectedElfSha256` when the matching\nfirmware identity is known, or `archivedElfSha256` for an available retained ELF.\nKeep unresolved frames explicit. Decoding against an ELF does not prove that ELF\nmatches the firmware currently running on the board.\n\nUse `size_report` with `projectDir`, `environment`, and optionally `top` or\n`filter` to locate large symbols and sections. These operations may execute\nPlatformIO build metadata collection and require its permission even when no\nhardware is contacted. Static symbol sizes do not measure runtime heap/stack\nuse; inspect accounting and partition evidence before diagnosing flash overflow.\nThe dashboard command feed shows a bounded preview; use the tool result for the\nfull returned analysis.\n\n## Permission failures\n\nCall `get_policy_status` for the same `projectDir`. Inspect `valid`, `source`,\n`sources`, `projectEnrollment`, and the allowed/approval-required/denied lists.\nAn invalid policy is a configuration error, not permission to fall back to a more\npermissive profile. Follow the reported source and error to correct it within the\nuser's authorized scope, then read status again.\n\n`serverPolicy` describes this server's gates. `hostPolicy` reports external host\nenforcement with unknown effective runtime permissions. Do not interpret a server\nallow as approval from Codex or another MCP host, or edit host `config.toml` to\nbypass a denial. Preserve customized host tool settings during installation.\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}