comm-link-debugging

Debug integration issues in communication / data-transfer links across systems, when you only control one end and the peer is not visible. This skill is a comm-link integration methodology — for one of the most common classes of cross-system debugging: handling the traps that hit hardest when "the peer is a black box and you only control your side".

Scope statement: cross-system debugging covers more than comm links — it also includes data consistency, multi-module timing, cross-team contract-understanding gaps, and hardware-software state sync, among non-comm problems — those are out of scope here. Of the five steps: ② cross-end claim-vs-evidence clash, ③ push your side to the limit then read the peer, and ⑤ lowest-cost diagnosis for the peer, generalize to non-comm cross-system cases; ① layered native-signal verification and ④ reachability principle lean toward comm / protocol-stack links.

When to use

• A comm-link integration is stuck: client↔server, phone↔device, data channels between hardware and software, cross-network / cross-service transport
• "They said they sent it but I didn't get it" / "I sent it but they say they didn't receive it"
• Stuck at some protocol layer (network? handshake? transport? application semantics?) and you cannot tell which
• The peer is another team / system / AI / vendor, and you can only see your side

When NOT to use

• Bugs inside a single system (use error-handling)
• Pure own-side code-logic problems
• Non-comm cross-system problems (data consistency / timing / contract gaps, etc.)

Core principle: reachability / correctness does not transfer across layers

A comm link is organized as a protocol stack. "Connected / correct" at one layer does not imply "connected / correct" at an adjacent layer — each layer has its own failure modes invisible to neighbors.

Generic counter-examples (protocol-independent):

→ To verify the layer under suspicion, use that layer's own native observable signal; do not proxy a conclusion with a neighbor-layer signal.

Methodology (five steps)

① Layered localization + native signal verification

Slice the comm link by protocol stack layers, locate the layer where the failure most likely happens, and verify with that layer's own native signal / tool. This is because "connected / correct" does not transfer across layers (see core principle).

• Do not proxy with a neighbor-layer signal: "ping works so the network is fine" — ping is network-layer (ICMP); what's failing is transport-layer (UDP/TCP); they are different things.
• On your own application layer, do not assume success when calling a lower-layer API — check return values / success flags. Typical case: the Boolean returned by send() / publish() is ignored, the application layer wrongly concludes "sent", and in reality the message never entered the queue (buffer full / transient state). The return value is the native success signal of that call as it crosses the boundary; not checking it means sending blind.
• At the lowest layer, verify with protocol bytes / packet contents — when application logs cannot tell, enable verbose logging in the low-level library and parse protocol packets directly (chunk type / field values) to judge data flow direction and handshake state. This is more native and harder to lie than application-layer logs.
• Fill the layered verification table row by row: layer / native signal or tool / result (connected / not connected / unknown).

② Cross-end claim-vs-evidence clash

(Generalizes to non-comm cross-system cases.) Take the conclusions the peer (another team / system / AI / vendor) gives, and clash them line by line with your own runtime evidence to find contradictions. The true root cause often lives in those contradictions.

• Do not blindly trust a single-side conclusion, and do not reject it outright either — use evidence clash to localize.
• Typical: the peer says "network unreachable / no pair connectivity", while your own log shows "a successful response from the peer (code=0 / rtt=X)" — the latter could only have come from the peer; the contradiction is the lead.
• Clash the peer's "protocol-layer judgment" too: the peer says "this is an X-type packet", but your byte-level parse shows it is actually Y (e.g., misjudging a STUN packet as a data-channel packet) — trust the bytes.

③ Push your side to the limit → switch to reading the peer's implementation

(Generalizes to non-comm cross-system cases.) When you have no more observables or tunables on your own side (the logs that should be read have been read, the switches that should be tried have been tried, all return values checked), shift the focus to the peer's implementation (source / config / logs), because the problem most likely lives on the peer.

• Maintain an "own-side tunable checklist" and mark it exhausted — to avoid spinning in place on your side.
• Read the peer's code to look for bugs, but watch step ④.

④ Runtime over static artifacts

(Leans toward comm links: protocol parameters / config are often out of sync.) The source / config / declarations in hand may not be the version actually running. Any "the code says X" conclusion must be confirmed with runtime evidence (runtime logs / packet capture / probe output); otherwise you may be debugging against stale or non-effective static artifacts.

• Typical: source says 640×480, runtime actually outputs 320×240 → source ≠ the running binary.
• Three or more independent contradictions (resolution / frame rate / parameter-level mismatches) → it is almost certain that "the source given is not what's running"; stop debugging against it and demand runtime evidence.

⑤ Lowest-cost diagnosis for the peer

(Generalizes to non-comm cross-system cases.) When the ball is on the peer's side, design one diagnostic instruction that the peer can run at lowest cost and that definitively splits the root-cause direction (using a probe / packet capture / log switch that the peer's environment already provides); running one line should converge the root cause into a few directions and avoid guesswork ping-pong.

• Bad example: asking the peer to "re-check the entire pipeline" — high cost, vague feedback.
• Good example: a single tcpdump / raising a module's log level / a built-in probe switch, with output that directly splits ("packets leaving → sending side is fine" / "no packets leaving → sending side is the problem").
• For each diagnostic, annotate: what to run, and which root-cause directions it can split into.

Output template

# Comm-link integration troubleshooting

## 1. Layered verification (native signal)
| Layer | Native signal / tool | Result |
|-------|----------------------|--------|
| ... | ... | connected / not connected / unknown |

## 2. Cross-end claim-vs-evidence clash
| Peer's claim | Our evidence | Contradiction? | Direction it points |
|--------------|--------------|----------------|---------------------|
| ... | ... | yes / no | ... |

## 3. Own-side tunables (marked to the limit)
- [ ] Checked / tried ... (to the limit)

## 4. Peer diagnostic instructions (lowest cost, definitive split)
| Instruction | Root-cause directions it can split |
|--------------|------------------------------------|
| ... | ... |

## 5. Root cause (one sentence)
____

Relationship to other skills

• Can be referenced by error-handling: when error-handling's "localization" stage runs into a comm-link / peer-invisible scenario, link here as the dedicated methodology. The specialized content lives only in this skill, avoiding duplication and update drift.
• Complementary to deep-comparison-analysis: the latter is the "comparison and convergence" methodology; this skill is the "comm link troubleshooting and localization" methodology.
• Scope boundary: this skill is the comm-link sub-class of cross-system debugging; non-comm cross-system problems (data consistency / timing / contract gaps) are out of scope and may warrant a dedicated skill once enough cases accumulate.

Practice reference (optional, as an appendix example)

The methodology is fully generic and not tied to any specific protocol or stack. If a project already contains a complete cross-system comm-link integration case (e.g., WebRTC / MQTT / gRPC / HTTP / WebSocket cross-service debugging), it can be referenced as an appendix example — walk the five steps over that concrete scenario. But the methodology does not depend on any case existing.