potiuk opened a new pull request, #292:
URL: https://github.com/apache/airflow-steward/pull/292
## Summary
New diagnostic skill at
[`.claude/skills/setup-isolated-setup-doctor/SKILL.md`](.claude/skills/setup-isolated-setup-doctor/SKILL.md).
Complements the existing `setup-isolated-setup-verify`:
| Skill | Question | Mechanism |
|---|---|---|
| `setup-isolated-setup-verify` | Is the setup **installed** correctly? |
Static checks on settings.json shape, hook wiring, pinned tool versions.
Catches drift. |
| **`setup-isolated-setup-doctor` (new)** | Are common workflows
**functionally** blocked by the current sandbox? | Live probes of SSH agent,
port binding, docker/podman socket. Catches over-restrictive allowlists. |
Each fail maps to a direct anchor link into the
[sandbox-troubleshooting catalog](docs/setup/sandbox-troubleshooting.md)
that landed in #291.
### The three probes
| Probe | What it tests | Pass shape | Fail shape | Catalog entry |
|---|---|---|---|---|
| `ssh-agent` | `SSH_AUTH_SOCK` set + socket stat-able + `ssh-add -l` runs |
rc=0 (keys) or rc=1 (no keys configured) | rc=2 (agent unreachable) | [SSH
agent / Yubikey
unreachable](docs/setup/sandbox-troubleshooting.md#ssh-agent--yubikey-appears-unreachable-from-inside-the-sandbox)
|
| `localhost-bind` | Python `socket.bind('127.0.0.1', 0)` + start
`HTTPServer` + `urlopen` self over loopback | HTTP 200 from loopback GET | Bind
ok / loopback GET fails (common shape — egress proxy refuses 127.0.0.1) | [Test
cannot bind to a localhost
port](docs/setup/sandbox-troubleshooting.md#test-cannot-bind-to-a-localhost-port)
|
| `docker-runtime` / `podman-runtime` | `docker info` / `podman info` for
each runtime on PATH | exit 0 | "Cannot connect to the Docker daemon" /
"connect: permission denied" | [Docker / Podman command fails with a socket
error](docs/setup/sandbox-troubleshooting.md#docker--podman-command-fails-with-a-socket-error)
|
Status taxonomy:
- ✓ probe passed
- ✗ probe failed → catalog entry linked
- ⊘ not applicable (e.g. `docker` not on PATH) — not a sandbox bug
- ⚠ unexpected (rare; the rc didn't match any documented shape)
### Golden rules (the skill is read-only)
- Never edits any settings file.
- Never invokes `dangerouslyDisableSandbox`.
- Runs every probe even on early failure (the value is the full
picture).
- Surfaces concrete evidence per probe — command, rc, stderr
snippet. "Looks blocked" is not a useful report.
- Maps each ✗ to a catalog entry by direct anchor link.
### When the catalog grows, the doctor grows
The skill's *Extending the skill with a new probe* section
documents how to add a fourth (fifth, …) probe when a new
failure mode lands in the catalog. The doctor and the catalog
stay in lock-step.
### `docs/setup/README.md`
New entry in the *Skills* table; the verify row's purpose cell
is tightened to "(static checks on settings.json, hooks, pinned
versions)" so the doctor-vs-verify split is visible at a glance.
### Sequencing
This is **PR-2 of 3** addressing sandbox friction:
- **PR-1 (#291, merged)** — `docs/setup/sandbox-troubleshooting.md`
catalog + cross-links.
- **PR-2 (this PR)** — `setup-isolated-setup-doctor` skill.
- **PR-3** — PostToolUse hint hook that annotates sandbox-shaped
errors in real time. Will reference both PR-1 and PR-2.
## Test plan
- [x] `prek run --files .claude/skills/setup-isolated-setup-doctor/SKILL.md
docs/setup/README.md` —
markdownlint / doctoc / typos / skill-validate / placeholder
conventions all pass.
- [x] Skill registered live in the runtime as soon as the
SKILL.md landed (visible in `/list-steward-skills` output).
- [ ] Next session that hits one of the three sandbox failure
modes: run `/setup-isolated-setup-doctor`, confirm the
matching probe reports ✗ with the right catalog link, and the
user can apply the linked remediation without further
guidance.
- [ ] Probe robustness on Linux (the probes are written
primarily against macOS Seatbelt; bubblewrap may produce
slightly different stderr signatures). Refine the rc/stderr
pattern matching in the *Interpretation* tables as real data
comes in.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
