| name | troubleshoot-connectivity |
| description | Isolate a network connectivity fault methodically, bottom-up the OSI stack (L1 link -> L2 VLAN/ARP/MAC -> L3 routing/ACL -> L4 port/firewall -> L7 DNS/app), naming the specific isolating test and confirming command at each layer, then return the ranked most-likely fault and how to confirm it. Reach for this when the user says "X can't reach Y" or reports intermittent/slow connectivity. Used by `network-operations-engineer` (primary). |
Skill: troubleshoot-connectivity
Invoked by: network-operations-engineer (primary).
When to invoke: "users at X can't reach Y"; "the link is slow/flapping"; "intermittent drops"; any reachability or performance fault.
Output: a bottom-up OSI isolation walk with the confirming command at each layer + the ranked most-likely fault. (You produce the walk + commands; the live devices are outside the repo.)
The method: isolate, don't guess
Never change config "to see if it helps." Find the working boundary, then bisect toward the break. Walk the layers bottom-up — most "routing problems" are really layer 1 or 2.
| Layer | Check | Confirming command (vendor-portable) |
|---|
| L1 — physical | Link up? Errors/CRC? Duplex/speed mismatch? SFP/cable? | show interface (status, errors, duplex); check optics/light levels |
| L2 — data link | Right VLAN? MAC learned? ARP resolving? STP blocking? Trunk allowing the VLAN? | show mac address-table, show arp, show spanning-tree, show interface trunk |
| L3 — network | Route to the destination? Correct gateway? ACL dropping? Asymmetric path? MTU/fragmentation? | ping, traceroute, show ip route <dst>, show access-lists, ping with DF + size for MTU |
| L4 — transport | Port open? Firewall/stateful drop? NAT correct? Connection table? | telnet/nc <host> <port>, firewall session/log, show nat translations |
| L7 — application | DNS resolving (right answer, sane TTL)? TLS/cert? App health? Load-balancer probe? | dig/nslookup, curl -v, load-balancer health/pool status |
Procedure
- Scope the fault precisely — who/what is affected, who is not, since when, what changed. The fault is usually where the symptom isn't — the working users define the boundary.
- Establish the working boundary, then bisect: test reachability from progressively closer/farther points (same VLAN → gateway → next hop → destination) to localize the break to a segment.
- Walk the layers bottom-up at the localized segment, running the confirming command at each. Stop at the first layer that fails — that's your fault domain.
- Form a single hypothesis and confirm it with a command before acting (Capability Grounding Protocol: the network's state is a hypothesis until a
show/ping/dig/tcpdump confirms it).
- Check "what changed" against the change log — a recent change is the prime suspect; this is why
plan-network-change insists on documented diffs.
- Fix at the cause, leave a guardrail, and capture the diagnosis for the next person.
Common fault signatures
- Works locally, fails across subnets → L3 (route/gateway/ACL).
- Intermittent / one-directional → asymmetric routing, MTU/fragmentation, or a flapping link.
- DNS name fails but IP works → L7 DNS (resolution path / stale TTL / split-horizon).
- Slow not down → duplex mismatch, congestion/drops, MTU, or an overloaded link — check interface errors and utilization.
- New host can't get on → L2 (wrong VLAN / NAC denial / DHCP scope exhaustion).
Output contract
Scope: <affected vs unaffected, since when, what changed>
Boundary: <working point ... break localized to <segment>>
OSI walk: <per-layer result + the command that showed it>
Most-likely fault: <ranked> — confirm with <command>
Fix + guardrail: <cause fix + how to prevent recurrence>
Then emit the Structured Output Protocol JSON block.
