agentleFS
teispaceteispace/teitunnel/.claude/skills/adding-doctor-checks/SKILL.md

adding-doctor-checks

Skill2 starsChanged 50 days agoMITView on GitHub

Adds a problem the Teitunnel Doctor detects (crates/core/src/doctor.rs), with the facts it gathers, a pure diagnosis, a translated title and detail, a one-click fix that goes through the plan engine, notification behaviour, tests and the Doctor reference page. Use when a recurring failure should be found and explained automatically instead of left to the person.

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 2 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    If the check needs information the Doctor doesn't collect yet, add it to Facts or AccountFacts in crates/core/src/doctor.rs and fill it in …

    line 30
  2. Distinctive:

    Avoid false positives: a check that fires wrongly teaches people to ignore the Doctor.

    line 57
  3. Distinctive:

    When a condition is transient (a connector reconnecting, DNS propagating), wait for it to persist.

    line 58
  4. Very specific:

    Add the check to apps/web/content/docs/reference/doctor.mdx: what it means and how the fix works.

    line 83

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Adding a Doctor check

The Doctor turns failures into a sentence and a fix. It runs at start-up, after every applied change, when a connector changes state, and on demand; doctor_monitor.rs notifies about new errors in the background.

Gathering and judging are separate: gather collects facts (I/O), diagnose is pure. That keeps every check fast to test.

Checklist

- [ ] 1. The fact: added to Facts / AccountFacts and filled in gather
- [ ] 2. The judgement in diagnose, with an id area.problem
- [ ] 3. Title, detail and evidence as catalog text
- [ ] 4. A fix, through the engine when it changes Cloudflare
- [ ] 5. Notification behaviour (QUIET_CHECKS)
- [ ] 6. Tests in doctor.rs
- [ ] 7. The Doctor reference page
- [ ] 8. pnpm verify

1. The fact

If the check needs information the Doctor doesn't collect yet, add it to Facts or AccountFacts in crates/core/src/doctor.rs and fill it in gather (or run). Reuse the observed engine snapshot; don't make an extra API call per check.

2–3. The judgement

In diagnose:

found.add(
    "dns.missing",                 // area.problem; stable, used to ignore it
    Severity::Error,
    hostname,                      // the subject
    msg::doctor::dns_missing::title(hostname),
    msg::doctor::dns_missing::detail(hostname),
    vec![/* evidence as Text */],
    vec![/* fixes */],
);
  • The id is area.problem. The issue's identity adds the account and subject, so "Ignore" survives restarts. Never rename an id.
  • The title says what's wrong in one sentence; the detail says what it means and what to do. Both come from locales/en.json under core.doctor (see writing-user-facing-text).
  • Severity: Error when something people rely on is broken, Warning when it will break or is wasteful, Info for advice.
  • Avoid false positives: a check that fires wrongly teaches people to ignore the Doctor. When a condition is transient (a connector reconnecting, DNS propagating), wait for it to persist.

4. The fix

  • A fix that changes Cloudflare is Fix::Change { label, change }, so it goes through the planner, is shown as a plan and can be undone (see changing-cloudflare-resources).
  • Local fixes (start a connector, clean stale connections) have their own Fix variants.
  • fix_safe backs Fix Safe Issues: include a fix there only if its plan touches nothing but what Teitunnel owns and needs no confirmation.
  • A problem only the person can solve (reconnect an account, install something) gets guidance instead of a fix.

5. Notifications

Errors notify once when they appear. If the problem is already announced another way, or flaps with the network, add its id to QUIET_CHECKS in crates/core/src/doctor_monitor.rs.

6. Tests

In doctor.rs's tests: build Facts, call diagnose, and assert the issue, its severity and its fix. Add the healthy case that must not fire.

7. Docs

Add the check to apps/web/content/docs/reference/doctor.mdx: what it means and how the fix works.

8. Verify

CARGO_INCREMENTAL=0 cargo nextest run -p teitunnel-core -E 'test(doctor)'
pnpm verify

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.