swain-doctor

What this skill does

<!-- swain-model-hint: sonnet, effort: low -->

# Doctor

Session-start health checks for swain projects. The consolidated script is authoritative for all detection. This skill file defines how to run the script and how to remediate each check.

## Running the script

```bash
REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
bash "$REPO_ROOT/.agents/bin/swain-doctor.sh"
```

The script outputs structured JSON with `{ checks: [...], summary: {...} }`. Each check has `name`, `status`, `message`, and optional `detail`. Parse it and present the summary table to the operator. Then use the remediation sections below **only for checks that reported `warning` or `advisory` status** — do not re-run detection.

To auto-fix flat-file artifacts: `bash "$REPO_ROOT/.agents/bin/swain-doctor.sh" --fix-flat-artifacts`

If the script is unavailable (e.g., `.agents/bin/` symlinks not yet bootstrapped), fall back to running checks from the script source at `skills/swain-doctor/scripts/swain-doctor.sh`. Run checks **sequentially** (one Bash call at a time), never in parallel — parallel tool calls cascade-cancel on first error.

## Preflight integration

A lightweight shell script (`$REPO_ROOT/.agents/bin/swain-preflight.sh`) performs quick checks before invoking the full doctor. If preflight exits 0, swain-doctor is skipped for the session. If it exits 1, swain-doctor runs normally.

When invoked directly by the user (not via auto-invoke), swain-doctor always runs regardless of preflight status.

## Governance content reference

The canonical governance rules live in `references/AGENTS.content.md`. Both swain-doctor and swain-init read from this single source of truth. If the upstream rules change in a future swain release, update that file and bump the skill version.

---

# Remediation by check name

Each section below corresponds to a check name emitted by the script. Only consult the relevant section when the check status is `warning` or `advisory`.

## governance

**Injection (missing):** Read [references/governance-injection.md](references/governance-injection.md) for Claude Code and Cursor injection procedures. Source: `references/AGENTS.content.md`.

**Replacement (stale):** The script auto-repairs stale governance blocks when both markers (`<!-- swain governance -->` and `<!-- end swain governance -->`) are present. If auto-repair fails (markers missing), read [references/governance-injection.md § Stale governance replacement](references/governance-injection.md) for manual replacement.

## legacy_skills

Clean up renamed and retired skill directories using fingerprint checks. Read [references/legacy-cleanup.md](references/legacy-cleanup.md) for the full procedure. Data source: `references/legacy-skills.json`.

## agents_directory

Create `.agents/` with `mkdir -p .agents`. This directory is used by swain-do for configuration and by swain-design scripts for logs.

## tickets

Validates `.tickets/` health — YAML frontmatter, stale locks. Read [references/tickets-validation.md](references/tickets-validation.md) for repair procedures.

## beads_migration

Auto-migrates `.beads/` → `.tickets/` if present. Read [references/beads-migration.md](references/beads-migration.md) for the migration procedure.

## tools

Required tools: `git`, `jq`. Optional: `tk`, `uv`, `gh`, `tmux`, `fswatch`. Never install automatically. Read [references/tool-availability.md](references/tool-availability.md) for degradation notes and install instructions.

## settings

If `swain.settings.json` is missing, create it with default content. If it contains invalid JSON, fix the syntax. User settings live at `${XDG_CONFIG_HOME:-$HOME/.config}/swain/settings.json`.

## script_permissions

The script auto-repairs missing execute permissions on `.sh` and `.py` files in the skill tree. No manual remediation needed — advisory status means it already fixed them.

## memory_directory

The script auto-creates the memory directory if missing. If creation fails, manually create:
```bash
mkdir -p "$HOME/.claude/projects/$(echo "$REPO_ROOT" | tr '/' '-')/memory"
```

## superpowers

When status is `warning` (missing or partial), ask the operator:

> Superpowers (`obra/superpowers`) is not installed [or: partially installed]. It provides TDD, brainstorming, plan writing, and verification skills that swain chains into.
>
> Install superpowers now? (yes/no)

If yes: `npx skills add obra/superpowers`. If no, note "Superpowers: skipped" and continue.

## epics_initiative

Non-blocking advisory. Report the count and suggest:

> N Epic(s) have `parent-vision` but no `parent-initiative`. Adding `parent-initiative` links is optional but recommended. To run the guided migration, ask: "run the initiative migration."

Read [references/initiative-migration.md](references/initiative-migration.md) for the full 6-step guided migration workflow.

## readme

Report: `README.md missing — swain alignment loop has no public intent anchor. Run swain-init to seed one.`

## artifact_indexes

The script auto-repairs stale indexes via `rebuild-index.sh`. If the rebuild script is unavailable or a rebuild fails, check that `.agents/bin/rebuild-index.sh` exists and is executable. Re-run `swain-doctor` after fixing the symlink.

## evidence_pools

If `docs/evidence-pools/` exists, run the trove migration:
```bash
bash "$REPO_ROOT/.agents/bin/migrate-to-troves.sh" --dry-run  # preview
bash "$REPO_ROOT/.agents/bin/migrate-to-troves.sh"            # migrate
```

## worktrees

Stale worktrees (branch already merged into HEAD) can be pruned: `git worktree remove <path>`. Orphaned worktrees (directory missing) can be pruned: `git worktree prune`. Stale lockfiles and unclaimed worktrees are reported in the detail field. Read [references/worktree-detection.md](references/worktree-detection.md) for classification rules.

## worktree_context

Validates the current session's worktree, not all linked worktrees (that's `worktrees`). All four sub-checks **auto-fix** deterministically — warnings mean auto-fix failed, advisory means auto-fix succeeded.

**Location outside .worktrees/** (auto-move): ADR-034 mandates `.worktrees/` as the canonical location. The script auto-moves the worktree via `git worktree move <path> <main_root>/.worktrees/<branch>`. Failure (warning) means the target path already exists or `git worktree move` failed — resolve manually.

**Missing lockfile** (auto-create): The script auto-creates a lockfile at `.agents/worktrees/<branch>.lock` using `swain-lockfile.sh claim`, or falls back to writing the lockfile directly. On collision (existing lockfile for same branch), a PID-suffixed lockfile is created. Advisory = auto-created; warning = creation failed.

**Branch name violates ADR-025** (auto-rename): The script auto-renames the branch and moves the worktree folder to match ADR-025 naming. It uses `swain-worktree-name.sh` when a purpose is available, or falls back to `session-<timestamp>`. The lockfile is also renamed. Advisory = renamed; warning = rename failed.

**Folder name != branch name** (auto-move): The script auto-moves the worktree folder so `basename` matches the branch name via `git worktree move`. Advisory = moved; warning = move failed (target already exists).

## lifecycle_dirs

Old phase directories from before ADR-003's three-track normalization. Read [references/lifecycle-migration.md](references/lifecycle-migration.md) for detection commands, remediation steps, and the migration script.

## tk_health

If vendored tk is not found or not executable, try: `/swain update` to reinstall skills. The expected path is `<skills-root>/swain-do/bin/tk`.

## operator_bin_symlinks

The script auto-repairs missing or stale `bin/` symlinks. Conflicts (real file exists at `bin/<name>`) require manual resolution — rename or remove the conflicting file, then re-run doctor.

## commit_signing

The script auto-enables commit signing when a signing key is detected at `~/.ssh/swain_signing`. If no key exists, run `/sw