Skip to main content
skill CX Codex

doctor · orwa-mahmoud — Claude Code skill: diagnosis and installation

The doctor Claude Code skill diagnoses a Nightshift project and reports detected issues. Run it to inspect the workspace, shift state, markers, and deadlines.

MIT ★ 571 updated 2026-11-16

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add orwa-mahmoud/nightshift --skill doctor -a claude-code
Open on GitHub

What doctor does

doctor inspects a Nightshift project without changing its files. Its report covers the workspace, rules, markers, session, process lease, and shift deadline, along with open tasks and staged work.

The skill labels suggested actions [safe], [confirm], or [blocked]; it reports them but does not carry them out. It does not run project tooling, and the project tree remains unchanged after invocation. Commands go through runtime/ns, which resolves the plugin and workspace paths.

What it helps with

  • find why Nightshift considers a workspace invalid
  • spot an incomplete setup or malformed work mode
  • inspect warnings about markers, sessions, or process leases
  • tell which reported actions are safe, need confirmation, or are blocked

Example prompts for the agent

  • Diagnose this Nightshift project and explain the warnings.
  • Check the shift state and list suggested actions without carrying them out.
  • Find why the Nightshift workspace fails its checks.

How to install doctor

1Skills CLI (Vercel)

npx skills add orwa-mahmoud/nightshift --skill doctor -a claude-code

2Manually: put the files in place

~/.claude/skills/doctor/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/doctor/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about doctor

How do I install doctor in Claude Code?

Run npx skills add orwa-mahmoud/nightshift --skill doctor -a claude-code. The skill file is installed at ~/.claude/skills/doctor/SKILL.md.

What does doctor do?

It inspects a Nightshift project and reports findings, warnings, and classified actions. It does not repair the project or change its files.

Does doctor apply the actions in its report?

No. It labels actions [safe], [confirm], or [blocked] but only reports them. Running the skill leaves the project tree unchanged.

Source text

SKILL.md · MIT
---
name: doctor
description: Read-only diagnosis of the workspace, rules, markers, lease, watchman and deadline, with classified next actions; never repairs anything.
license: MIT
metadata:
  internal: true
---

Diagnose the host-opened project **without changing anything**. Doctor is deeper than status: it
explains what Nightshift resolved and which failures that implies. It does not arm, stop, revive,
rewrite, or delete.

The four state files and what each holds are in
`$NIGHTSHIFT_PLUGIN_ROOT/skills/nightshift/references/shift/state-map.md`. Report these as different categories; do not merge or move them.

Resolve the installed plugin root to an absolute `$NIGHTSHIFT_PLUGIN_ROOT` — `${CLAUDE_PLUGIN_ROOT}`
on Claude Code, `$PLUGIN_ROOT` on Codex when set, otherwise the absolute path this skill was
attached from (`skills/doctor/SKILL.md`). Run every command below through
`"$NIGHTSHIFT_PLUGIN_ROOT/runtime/ns"` — native Windows: `& "$NIGHTSHIFT_PLUGIN_ROOT\runtime\windows\ns.ps1"`
in the PowerShell tool, same verbs — which resolves the host and the workspace; `ns help` lists the
verbs, and `ns bind` prints the six resolved facts (`TASK_ROOT`, `NIGHTSHIFT_WORKSPACE`, `NS`,
`NIGHTSHIFT_PLUGIN_ROOT`, `HOST`, `SOURCE`); `$NS` below is that `NS`. Never a bare relative path: the working
directory persists between calls. Each `$NS/...` path below is where the current layout keeps that file;
`ns path <key>` prints where this workspace keeps it, and `ns path --list` names every key.

## 1. Run the inspector

```bash
"$NIGHTSHIFT_PLUGIN_ROOT/runtime/ns" doctor
```

Print its report verbatim. Do not summarise away Facts, Warnings, or Actions, and do not re-derive
anything it already resolved: the script uses the same workspace, work-mode, work-target, policy
and ownership libraries as the hooks, and both implementations print the same lines.

The report answers, in its own words: where the workspace is and whether `.nightshift-link` is
valid; the schema version and whether it is current, legacy, malformed, or newer than this plugin;
work mode and work target; the punch-list and staged-work counts; each parking-lot or snag-log
paragraph Archive can never file, by file and line; markers, session, process lease
and watchman liveness; the deadline and whether it disagrees with the shift policy; an interrupted provisioning transaction; every
`rules.json` knob it needs and the three native question-tool entries; a `resolved policy` block
naming every effective setting with its source (`built-in`, `rules`, `defaults`, `one-shift` or
`exact-plan`) and expiry (`shift`, `permanent` or `-`); and a `preflight` fact naming which items
need an elevation category the resolved policy does not grant.

Staged work is reported, never offered, while the punch list has open items. Doctor suggests
promoting a draft or a parked Hunt order only when no `- [ ]` remains under `## Items` and no shift
is armed — the same precedence Start applies. With open work, say what is staged and say plainly
that Start works the current list; do not read a count as an invitation to widen the approved
scope, and never promote anything from this read-only skill.

The `work mode` fact is `repository` or `artifact`. When `$NS/run/work-mode` is missing and Setup
would propose artifact, Doctor warns `work mode is unset; Setup would propose artifact` and offers
`persist the proposed artifact mode with Setup; Doctor does not write work-mode`. When work-mode is
unreadable it warns `work mode is malformed; treating the site as unusable until Setup rewrites it`,
and when the target cannot be resolved it warns
`work target could not be resolved; treating workspace as the code root`. When the record is
missing the resolver takes the workspace or its single immediate child repository.
Skip a symlink or reparse child; it is not a nested checkout.

In artifact mode the report also carries `artifact receipts N` for files under `$NS/receipts/`,
and `latest artifact receipt` with the filename only of the most recently written receipt (no
directory path). When receipts are enabled it reports `completion record per-item receipt` and,
if ticked items have no model text, warns
`N ticked items have no receipt text; each item completes through its receipt file`. Disabled
receipts are a fact only: `completion record none; the owner disabled receipts`. When the path exists but is not a real
directory, it warns `artifact receipts path is not a usable directory` and offers to replace it
so receipts can land; it does not also warn empty ticks for that path.
Copies from Archive live in each shift's folder under the archive root,
`$NS/archive/<YYYY-MM-DD>/receipts/` by default, and do not replace the live files Doctor counts.
Missing or empty receipts create no dated receipts folder.

**Every Warning is a real finding — relay it, do not soften it.** A path that is not a usable file
is a planted symlink where a marker should be, not an empty night; a malformed work mode is not a
working site; a failed clock-out is not a finished shift. Say what each one means for the owner
and, when the report offers a `[confirm]` action for it, name that action.

Doctor never writes the policy file, never runs the project's own tooling, and never prints
credentials, raw evidence, rule values, or the output of a command it did not run.

## 2. Classify actions — do not execute them

The report tags every suggestion:

- `[safe]` — mechanical leftover with no live session (for example a stale watchman pid file whose
  process is already gone). Still do **not** apply it because Doctor was invoked; offer it.
- `[confirm]` — owner decision (broken link, missing setup, leftover STOP while they still want
  the night). During an **unattended active shift** (`$NS/run/.shift-armed` and open boxes), report that
  the recommendation should be parked with the default "leave in place until morning", but do not
  write the parking lot or ask — the Doctor invocation remains byte-identical.
- `[blocked]` — Nightshift cannot fix this here (non-resumable Codex id, malformed process lease,
  missing host binary, unverified wedge). Say so. Never guess a session id or print/edit a lease
  capability. For a stuck conversation or a fenced recorded session, name
  `"$NIGHTSHIFT_PLUGIN_ROOT/runtime/ns" stop-shift` — that pauses immediately without waiting for a Stop
  event. Do not run it from Doctor.

When the report says a terminal clock-out failed without releasing the shift, say whether the
recorded conversation can operate or whether a recovery worker still holds the lease; never tell
the owner to reopen a conversation that would stay blocked.

Invoking Doctor alone must leave the tree byte-identical. Never perform a repair merely because
Doctor was invoked.

When cross-host continuity is relevant, summarize stand-down and revival from `$NS/run/shift-log.md`
(no secrets), and run `continuity-handoff.sh fence-check` only when a duplicate worker or unfenced
prior owner is suspected.

## 3. After the report

Offer the classified repairs after the report. If the owner explicitly asks to apply a `[safe]`
leftover while no shift is armed, they are no longer in Doctor — follow stop/start/setup as those
skills specify. Until that explicit ask, change nothing. During an unattended shift, the offer is
informational only: continue the active work without asking or writing state.

Two repairs the report names are separate owner actions, never Doctor's own:

- The move into the current layout. On a workspace at an older state-version, or one holding a
  state file at an earlier path, the `[confirm]` action names each file with its old and new path
  and says that nothing is deleted; it is `[blocked]` while a shift is armed, a watchman is alive
  or a lock is held. Relay it as printed. The owner previews it with
  `"$NIGHTSHIFT_PLUGIN_ROOT/runtime/ns" migrate-state` and makes it by running that again with
  `--apply`. A future version is `[blocked]`: never downgrade a marker.
- A local rule profile. Doctor may list the shipped examples with
  `"$NIGHTSHIFT_PLUGIN_ROOT/runtime/ns" apply-profile --list`
  and preview one with `--profile <name> --mode fill` (or `--mode replace`). Preview is the
  default; only `--apply` writes, and Invoking
  Doctor never writes `rules.json`.

A senior may run the read-only project inventory after the report:
`"$NIGHTSHIFT_PLUGIN_ROOT/runtime/ns" inventory`. It prints one table per
workspace package — package manager and lockfile, the scripts declared for test, lint, typecheck,
build and format, the config files present, and each named tool as `declared`, `runnable` or
`absent`. Those three words are the whole verdict; the report never calls a project misconfigured.
It writes and caches nothing, and Doctor never runs it — offer it, the way every other action here
is offered.

If the owner then explicitly asks to **Export support bundle**, they are no longer in Doctor.
Run
`"$NIGHTSHIFT_PLUGIN_ROOT/runtime/ns" export-support`.
Print its path, included sections, and omitted categories. Do not upload, attach, transmit, or open
the file. Invoking Doctor alone must not create `$NS/support/`.

© orwa-mahmoud · MIT · orwa-mahmoud/nightshift

Similar skills

SKILL.md skills catalog →

doctor by other authors comes first.

doctor OrchestKit doctor diagnoses OrchestKit manifests, hooks, subagents, and MCP servers across project files. Pinpoints broken configurations and suggests fixes before deployment. CX Codex +1 227installs doctor Rich627 doctor is a Claude Code skill that checks why a WhatsApp channel is failing and explains how to address the findings. It can compare script results with the server status. CX Codex +1 ★ 127repo stars react-doctor millionco react-doctor audits React codebases for architecture, accessibility, and rendering issues. Computes a health score from 0 to 100 and helps patch regressions. CX Codex +1 22,800installs turbo-doctor goldsky-io The turbo-doctor skill for Claude Code diagnoses broken Goldsky Turbo pipelines by checking statuses and logs, then guides fixes through the CLI. CX Codex +1 5,100installs subgraph-doctor goldsky-io subgraph-doctor — a skill that tracks down why a Goldsky Subgraph stopped indexing, stalled or failed to deploy, then points at the fix. CX Codex +1 5,000installs dotnet-maui-doctor dotnet dotnet-maui-doctor is a Claude Code skill that diagnoses and fixes .NET MAUI environment setup on macOS, Windows, and Linux. It addresses Android, iOS, and Windows build errors caused by SDK or Java conflicts. CX Codex +1 4,500installs pod-doctor runpod pod-doctor diagnoses unreachable, stuck, or GPU-blind Runpod Pods using MCP tools. Inspects logs in read-only mode and suggests safe recoveries without data loss. CX Codex +1 3,700installs ctx-doctor mksglu ctx-doctor — a skill for Claude Code that verifies your context-mode setup. It runs an environment check and prints the resulting status table directly. CX Codex +1 1,800installs

From the same set17

The whole set →
plan This Claude Code skill opens a planning room to explore a project and shape the work with its owner. Implementation waits until the owner deliberately leaves the room. CX Codex +1 ★ 571repo stars plan-exit The plan-exit Claude Code skill checks whether plan mode is closed and names the next step toward implementation. It reads the room status and staged items. CX Codex +1 ★ 571repo stars nightshift The nightshift Claude Code skill works through a project punch list during an autonomous shift. Start it with a request to work on the project, with or without a time budget. CX Codex +1 ★ 571repo stars import-issues The import-issues Claude Code skill stages selected GitHub issues as project drafts. It previews each issue before asking which ones to add. CX Codex +1 ★ 571repo stars hunt The hunt Claude Code skill builds a Nightshift work shift from a project request. Give it a task and a number of hours, and it starts without asking for catalog choices. CX Codex +1 ★ 571repo stars customize The customize Claude Code skill displays Nightshift settings, templates, and catalog entries on one screen. It changes only the values the project owner names. CX Codex +1 ★ 571repo stars archive Files completed Nightshift records into structured archive folders. Active project directories keep only open tasks and unresolved records. CX Codex +1 ★ 571repo stars install-nightshift The install-nightshift Claude Code skill installs the Nightshift plugin with its hooks and runtime. It checks Claude Code, Codex, and Cursor before guiding the setup. CX Codex +1 ★ 571repo stars

Project sponsors

Companies that keep this analytics open