Skip to main content

Validation and Readback Workflow

Use this page when you need the standard verification path for a Helpifyr integration, docs change, or control-plane publication update.

When to use this page​

  • You changed an integration-related source and need trustworthy evidence.
  • You need to compare repo truth, materialized truth, and live truth.
  • You want the bounded readback order before you ask for merge or rollout.

Prerequisites​

  • You know which repo owns the source change.
  • You can run the repo-owned build and verification commands for that lane.

Architecture / Flow​

flowchart TD
    A["Change source truth"] --> B["Run repo-local verifier"]
    B --> C["Materialize reviewed artifact"]
    C --> D["Read back generated truth"]
    D --> E["Check published or runtime surface"]
    E --> F["Accept, escalate, or fix"]

Step-by-step procedure​

1. Verify the owner repo first​

Do not start with the live site. Start where the source change lives and run the narrowest repo-owned verifier.

2. Materialize the reviewed docs or projection layer​

For public docs in jhf-docs, the standard sequence is:

python scripts/materialize_public_docs_site.py
python scripts/materialize_public_docs_site.py --check
npm run build --prefix docs-site

3. Read back the generated evidence​

Check materialized outputs and generated metadata such as:

  • docs-site/generated/validation_report.json
  • docs-site/static/generated/docs-platform.json
  • materialized target pages under docs-site/docs/**

4. Check the live or runtime surface last​

Use the live site or runtime endpoint only after the reviewed artifact is known-good. Typical reads include:

GET /api/v1/docs/platform
GET /api/v1/docs/catalog
GET /api/v1/docs/readiness

5. Compare exact-main truth when publication is involved​

If a site or artifact looks stale, compare:

  • owner repo mainline
  • reviewed artifact metadata
  • live surface metadata or content readback

Verification​

The workflow is applied correctly when:

  1. verification started in the owner repo
  2. generated evidence was checked before live claims were made
  3. live readback was compared against the reviewed artifact, not memory

Common failure modes​

Starting with the live page only​

Problem:

  • you can see the symptom but not which layer is wrong.

Better path:

  • verify source, materialized artifact, then live publication in order

Treating a successful build as full publication truth​

Problem:

  • the artifact is correct locally but stale in production.

Better path:

  • add the final live readback and metadata comparison

Source Truth​

Next paths​