session-orchestrator 3.16.0

package/skills/daily/SKILL.md

@@ -0,0 +1,222 @@
+---
+name: daily
+user-invocable: true
+tags: [vault, daily, obsidian, pkm]
+model: haiku
+model-preference: sonnet
+model-preference-codex: gpt-5.4-mini
+model-preference-cursor: claude-sonnet-4-6
+description: >
+  Use this skill when creating today's daily note in the Meta-Vault (03-daily/YYYY-MM-DD.md) with valid
+  vaultFrontmatterSchema-compliant YAML frontmatter. Idempotent: re-running on the
+  same day opens the existing note instead of overwriting. Use when starting a work
+  day, capturing scratch notes, or bootstrapping the inbox flow.
+---
+
+# Daily Skill
+
+## Status
+
+IMPLEMENTED 2026-04-13.
+
+## Purpose
+
+Bootstraps today's daily note in the Meta-Vault so the user can start capturing
+thoughts, scratch work, and "done today" items without yak-shaving YAML
+frontmatter each morning. The daily note is the anchor of the PKM workflow: it
+is where the inbox flow starts, where daily momentum is tracked, and where
+evening reflections land. Every daily note carries the same frontmatter shape
+(validated by `vaultFrontmatterSchema`), which makes Dataview queries and the
+vault-sync validator trivial.
+
+## Prerequisites
+
+- Must be invoked from inside a Meta-Vault root (cwd contains `03-daily/`) OR
+  with `VAULT_DIR` resolved to the vault path (see Resolution Order below).
+- `03-daily/` must already exist — the skill fails fast if it does not.
+- `bash` + `sed` + `date` (always available on macOS/Linux).
+
+### VAULT_DIR Resolution Order
+
+1. `vault-integration.vault-dir` in Session Config (highest precedence)
+2. `VAULT_DIR` environment variable
+3. `$PWD` (fallback when neither is set)
+
+Claude must read Session Config and export `VAULT_DIR` before calling
+`generate.sh`. The canonical pattern (mirrors `session-end` and `evolve`):
+
+```bash
+CONFIG=$(cat .orchestrator/session-config.yaml | yq -o json)
+VM_DIR=$(echo "$CONFIG" | jq -r '."vault-integration"."vault-dir" // empty')
+: "${VM_DIR:=$VAULT_DIR}"
+VAULT_DIR="$VM_DIR" bash /path/to/skills/daily/generate.sh
+```
+
+`generate.sh` itself reads only `VAULT_DIR` (pure bash, no Config parser).
+
+## Algorithm
+
+1. **Resolve `VAULT_DIR`.** Check `vault-integration.vault-dir` in Session
+   Config first; fall back to the `VAULT_DIR` env var; then `$PWD`. The
+   config field takes precedence — see Prerequisites for the canonical
+   resolution snippet. `generate.sh` then validates: template exists (exit 2
+   if not), vault dir exists (exit 3 if not), `03-daily/` exists (exit 4 if
+   not).
+2. **Compute today's date.** `date +%Y-%m-%d` — ISO 8601 date-only, respecting
+   the system timezone (the user is in Vienna, so `Europe/Vienna` via system TZ).
+3. **Target path.** `$VAULT_DIR/03-daily/YYYY-MM-DD.md`.
+4. **Idempotency check.** If the target already exists, print
+   `Daily note already exists: <path>` and exit 0. Never overwrite.
+5. **Render template.** Read `templates/daily.md.tpl` (next to this SKILL.md)
+   and substitute `{{date}}`, `{{id}}`, `{{created}}`, `{{updated}}`,
+   `{{title}}`, `{{weekday}}` via `sed`. The template is literal markdown; the
+   only shell interpolation happens in the `sed` substitutions.
+6. **Write to target path.** Uses `sed … > "$TARGET.tmp" && mv "$TARGET.tmp"
+   "$TARGET"` to avoid leaving a half-written file on disk if sed fails.
+7. **Validate** (recommended but not automatic in `generate.sh`). Callers
+   should run the vault-sync validator over the vault in hard mode to confirm
+   schema compliance:
+   ```bash
+   VAULT_DIR="$VAULT_DIR" bash ../vault-sync/validator.sh --mode hard
+   ```
+   The BATS test suite runs this check on every run — see
+   `tests/daily.bats`. If validation ever fails, the template has drifted from
+   the canonical Zod schema; fix the template, do not downgrade the gate.
+8. **Print success.** `Created daily note: <path>` on stdout, exit 0.
+
+## Implementation
+
+The deterministic path is implemented in `generate.sh` (pure bash). An
+LLM-driven fallback is unnecessary: daily-note creation is a 100%
+mechanical transform and a shell script is faster, cheaper, and more
+reliable than an LLM round-trip. Recommended invocation:
+
+```bash
+# Resolve vault dir from Session Config first, env var as fallback:
+CONFIG=$(cat .orchestrator/session-config.yaml | yq -o json)
+VM_DIR=$(echo "$CONFIG" | jq -r '."vault-integration"."vault-dir" // empty')
+: "${VM_DIR:=$VAULT_DIR}"
+VAULT_DIR="$VM_DIR" bash ~/Projects/session-orchestrator/skills/daily/generate.sh
+```
+
+Or, if `VAULT_DIR` is already set in the environment and Session Config has
+no `vault-integration.vault-dir` override:
+
+```bash
+VAULT_DIR=~/Projects/vault bash ~/Projects/session-orchestrator/skills/daily/generate.sh
+```
+
+Or, if the user's cwd is already the vault:
+
+```bash
+cd ~/Projects/vault && bash ~/Projects/session-orchestrator/skills/daily/generate.sh
+```
+
+## Template Placeholders
+
+| Placeholder   | Example            | Format                                                     |
+| ------------- | ------------------ | ---------------------------------------------------------- |
+| `{{date}}`    | `2026-04-13`       | ISO 8601 date (`YYYY-MM-DD`), also used inside the `id`    |
+| `{{created}}` | `2026-04-13`       | ISO 8601 date (`YYYY-MM-DD`) — matches `isoDateRegex`      |
+| `{{updated}}` | `2026-04-13`       | ISO 8601 date (`YYYY-MM-DD`) — matches `isoDateRegex`      |
+| `{{title}}`   | `Daily 2026-04-13` | Human-readable heading, `Daily YYYY-MM-DD`                 |
+| `{{weekday}}` | `Montag`           | Full German weekday name (lookup table keyed on `date +%u`) |
+
+Note: `{{id}}` is **not** a separate placeholder — the template inlines
+`id: daily-{{date}}` so there is only one date substitution. This keeps
+template rendering to a single `sed` pass and prevents drift between `id`
+and filename.
+
+The German weekday is computed via a hardcoded lookup (1=Montag,
+2=Dienstag, ..., 7=Sonntag) rather than `LC_TIME=de_DE.UTF-8 date +%A`
+because not every macOS install has the `de_DE.UTF-8` locale compiled.
+
+## Integration with vault-sync
+
+The template **must** stay in sync with `vaultFrontmatterSchema`. The canonical
+schema lives at:
+
+```
+~/Projects/projects-baseline/packages/zod-schemas/src/vault-frontmatter.ts
+```
+
+Required fields produced by the template: `id`, `type`, `created`, `updated`.
+Optional-but-useful fields: `title`, `tags`, `status`. The `type` is hardcoded
+to `daily` (one of the valid values in `vaultNoteTypeSchema`). The `id` is
+`daily-YYYY-MM-DD` which is kebab-case and 16 chars — passes
+`slugRegex.min(2).max(128)`.
+
+The BATS suite runs the vault-sync validator end-to-end (`bats tests/daily.bats`
+→ test 8), so any drift between the template and the schema breaks the build
+of this skill, not of the vault that consumes it.
+
+## Idempotency Guarantee
+
+Running `generate.sh` twice on the same day is a no-op when the existing
+file is valid:
+
+1. The first run creates `$VAULT_DIR/03-daily/YYYY-MM-DD.md`.
+2. The second run finds the file, confirms it is non-empty and starts with
+   `---\n` (valid YAML frontmatter opener), prints
+   `Daily note already exists: <path>`, and exits 0.
+
+If the existing file is 0 bytes or lacks the `---\n` opener (e.g. a previous
+run crashed between the `$TARGET.tmp` write and the `mv`), the corrupt file
+is removed and the note is re-created cleanly.
+
+The file is **never** re-rendered when intact. This matters because the user
+edits the daily note throughout the day (ticking checkboxes, filling in the
+Scratch section, etc.) and re-invoking `/daily` from anywhere — a later
+session, a different tool, a keybind — must not destroy that work.
+
+Verified by `tests/daily.bats` test 5: hash-compares the file before and after
+a second `generate.sh` invocation.
+
+## Anti-Patterns
+
+- **DO NOT overwrite existing daily notes.** Re-running `/daily` is routine;
+  losing the day's scratch notes is catastrophic. The idempotency check is
+  load-bearing.
+- **DO NOT hardcode the vault path.** `VAULT_DIR` is the contract. Hardcoding
+  `~/Projects/vault` breaks tests, breaks any future multi-vault setup, and
+  couples this skill to one user's machine.
+- **DO NOT skip the post-write validation step.** If the BATS suite stops
+  running the vault-sync validator, template drift will quietly ship invalid
+  frontmatter into the vault and only be caught at the next session-end gate.
+- **DO NOT use `LC_TIME` for the weekday.** The locale is not guaranteed to
+  exist. Use the hardcoded lookup table.
+- **DO NOT add `sed`-unsafe characters to the template.** The placeholders use
+  `|` as the sed delimiter; if you add a `|` to any substituted value, sed
+  will break. Keep substitutions plain.
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success (created) or idempotent skip (already exists and valid) |
+| 1 | Unexpected runtime failure (`set -e` caught an unhandled error) |
+| 2 | Infra error: template file not found at `$SCRIPT_DIR/templates/daily.md.tpl` |
+| 3 | Config error: `VAULT_DIR` does not exist as a directory |
+| 4 | Vault structure error: `$VAULT_DIR/03-daily/` directory is missing |
+
+## Files
+
+- `SKILL.md` — this file.
+- `generate.sh` — the POSIX bash implementation of the algorithm above.
+- `templates/daily.md.tpl` — the daily-note template with `{{placeholder}}`
+  markers.
+- `tests/daily.bats` — 8 BATS test cases covering creation, substitution,
+  idempotency, missing-dir errors, and end-to-end schema validation via
+  vault-sync.
+
+## Testing
+
+From the skill directory:
+
+```bash
+bats tests/daily.bats
+```
+
+Expected: `8/8 passing`. Test 8 runs the vault-sync validator over a fixture
+vault that contains only the freshly-generated daily note, proving end-to-end
+schema compliance.

package/skills/daily/generate.sh

@@ -0,0 +1,92 @@
+#!/usr/bin/env bash
+# generate.sh — Create today's daily note in the Meta-Vault.
+#
+# Usage:
+#   bash generate.sh
+#   VAULT_DIR=/path/to/vault bash generate.sh
+#
+# Behavior:
+#   - Resolves VAULT_DIR from env, else $PWD. Must contain 03-daily/.
+#   - Computes today's date via `date +%Y-%m-%d` (Europe/Vienna via system TZ).
+#   - Target path: $VAULT_DIR/03-daily/YYYY-MM-DD.md
+#   - If target exists → idempotent no-op (exit 0).
+#   - Otherwise substitutes placeholders into templates/daily.md.tpl and writes.
+#
+# Exit codes:
+#   0 — created OR already-exists (idempotent)
+#   1 — unexpected runtime failure (set -e)
+#   2 — infra error: template file missing
+#   3 — config error: VAULT_DIR does not exist
+#   4 — vault structure error: 03-daily/ missing
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+TEMPLATE="${SCRIPT_DIR}/templates/daily.md.tpl"
+
+# ── Resolve VAULT_DIR ──────────────────────────────────────────────────────
+: "${VAULT_DIR:=$PWD}"
+
+if [[ ! -f "$TEMPLATE" ]]; then
+  echo "error: template not found: $TEMPLATE" >&2
+  exit 2
+fi
+
+if [[ ! -d "$VAULT_DIR" ]]; then
+  echo "error: VAULT_DIR does not exist: $VAULT_DIR" >&2
+  exit 3
+fi
+
+DAILY_DIR="$VAULT_DIR/03-daily"
+if [[ ! -d "$DAILY_DIR" ]]; then
+  echo "error: 03-daily/ not found in vault: $DAILY_DIR" >&2
+  echo "hint: run this skill from inside the Meta-Vault, or set VAULT_DIR." >&2
+  exit 4
+fi
+
+# ── Compute date / weekday ─────────────────────────────────────────────────
+DATE="$(date +%Y-%m-%d)"
+DOW="$(date +%u)"  # 1=Mon .. 7=Sun
+
+# Hardcoded German weekday lookup (locale-independent for reliability).
+case "$DOW" in
+  1) WEEKDAY="Montag" ;;
+  2) WEEKDAY="Dienstag" ;;
+  3) WEEKDAY="Mittwoch" ;;
+  4) WEEKDAY="Donnerstag" ;;
+  5) WEEKDAY="Freitag" ;;
+  6) WEEKDAY="Samstag" ;;
+  7) WEEKDAY="Sonntag" ;;
+  *) WEEKDAY="Unknown" ;;
+esac
+
+TARGET="$DAILY_DIR/${DATE}.md"
+
+# ── Idempotency check ──────────────────────────────────────────────────────
+if [[ -f "$TARGET" ]]; then
+  # corrupt file guard: 0-byte or missing YAML frontmatter opener → re-create
+  if [[ ! -s "$TARGET" ]] || [[ "$(head -c 3 "$TARGET")" != "---" ]]; then
+    rm -f "$TARGET"
+  else
+    echo "Daily note already exists: $TARGET"
+    exit 0
+  fi
+fi
+
+# ── Render template ────────────────────────────────────────────────────────
+TITLE="Daily ${DATE}"
+
+# sed substitution — placeholders are {{name}}, no shell interpolation in the
+# template, so this is safe with simple replacement.
+sed \
+  -e "s|{{date}}|${DATE}|g" \
+  -e "s|{{created}}|${DATE}|g" \
+  -e "s|{{updated}}|${DATE}|g" \
+  -e "s|{{title}}|${TITLE}|g" \
+  -e "s|{{weekday}}|${WEEKDAY}|g" \
+  "$TEMPLATE" > "$TARGET.tmp"
+
+mv "$TARGET.tmp" "$TARGET"
+
+echo "Created daily note: $TARGET"
+exit 0

package/skills/daily/templates/daily.md.tpl

@@ -0,0 +1,36 @@
+---
+id: daily-{{date}}
+type: daily
+title: {{title}}
+created: {{created}}
+updated: {{updated}}
+tags:
+  - daily
+status: draft
+---
+
+# {{title}} ({{weekday}})
+
+## Energie & Fokus
+
+- [ ]
+
+## Termine
+
+-
+
+## Done heute
+
+-
+
+## Scratch
+
+-
+
+## Offen für morgen
+
+-
+
+## Links
+
+- [[_MOC]]

package/skills/debug/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: debug
+description: Use when encountering any bug, test failure, build break, or unexpected behavior — runs a 4-phase systematic debugging process before proposing any fix. Iron Law: NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST. Produces a `.orchestrator/debug/` artifact the fixer agent must reference.
+model: inherit
+color: red
+tools: Read, Grep, Glob, Bash, Write
+---
+
+# Debug Skill
+
+> 4-phase root-cause investigation. Iron Law: no fix without root cause.
+
+## When to use
+
+- Any test failure (unit, integration, E2E)
+- Build break or compile error
+- Runtime exception in production code
+- Performance regression
+- Integration issue between modules
+- "It worked yesterday" bugs
+
+## When NOT to use
+
+- Feature implementation (use `/plan` or wave-executor)
+- Pure refactoring with no broken behavior
+- Style/lint fixes with no behavioral impact
+
+## Phase 0: Bootstrap Gate
+
+Read `skills/_shared/bootstrap-gate.md` and execute the gate check. If the gate is CLOSED, invoke `skills/bootstrap/SKILL.md` and wait for completion before proceeding. If the gate is OPEN, continue to Phase 1.
+
+<HARD-GATE>
+Do NOT proceed past Phase 0 if GATE_CLOSED. There is no bypass. Refer to `skills/_shared/bootstrap-gate.md` for the full HARD-GATE constraints.
+</HARD-GATE>
+
+## The Iron Law
+
+> **NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.**
+
+No matter how obvious the fix looks, complete Phase 1 (Root Cause Investigation) and produce the artifact BEFORE writing any fix code. This is non-negotiable.
+
+The "2-hour obviously a typo" case has been the root cause of every multi-day debugging session in every project's history. Treat the obvious fix as a hypothesis to verify, not a conclusion to act on.
+
+## Phase 1: Root Cause Investigation
+
+### 1.1 Read the error carefully
+
+Quote the exact error message, full stack trace, and exit code in the artifact. Do not paraphrase. Paraphrasing introduces your assumptions before investigation begins.
+
+### 1.2 Reproduce reliably
+
+Document the exact command and environment that triggers it. If reproduction is flaky, that itself is a data point — write down the failure rate.
+
+```bash
+# minimum reproduction attempt
+<exact command>
+# env: Node version, OS, env vars relevant to the failure
+```
+
+### 1.3 Check recent changes
+
+```bash
+git log --oneline -20
+git diff HEAD~5..HEAD -- <affected paths>
+```
+
+Identify the smallest set of commits that could have introduced this. Do not assume the most recent commit is the culprit without checking.
+
+### 1.4 Instrument every component boundary
+
+Add temporary logging at each input/output point along the failing path's modules. Capture actual values, not assumptions about what they should be. Run with instrumentation in place and record results.
+
+### 1.5 Trace data flow backward
+
+Start from the failure point and walk upstream. At each step, verify what you think is true with an actual Read or Bash call. "I assume X is Y" is not data.
+
+### Phase 1 artifact
+
+Write to `.orchestrator/debug/<session-id>-<sequence>.md` (sequence = 1, 2, 3 within session).
+
+**Artifact MUST be written before proceeding to Phase 2.** See "Artifact contract" section below.
+
+## Phase 2: Pattern Identification
+
+After the Phase 1 artifact is written:
+
+- Is this a recurrence of a previously fixed bug? Search `git log --all --grep="<symptom keyword>"`.
+- Is there a class of bug this exemplifies (race condition, off-by-one, null check, encoding, async ordering)?
+- Is there a missing test that would have caught this? Identify what the test would look like.
+- Search the codebase for similar patterns:
+  ```bash
+  grep -rn "<suspect pattern>" --include="*.ts" --include="*.mjs"
+  git grep "<symbol>"
+  ```
+
+Record findings in the artifact's Phase 2 section.
+
+**Optional operator-side companion:** `/tmux-layout --layout debug` renders a 4-pane layout (scratch shell + `npm test --watch` + `tail -F .orchestrator/debug/*.md` + `watch -n 2 'git diff --stat'`) so you can observe hypothesis tests, debug artifacts, and diff progression peripherally. Pure observability — the `/debug` skill works identically with or without the layout (per ADR-0007 + GitLab #562).
+
+## Phase 3: Impact Analysis
+
+- What else does the root-caused code touch?
+  ```bash
+  grep -rn "<function or symbol name>"
+  ```
+- What other code paths could share the same root cause?
+- Will the fix break anything else? Identify callers, dependents, transitive effects.
+- List the affected files explicitly in the artifact.
+
+## Phase 4: Solution
+
+Only after Phases 1-3 are complete and the artifact is written:
+
+1. Propose the minimal fix — the smallest code change that addresses the confirmed root cause
+2. Identify test cases that would have caught this; write them alongside or before the fix if appropriate
+3. Document the fix decision in the artifact under a "Resolution" section
+4. Verify the fix: run the test command from Session Config (`test-command`) and confirm the failure no longer reproduces
+
+Do not gold-plate the fix. Scope creep during a bugfix introduces new bugs.
+
+## Artifact contract
+
+`.orchestrator/debug/<session-id>-<sequence>.md`:
+
+```markdown
+# Debug session: <topic>
+Created: <ISO timestamp>
+Session: <session-id>
+
+## Phase 1 — Root Cause
+
+### Error
+[exact error message + stack trace + exit code — verbatim]
+
+### Reproduction
+[exact command]
+[environment: Node version, platform, relevant env vars]
+[frequency: always | intermittent (~N/10)]
+
+### Suspect commits
+- <sha> <subject> — reason
+
+### Instrumentation data
+[per-boundary observations with actual values]
+
+### Hypothesized root cause
+[ONE sentence] · Confidence: [low|medium|high]
+
+## Phase 2 — Pattern
+
+[recurrence? class? missing test? similar code paths?]
+
+## Phase 3 — Impact
+
+[affected files, callers, dependents]
+
+## Phase 4 — Solution
+
+[proposed fix + test cases identified]
+
+## Resolution
+
+[commit SHA, files changed, tests added — filled in after fix lands]
+```
+
+**Rules for the artifact:**
+- "Hypothesized root cause" is always ONE sentence. Multiple hypotheses signal you have none — pick the most evidence-backed one and lower confidence if uncertain.
+- Do not write fix code in Phase 1-3 sections. Those sections are investigation only.
+- The artifact is the deliverable — not an optional note.
+
+## Integration with wave-executor
+
+When `wave-executor` classifies a task as `bugfix`, it routes through this skill. `code-implementer` agents handling bugfix-classified tasks must reference an existing Phase-1 artifact path in their task description before editing any production code. Wire-up happens in wave-executor's routing layer (Wave 3 P1 cross-reference).
+
+## Anti-Patterns
+
+- **Skipping Phase 1 because "it's obviously a typo"** — see Iron Law. The obvious hypothesis goes in Phase 1 as a hypothesis to verify, not a fix to apply.
+- **Multiple hypotheses in "Hypothesized root cause"** — pick ONE. Lower confidence rating if uncertain. "Either X or Y" means you don't know yet.
+- **Writing fix code in Phase 1** — fixes belong in Phase 4. Investigation and implementation are separate acts.
+- **Skipping the artifact write** — the artifact IS the work product. No artifact = no investigation.
+- **Fixing the symptom** — the error location is the symptom; the root cause may be several frames upstream. Trace backward.
+- **Assuming the most recent commit is the cause** — check `git log -20` and the diff before assuming recency.
+
+## See Also
+
+- `skills/discovery/SKILL.md` — discovery surfaces problems; debug investigates them
+- `.claude/rules/verification-before-completion.md` — once fixed, verify fresh (issue #38)
+- `agents/code-implementer.md` — references this skill for bugfix-classified tasks

package/skills/debug/soul.md

@@ -0,0 +1,35 @@
+# Debug Skill — Soul
+
+## Identity
+
+You are the Investigator — a methodical root-cause analyst who treats every "obvious fix" as a hypothesis to verify. You don't patch symptoms; you find causes. Patches without causes are the source of the next incident.
+
+## Communication Principles
+
+- Quote errors verbatim, never paraphrase — paraphrasing bakes in your assumptions before investigation begins
+- State confidence levels explicitly: low / medium / high — calibration matters more than appearing decisive
+- One hypothesis at a time — multiple hypotheses in a single statement signal you have none
+- The artifact is the work product — the fix follows from it, not the other way around
+- Short, precise observations — long paragraphs in instrumentation sections hide the signal in noise
+
+## Decision-Making Philosophy
+
+1. **Iron Law first** — no fix without root cause investigation. Always.
+2. **Read three times what you would act on once** — the stack trace tells you where it broke; reading backward tells you why.
+3. **Instrument the boundary before guessing at the middle** — actual logged values beat theoretical reasoning at every step.
+4. **Confidence calibration matters more than speed** — "high confidence, wrong hypothesis" is the most expensive debugging failure mode.
+5. **One hypothesis** — if you have two, lower confidence and pick the more evidence-backed one. Write the other in Phase 2 as a pattern note.
+
+## Values
+
+- **Discipline** — Phase 1 always completes before Phase 4 starts. No exceptions.
+- **Skepticism** — your first hypothesis is probably wrong. Build the case before committing to it.
+- **Documentation** — the artifact prevents the next recurrence by making the investigation reproducible.
+- **Minimal fixes** — the narrowest change that addresses the confirmed root cause. Scope creep during bugfixes introduces new bugs.
+
+## What you are NOT
+
+- Not a fixer — that is the code-implementer agent's job. Your deliverable is the artifact.
+- Not a guesser — "I think it might be" without instrumentation data is not allowed.
+- Not in a hurry — the 2-hour investigation prevents the 2-day rabbit hole.
+- Not a symptom-patcher — the error location is the symptom; the cause may be upstream.