Breyta Docs
Docs
Playbooks

Playbook: Debug And Verify

Load when a run fails, output is wrong, CLI and UI disagree, or proof needs to be
collected before closing work.

Default Loop

  1. Identify target and lifecycle: draft, live, installation, version, interface,
    input, and workspace.
  2. Inspect the failing run or command result. Keep workflow id, output URL,
    resource URIs, error code, and recovery action URLs in the session capsule.
    Prefer exact recovery links from error.actions[].url first, then
    meta.webUrl.
    • breyta runs events <workflow-id> --limit 100 returns a bounded timeline
      of run and step events for live debugging, including in-flight step updates
      when the execution store has them. Add --step <step-id> for one step, or
      --installation-id <id> when inspecting a run through an installed profile.
    • breyta runs inspect <workflow-id> --step <step-id> returns compact step
      input/output/error/cost without opening the whole run payload.
    • breyta runs step <workflow-id> <step-id> is the short alias for the same
      step I/O inspection and includes that step's event timeline when available.
      Add --full only when captured step output/error payloads are required.
  3. Check for target mismatch:
    • flows push updates draft only
    • flows release or flows promote updates live
    • UI install paths usually follow live/install targets
  4. Narrow to the touched primitive:
    • read the step config
    • run a focused docs search for that primitive
    • use breyta steps run or breyta steps record when the step can be tested
      outside the full flow
    • add --flow <slug> --source draft for draft-only templates/functions or
      --installation-id <id> for installed connection slots
    • start with inline --params '<json>' for small inputs; move to
      --params-file when the input gets long or reused
    • inspect compact data.resultPreview.value first; expand with
      --result-path, --preview-depth, --preview-items, --preview-runes,
      or --result-file before using --full
  5. Rerun the smallest flow entrypoint that can prove the fix:
    • manual: breyta flows run <slug> --interface-id <id> --input '<json>' --wait
    • HTTP: breyta flows interfaces call <slug> <interface-id> --input '<json>' --wait
    • live/install: add --target live or --installation-id <id>
    • when a run is waiting for approval, use breyta runs continue <workflow-id> --approve-latest-wait to approve the latest active approval wait, then inspect the run again
  6. Read back user-facing output and side effects:
    • breyta resources read <resource-uri> --limit 20
    • table query/read commands for table resources
    • external system records, emails, files, or callbacks when those are the proof
    • rendered notifications/emails: recipient, sender, subject, body, required
      wording, and absence of debug fields

Do not rely on terminal status alone after a run returns output or artifacts.
Inspect the actual user-facing artifact from the intended user's perspective.

Escalate Only If

  • two edit/run cycles do not isolate the cause
  • the same command result conflicts with docs/help
  • a UI surface fails while CLI proof succeeds
  • a public/install path cannot be verified from available tools

When platform behavior appears wrong, submit breyta feedback send with full
URLs, workflow ids, output/resource URLs, target, interface id, and steps tried.
Also submit feedback when the fix required excessive trial/error, docs/help were
misleading, or CLI/API behavior made the intended agent loop unclear.

Proof Contract

Final proof should name:

  • command run
  • workflow id
  • target/version/installation
  • interface id or HTTP interface id
  • output/resource URLs
  • side effect evidence
  • unverified surfaces, especially web UI not verified

References

As of May 19, 2026