"The code didn't lie, but the black-box system's behavior isn't in the code."
When environments beyond the code are involved (browsers, editors, CDNs, IM platforms, third-party APIs), both coding and debugging mustcapture real data first, then reason。
When to Trigger
Coding Scenarios
- Outputting content that will be consumed by third-party platforms (HTML pushed to CSDN/WeChat/Notion/DingTalk/Feishu)
- Integrating browser/OS APIs (Clipboard / Drag-Drop / File System)
- Calling third-party HTTP APIs that go through CDN/WAF/reverse proxy
- Rendering content in IM / rich text editors
Debugging Scenarios
- Inconsistent behavior across browsers/devices/terminals
- Abnormal paste/copy behavior
- Third-party API returns weird results (empty body, incomplete headers, 200 but error)
- Local reproduction fails but problems occur online
- Consecutive 2 rounds of "reasoning from code" fixes are both no-ops(strongest signal)
Black-Box Determination Checklist
| Dimension | Not a black box | Is a black box (triggers this skill) |
|---|---|---|
| Control | Code you wrote yourself | Third-party/platform/browser implementation |
| Documentation completeness | Has complete API documentation | Documentation incomplete or has undocumented behavior |
| Debuggability | Can add logs, breakpoints | Can only observe input and output from outside |
| Behavior predictability | Given input necessarily yields given output | Same input behaves differently in different environments |
Satisfying any 2 items → follow this skill's methodology.
Data Collection Template (Core)
For different black-box types,what the user should capture first:
| Black-Box Type | Priority Collection | Tool/Method |
|---|---|---|
| Browser paste/copy | Actual clipboard HTML | navigator.clipboard.read() List all mime types + print outerHTML |
| Third-party editor rendering | DOM before paste vs after paste | Copy outerHTML from DevTools Elements and diff |
| Cross-browser rendering | Real device screenshot + DOM structure | Real device/BrowserStack; not just look at the effect, must copy the DOM |
| HTTP third-party API | Complete request/response | curl -v / Charles / mitmproxy; compare GET vs POST |
| CDN/WAF interception | Intermediate node information | curl -I look at Server / Via headers; empty body + minimal headers is a strong signal |
| IM platforms (WeChat/DingTalk/Feishu) | Actual rendering on both send and receive ends | Must use real device screenshots; cannot only look at the send end |
| Operating system clipboard | All available mime types | navigator.clipboard.read() / macOS pbpaste -Prefer html |
| Mobile webview | UA + actually loaded CSS/JS | Chrome DevTools remote debugging |
⚠️ Capturing data must preserve the original format:For HTML use outerHTML instead of innerText, for JSON use raw bytes, for binary use hexdump.
Debugging decision flow
Bug 现象 → 涉及外部黑盒?
├─ 是 → 数据采集模板 → 基于数据做假设 → 单变量验证 → 修复 → 追加到 references/
└─ 否 → 走通用 systematic-debugging
Key nodes:
- Do not skip data collection:The phenomenon described by the user may be inaccurate; real data is the truth
- Hypotheses must be based on data:Every hypothesis must be able to cite specific captured results, not "I thought"
- Single-variable verification:Change only one variable at a time to verify the hypothesis
- Must consolidate after fixing:Append new cases to
references/case-{name}.md
Anti-pattern warnings (iron rules)
| ❌ Anti-pattern | ✅ Correct approach |
|---|---|
| "I thought the browser would preserve attribute X" | "Actually tested this browser's behavior for attribute X: [captured data]" |
| Two consecutive rounds of "reasoning from code" fixes are no-op, and the third round continues reasoning | On the third roundmust stop, and have the user output real data |
| Use try-catch / global polyfill fallbacks to mask behavior that is not understood | First understand the black box's actual behavior, then decide whether a fallback is needed |
| Change multiple variables at once and try your luck | Single-variable verification, with evidence to follow |
| Once fixed, it's done; the case stays only in your head | Append references/case-{name}.md, with the title containing the system name + symptom |
| Relying on "mainstream editors/browsers should all support X" | List the versions actually tested; mark untested ones as unknown |
Boundaries with other skills
| skill | When to use | Relationship to this skill |
|---|---|---|
superpowers:systematic-debugging |
General bug debugging | Upstream general methodology; this skill adds the hard rule of "capture data first" on top of it |
api-design-safety |
When designing your own API | Proactive design; this skill is passive adaptation to third parties |
Case library
After fixing, append new cases to references/,Naming convention:
| Prefix | Purpose | When to use |
|---|---|---|
case-{system}-{symptom}.md |
Real case:Has already occurred, including specific root cause/fix/lesson | Consolidating pitfalls encountered |
template-{system}-{symptom}.md |
Placeholder framework:A template to fill in when this type of system encounters a bug in the future | Reserve direction, prefill collection template |
After filling in the pitfalls for the template- file, please rename it to case-, keeping the semantics clear.
Currently available:
- CSDN paste list bug — HTML→MD loses the start attribute, causing 4 "1." items and huge spacing
- HTTP CDN/WAF interception — body empty + headers extremely minimal, GET normal but POST abnormal
- Proxy keyword substring matching misjudgment — A normal long article containing the Cloudflare keyword is misjudged by the proxy as a false-success error; fixed by splitting strong/weak features
- Browser paste behavior differences (template) — To be added
Rule provenance
> 📋 本回复遵循:`external-system-debugging` - [章节]