feat: add Network Troubleshooting skill (.mdc rule)

[CacinieP]

Summary

Add rules/network-troubleshoot.mdc, a safety-first Cursor rule for developer network failures.

The rule is intentionally scoped as a concise decision guide, not a full troubleshooting toolkit or automatic remediation script.

What it does

• Collects the exact error, failing command, target host/URL/port, OS/shell, and proxy/VPN context.
• Classifies common failures such as refused/reset connections, DNS failures, proxy errors, TLS certificate errors, HTTP gateway failures, package registry timeouts, and Git network failures.
• Guides read-only, target-scoped diagnostics against the failing host, URL, registry, or service.
• Explains diagnostic results before suggesting fixes.
• Requires explicit user approval before any remediation, unrelated external probe, or persistent configuration change.

Safety boundaries

• Does not print raw proxy URLs, credentials, tokens, auth headers, package index URLs, internal hosts, registry hostnames, or raw config values.
• Does not dump npm, pnpm, yarn, pip, Git, Docker, shell, OS proxy, VPN, or certificate-store config.
• Does not disable or bypass TLS/certificate verification.
• Does not hardcode unrelated public probe targets.
• Does not mutate OS networking, DNS, proxy, package manager, Git, Docker, shell, VPN, or trust-store settings automatically.

Source repo

https://github.com/CacinieP/network-troubleshoot-skill

The Cursor adapter in the source repo has also been synced to this safety-first version.

Validation

• node scripts/check-repo-hygiene.mjs --only rules --changed-files .changed-files.local
• node scripts/check-repo-hygiene.mjs --only security --changed-files .changed-files.local

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds rules/network-troubleshoot.mdc, a developer-facing network troubleshooting playbook with a 5-step workflow, error-pattern classification, cross-platform diagnostic commands, a diagnosis→fix matrix, China proxy quick-fix snippets, and post-fix verification steps.

Changes

Network Troubleshooting Guide

Layer / File(s)	Summary
Troubleshooting framework and diagnostics rules/network-troubleshoot.mdc	Front-matter metadata, workflow definition, error-pattern classification spanning connectivity, firewall, timeouts, DNS, proxy, SSL/TLS, HTTP, package managers, and git. Cross-platform diagnostic command sets for each category, resolution matrix mapping diagnoses to fixes, China-environment proxy/registry quick-fix for Bash and PowerShell, and post-fix verification steps.
Verification and quick-reference rules/network-troubleshoot.mdc	Post-fix verification commands (curl/nslookup/PowerShell), concise error quick-reference list, and directive to explain command purposes and interpret outputs before suggesting fixes.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Suggested reviewers

• PatrickJS

Poem

🐰 I hopped through packets, traced each route,
Curl and nslookup, outputs to scout.
From DNS to proxy, TLS in a glance,
I stitch fixes together—one confident prance.
Hop on, reviewer, let's clear the network's doubt!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically describes the main change: adding a new network troubleshooting skill as a Cursor rule file (.mdc).
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description check	✅ Passed	PR description covers the summary, contribution type, value, and quality checklist comprehensively with clear safety boundaries and validation steps.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (1)

rules/network-troubleshoot.mdc (1)

55-67: ⚡ Quick win

Add Windows-native alternatives for Unix-specific commands to keep the rule truly cross-platform.

Several snippets rely on shell semantics/commands (echo $VAR, grep, /dev/null) that won’t run in PowerShell/CMD. Add Windows equivalents near each section.

Also applies to: 76-80, 117-121

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@rules/network-troubleshoot.mdc` around lines 55 - 67, The snippets use
Unix-only shell features (echo $HTTP_PROXY, curl -v, grep, /dev/null, openssl
s_client) — add Windows PowerShell/CMD equivalents next to each Unix example:
show environment variables with PowerShell ($env:HTTP_PROXY, $env:HTTPS_PROXY,
$env:ALL_PROXY) and CMD (echo %HTTP_PROXY%), replace curl checks with
Invoke-WebRequest or Test-NetConnection / Test-Connection examples and show how
to specify a proxy in Invoke-WebRequest, replace grep with Select-String,
replace /dev/null with $null, and for SSL/TLS include a PowerShell alternative
to openssl s_client (e.g. using Invoke-WebRequest or
System.Net.Security.SslStream to fetch cert details and using Get-Date on the
certificate) so the blocks containing "echo $HTTP_PROXY", "curl -v", "curl -x",
"git config --global --get http.proxy", "openssl s_client" and the grep/curl
certificate checks have matching Windows-native commands.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@rules/network-troubleshoot.mdc`:
- Line 90: Replace the unsafe TLS-bypass snippet in the "SSL cert expired" row:
remove the dev guidance that suggests setting NODE_TLS_REJECT_UNAUTHORIZED=0 and
instead instruct renewing the certificate and safer dev options (e.g., install a
local/dev cert into the system or trust store, use a valid self-signed cert
generated for local testing, or use tools that support per-request trust flags
only for ephemeral debugging). Update the table row that currently contains "SSL
cert expired | Renew cert; dev: `NODE_TLS_REJECT_UNAUTHORIZED=0` |" to omit the
NODE_TLS_REJECT_UNAUTHORIZED suggestion and include one-line safer dev
alternatives.
- Around line 3-4: The frontmatter is invalid because globs is empty while
alwaysApply is set to false; update the rule frontmatter so they comply with the
contract by either populating globs with one or more file pattern strings (e.g.,
relevant paths/patterns) or by setting alwaysApply to true if the rule is
intended to apply globally—edit the frontmatter that contains the globs and
alwaysApply keys to implement one of these fixes.

---

Nitpick comments:
In `@rules/network-troubleshoot.mdc`:
- Around line 55-67: The snippets use Unix-only shell features (echo
$HTTP_PROXY, curl -v, grep, /dev/null, openssl s_client) — add Windows
PowerShell/CMD equivalents next to each Unix example: show environment variables
with PowerShell ($env:HTTP_PROXY, $env:HTTPS_PROXY, $env:ALL_PROXY) and CMD
(echo %HTTP_PROXY%), replace curl checks with Invoke-WebRequest or
Test-NetConnection / Test-Connection examples and show how to specify a proxy in
Invoke-WebRequest, replace grep with Select-String, replace /dev/null with
$null, and for SSL/TLS include a PowerShell alternative to openssl s_client
(e.g. using Invoke-WebRequest or System.Net.Security.SslStream to fetch cert
details and using Get-Date on the certificate) so the blocks containing "echo
$HTTP_PROXY", "curl -v", "curl -x", "git config --global --get http.proxy",
"openssl s_client" and the grep/curl certificate checks have matching
Windows-native commands.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 3a4bb75b-2bce-4cc6-9830-cd6958704e89

📥 Commits

Reviewing files that changed from the base of the PR and between 379532d and ccb6ab0.

📒 Files selected for processing (2)

• README.md
• rules/network-troubleshoot.mdc

[CacinieP]

I removed the README listing that triggered the repo-hygiene check and kept only the new rules/network-troubleshoot.mdc file. The current workflow shows action_required, so it may need maintainer approval to run.

[CacinieP]

Hi 👋 The repo-hygiene CI failure is not caused by this PR.

The check flagged two README entries that already exist on main:

• [React (Zustand)] → react-zustand-cursorrules-prompt-file.mdc
• [Vue (Pinia)] → vue-pinia-cursorrules-prompt-file.mdc

This PR only adds rules/network-troubleshoot.mdc and does not modify README.md at all (see the diff — only one file changed). The hygiene script scans the full README against its rules and caught pre-existing entries from earlier merges.

Could a maintainer either fix those entries on main or override and merge this PR? Thanks!

[PatrickJS]

im updating the lint rules

[coderabbitai]

Actionable comments posted: 0

[Copilot]

Pull request overview

Adds a new universal Cursor rule (rules/network-troubleshoot.mdc) intended to guide AI agents through a structured, cross-platform network debugging workflow (classification → diagnostics → resolution → verification).

Changes:

• Introduces a new network troubleshooting rule with diagnostic command sets for Windows/Linux/macOS.
• Adds an error-pattern classification table and a resolution matrix for common failure modes.
• Includes “quick fix” and verification recipes aimed at common proxy/GFW scenarios.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coderabbitai]

Actionable comments posted: 0

[CacinieP]

Thank you so much — I really appreciate you taking the time to update the lint rules and help this contribution move forward.

I just pushed a safety-first revision: removed all full config dumps (npm config list, pip config list, git config --list, docker info), TLS bypass examples (SkipCertificateCheck, NODE_TLS_REJECT_UNAUTHORIZED), persistent global config mutations (npm config set, pip config set, git config --global, export HTTP_PROXY), hardcoded public probes (8.8.8.8, google.com), and credential-exposing echo commands.

The rule now focuses on read-only diagnostics (npm config get <key>, git config --get <key>, single-key reads only), redacted interpretation, user-approved probe targets, and explicit confirmation before any persistent configuration change.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 5 comments.

[CacinieP]

Thanks for the review. I pushed a follow-up commit addressing the 5 Copilot comments:

1. Proxy config reads no longer print raw values — they report only whether each key is set, with a note to redact credentials before sharing.
2. SSL/TLS commands are marked Linux/macOS-only and paired with a PowerShell alternative that reads cert info without bypassing validation.
3. SSL cert advisory now explicitly states "Do not bypass TLS verification" — replaced "temporary workarounds" with installing trusted local/dev certificates or updating the trust store.
4. Safety rules updated: "without explicit user confirmation" for any persistent/global config change, and external probes require user-approved targets.
5. npm ping gated with a comment: only use when the failing target is the configured npm registry, or after user approval.

[CacinieP]

Just wanted to say thanks again — not just for maintaining this repo, but for actively updating the lint rules and helping this PR get to a mergeable state. It's rare to see a maintainer invest this level of care into a first-time contribution. Really appreciated.

[PatrickJS]

I think this rule can still meet the goal for the repo, but it needs to stay clearly scoped to safe diagnostics rather than automatic remediation.

The useful version is: help an agent collect the failing target/error, classify the likely network issue, run read-only checks against that target, explain the results, and then ask before suggesting or applying any state-changing fix.

A few changes would make this safe enough for an awesome-cursorrules entry:

• Do not print credential-bearing config values. Proxy, package index, registry auth, Git extraheader, and similar checks should be presence-only or explicitly redacted.
• Remove raw reads like pip config get global.index-url; private package indexes often include credentials or internal hostnames.
• Avoid vague TLS wording such as “temporary workaround.” The rule should name safe fixes: renew the certificate, fix system time, install a trusted local CA, or update the trust store. It should explicitly say not to disable TLS/certificate verification.
• Treat commands such as ipconfig /renew, DNS changes, proxy changes, registry changes, and Docker config edits as user-approved resolution actions, not diagnostics.
• Keep probes target-scoped: use the failing host by default and ask before probing unrelated third-party services.

With those boundaries, the rule still accomplishes the intended goal: systematic developer network troubleshooting. It just does so without teaching agents to leak secrets, bypass TLS, or mutate network state while pretending to diagnose.

[PatrickJS]

One broader framing point to avoid overcorrecting this PR: I would not turn this .mdc file into a full troubleshooting toolkit.

For awesome-cursorrules, the strongest shape is a concise decision guide: collect the failing command/target/error/context, classify the likely issue, run safe read-only checks scoped to the failing target, explain the results, and ask before any remediation.

If the goal is deeper automation, that is probably better handled by helper scripts or a tool-backed skill outside this catalog entry. The rule can still say to prefer trusted project-provided diagnostic scripts when available, but the .mdc itself should avoid embedding lots of risky shell logic, raw config reads, or state-changing fixes.

[CacinieP]

Thanks for the clear guidance. I pushed a follow-up revision that scopes the rule down to a safety-first decision guide rather than a full troubleshooting toolkit.

Main changes:

• Removed sensitive config value reads and raw package/proxy/Git config checks.
• Removed mutating network actions such as DHCP renewal from diagnostic guidance.
• Removed hardcoded public probes and automatic registry/proxy remediation.
• Kept diagnostics target-scoped and read-only by default.
• Moved remediation into explicit user-approved options.
• Synced the source repo Cursor adapter to the same safety-first version.
• Updated the PR description to match the narrower scope.

I also verified the updated rule with:

node scripts/check-repo-hygiene.mjs --only rules --changed-files .changed-files.local

node scripts/check-repo-hygiene.mjs --only security --changed-files .changed-files.local

Both checks pass now. Please let me know if you’d like this tightened further or if catalog/README placement should be left to maintainers.