/doctor

description: "Something off with great_cto, or just upgraded it? Run it — you get a health report (pipeline state, missing artefacts, hooks, last run per agent, permission denials, an outdated PROJECT.md schema); `--fix` applies the safe fixes, including the schema upgrade."
argument-hint: "[--fix] [--skills | --skills-refresh] — --fix applies safe fixes incl. the PROJECT.md schema upgrade"
user-invocable: true
allowed-tools: Read, Bash, Edit, Glob, Grep
model: haiku

You are the Doctor. Produce a concise, actionable health report for the great_cto pipeline in this project. Without `--fix`: diagnose and point only — reports go to stdout, no files written. With `--fix`: apply the safe, non-destructive fixes in Check 9, including the PROJECT.md schema upgrade (append-only — what `/migrate` used to do).

Setup

source .great_cto/env.sh 2>/dev/null || export PATH="/opt/homebrew/bin:$HOME/.local/bin:/usr/local/bin:$PATH"
FIX_MODE=false
SKILLS_DETAIL=false
SKILLS_REFRESH=false
for arg in "$@"; do
  case "$arg" in
    --fix) FIX_MODE=true ;;
    --skills) SKILLS_DETAIL=true ;;
    --skills-refresh) SKILLS_REFRESH=true; SKILLS_DETAIL=true ;;
  esac
done
TODAY=$(date +%Y-%m-%d)
NOW_EPOCH=$(date +%s)

Check 1 — Required files

REQ_FILES=(.great_cto/PROJECT.md)
MISS=0
for f in "${REQ_FILES[@]}"; do
  if [ ! -f "$f" ]; then
    echo "MISSING: $f — run /start (new) or /audit (existing repo)"
    MISS=$((MISS+1))
  fi
done

Exit early with summary if PROJECT.md missing — no point checking the rest.

Check 2 — PROJECT.md format (v1.0.76+ contract)

# Use bash -c to avoid zsh nomatch + grep-c "0 || echo 0" doubling quirks.
if [ -f .great_cto/PROJECT.md ]; then
  HAS_STACK=$(grep -c "^Stack:" .great_cto/PROJECT.md 2>/dev/null); HAS_STACK=${HAS_STACK:-0}
  HAS_TYPE=$(grep -c "^Type:" .great_cto/PROJECT.md 2>/dev/null); HAS_TYPE=${HAS_TYPE:-0}
  HAS_ARCHETYPE=$(grep -c "archetype:" .great_cto/PROJECT.md 2>/dev/null); HAS_ARCHETYPE=${HAS_ARCHETYPE:-0}
  echo "PROJECT.md format:"
  [ "${HAS_STACK}" -gt 0 ] && echo "  ✓ Stack: line present" || echo "  ⚠ Stack: line missing — old format, run /audit to migrate"
  [ "${HAS_TYPE}" -gt 0 ] && echo "  ✓ Type: line present" || echo "  ⚠ Type: line missing — old format, run /audit to migrate"
  [ "${HAS_ARCHETYPE}" -gt 0 ] && echo "  ✓ archetype: present" || echo "  ⚠ archetype: missing"
fi

Check 2b — PROJECT.md schema (fields added since v1.0.100)

An install older than the current schema is missing fields agents now read. Diagnosis lists exactly what `--fix` would append (this is the preview — nothing is written); Check 9 Fix 4b appends them. Existing values are never overwritten.

if [ -f .great_cto/PROJECT.md ]; then
  SCHEMA_MISSING=""
  for FIELD in archetype_confidence archetype_alternatives archetype_rationale security_tier project_size packs; do
    grep -q "^${FIELD}:" .great_cto/PROJECT.md 2>/dev/null || SCHEMA_MISSING="$SCHEMA_MISSING $FIELD"
  done
  echo "PROJECT.md schema:"
  if [ -z "$SCHEMA_MISSING" ]; then
    echo "  ✓ up to date — no fields missing"
  else
    echo "  ⚠ outdated schema — missing:${SCHEMA_MISSING}"
    echo "    → /doctor --fix appends them with safe defaults (existing values untouched)"
  fi
fi

Check 2c — Archetype confidence

if [ -f .great_cto/PROJECT.md ]; then
  CONFIDENCE=$(grep "^archetype_confidence:" .great_cto/PROJECT.md 2>/dev/null | awk '{print $2}')
  ALTERNATIVES=$(grep "^archetype_alternatives:" .great_cto/PROJECT.md 2>/dev/null | sed 's/.*\[//;s/\]//')
  echo "Archetype confidence:"
  case "${CONFIDENCE:-}" in
    high)
      echo "  ✓ archetype_confidence: high — detector is certain"
      ;;
    medium|low)
      echo "  ⚠ archetype_confidence: ${CONFIDENCE} — consider reviewing alternatives: ${ALTERNATIVES:-none}"
      echo "    Run /audit to re-detect, or set archetype: manually in .great_cto/PROJECT.md"
      ;;
    user-specified)
      echo "  ✓ archetype_confidence: user-specified — manually confirmed"
      ;;
    "")
      echo "  ⚠ archetype_confidence: missing — outdated schema (see Check 2b)"
      echo "    Quick fix: run /doctor --fix, then /audit to re-detect the archetype"
      ;;
    *)
      echo "  ⚠ archetype_confidence: unknown value '${CONFIDENCE}' — expected high | medium | low | user-specified"
      ;;
  esac
fi

Check 3 — Output artefacts per phase

echo ""
echo "Pipeline artefacts:"
# Use find instead of globs so zsh without nullglob doesn't error on no-match.
find_latest() { find "$1" -maxdepth 1 -name "$2" 2>/dev/null | sort -V | tail -1; }
LAST_AUDIT=$(find_latest docs/audit          'AUDIT-*.md')
LAST_ARCH=$(find_latest  docs/architecture   'ARCH-*.md')
LAST_QA=$(find_latest    docs/qa-reports     'QA-*.md')
LAST_CSO=$(find_latest   docs/security       'CSO-*.md')
LAST_ADR=$(find_latest   docs/decisions      'ADR-*.md')
LAST_DIGEST=$( [ -f .great_cto/digest-latest.md ] && echo .great_cto/digest-latest.md )

age_days() {
  local f="$1"
  [ -z "$f" ] || [ ! -f "$f" ] && { echo "-"; return; }
  local mtime
  mtime=$(stat -f %m "$f" 2>/dev/null || stat -c %Y "$f" 2>/dev/null || echo 0)
  echo $(( (NOW_EPOCH - mtime) / 86400 ))
}

report_artefact() {
  local label="$1"; local path="$2"; local max_age="$3"
  if [ -z "$path" ]; then
    echo "  ✗ $label: NEVER — run the relevant command"
    return
  fi
  local age; age=$(age_days "$path")
  if [ "$age" -gt "$max_age" ]; then
    echo "  ⚠ $label: $age days old (max $max_age) — $(basename "$path")"
  else
    echo "  ✓ $label: $age days old — $(basename "$path")"
  fi
}

report_artefact "audit"        "$LAST_AUDIT"  30
report_artefact "architecture" "$LAST_ARCH"   90
report_artefact "qa report"    "$LAST_QA"     14
report_artefact "security"     "$LAST_CSO"    30
report_artefact "ADR (latest)" "$LAST_ADR"    90
report_artefact "digest"       "$LAST_DIGEST"  7

Check 3b — ADR health (lifecycle + supersession)

echo ""
echo "ADR hea