Skip to main content

Troubleshooting

Scope​

This page is the canonical v1.6 troubleshooting surface for jhf-dobby.

It stays command-first and bounded. It does not replace the deeper operational and deployment docs.

Reader Outcome​

This page should help an operator quickly separate:

  • Dobby-owned docs or contract drift
  • Dobby runtime/materialization drift
  • foreign-owner approval or governance failures that Dobby should only consume and classify

Common Failure Classes​

Fabric Alignment Drift​

Symptoms:

  • readiness degrades to warmup
  • contract alignment routes show mismatch

Run:

python scripts/validate_fabric_consumer_contract.py
python scripts/verify_fabric_live.py

Verify after recovery:

python scripts/verify_fabric_live.py

Runtime Materialization Drift​

Symptoms:

  • compose truth and running containers diverge
  • runtime labels or service ownership drift from repo truth

Run:

python scripts/verify_runtime_materialization.py

Verify after recovery:

python scripts/verify_runtime_materialization.py

Replay / Approval Flow Fails Closed​

Symptoms:

  • replay proposals stop at approval or policy checks
  • Warp or persistence unavailability keeps activation blocked

Run:

python scripts/verify_replay_harness.py
python scripts/validate_state_machine.py

Verify after recovery:

python scripts/verify_replay_harness.py

Run This Check​

python scripts/validate_docs_platform_v1_6.py
python scripts/verify_runtime_guardrails.py
python scripts/verify_runtime_materialization.py

For public source-truth and contract posture:

python scripts/validate_contract_conformance.py
python scripts/validate_fabric_consumer_contract.py

Supporting Deep-Dive Docs​

First Handoff Rule​

If the Dobby-owned docs, contract, and runtime-materialization checks are green but the remaining failure is upstream Fabric, Warp, Shuttle, or Bobbin truth, classify it as external-owner follow-up instead of recreating that truth locally in Dobby.

License: AGPLv3. See ../LICENSE (LICENSE). Learn more at helpifyr.com.