Skip to main content

Troubleshooting

Documentation Map​

Troubleshooting

Purpose​

This page is the executable troubleshooting surface for jhf-fabric.

Each failure mode should lead to:

  • diagnosis
  • a bounded run command
  • a verify-after-fix command

Run This Check​

Primary docs/runtime drift check:

python scripts/docs/check_runtime_drift.py

Execution-link verification:

python scripts/docs/validate_execution_links.py

Docs rollback readiness:

python scripts/docs/prepare_docs_rollback_bundle.py --check

Common Failure Modes​

Docs skeleton incomplete​

Symptoms:

  • repo docs readiness is partial
  • execution-link status is gapped

Run:

python scripts/docs/validate_repo_docs_skeleton.py --repo C:\CodexTest\helpifyr-fabric

Verify:

python scripts/docs/compute_docs_hash.py

Capability mapping gap​

Symptoms:

  • capability coverage reports missing mappings

Run:

python scripts/docs/check_capability_docs_mapping.py

Verify:

python scripts/docs/check_docs_coverage.py

Runtime/source drift​

Symptoms:

  • generated refs or event-model docs no longer match source truth

Run:

python scripts/docs/check_runtime_drift.py

Verify:

python scripts/docs/compute_global_docs_state.py

Rollback bundle partial​

Symptoms:

  • docs rollback posture is not ready

Run:

python scripts/docs/prepare_docs_rollback_bundle.py

Verify:

python scripts/docs/prepare_docs_rollback_bundle.py --check

Host/Runtime Diagnosis​

When the question is about host or container state, verify the real state first on <internal-runtime-redacted> via the guarded runtime paths documented in Operations. Do not assume permission or container failure without host evidence.

License​