{"ok":true,"data":{"generatedAt":"2026-05-26T02:39:59.291Z","source":"deterministic_trace_debugging_playbooks","playbooks":[{"slug":"incomplete-traces","title":"Incomplete Traces","summary":"Use when a trace has started work but required child spans or async jobs have not reached a terminal state.","symptoms":["Trace status is active, waiting, partial, or degraded.","Completion state includes pending_children or waiting_for_async_jobs.","Expected services are missing from the timeline."],"likelyCauses":["A downstream service did not propagate traceparent.","An async job has not heartbeated or completed.","A span was started without a matching completion or failure event."],"checks":["Open /api/v1/traces/{traceId}/completion.","Inspect /api/v1/traces/{traceId}/spans for unset or running spans.","Check /api/v1/jobs?traceId={traceId} for waiting jobs."],"commands":["platphormctl trace incomplete","platphormctl trace get <traceId>","platphormctl trace spans <traceId>","platphormctl harness run trace-propagation-check --dry-run"],"linkedTools":["Trace completion","AgentUI","Sandbox","BrowserOps","Claws"],"evidenceToCollect":["Trace ID","pending span IDs","job IDs","last heartbeat timestamp","source and target service headers"]},{"slug":"failed-spans","title":"Failed Spans","summary":"Use when one or more spans failed, timed out, or were cancelled and the workflow needs a deterministic handoff.","symptoms":["Trace status is failed, timed_out, or partial.","A span has status failed, timed_out, or cancelled.","Evidence references include error summaries."],"likelyCauses":["Tool handler returned a real error.","Target service rejected the request.","Input schema validation failed.","Timeout deadline expired before completion."],"checks":["Open /api/v1/aggregate/errors.","Open /api/v1/traces/{traceId}/timeline.","Inspect redacted span errorCode and errorMessageRedacted."],"commands":["platphormctl trace failed","platphormctl trace report <traceId>","platphormctl mcp validate trace"],"linkedTools":["MCP","Evals","Sandbox","Docs","Claws"],"evidenceToCollect":["failed span ID","error code","redacted error message","evidence refs","related MCP method or API route"]},{"slug":"late-spans","title":"Late Spans","summary":"Use when a span arrives after deadline or after a trace already moved to a terminal state.","symptoms":["Completion contains has_late_spans.","Span attribute isLate is true.","Timeline shows evidence arriving after completion."],"likelyCauses":["Async completion callback was delayed.","Queue worker recovered after timeout.","A downstream service retried after the root workflow moved on."],"checks":["Open /api/v1/aggregate/late-spans.","Compare span deadlineAt, heartbeatAt, startTime, and endTime.","Check whether the late span attached evidence safely."],"commands":["platphormctl trace spans <traceId>","platphormctl trace report <traceId>"],"linkedTools":["Sandbox","BrowserOps","WebhookLab","Monitor"],"evidenceToCollect":["late span ID","deadlineAt","heartbeatAt","evidence refs","queue or delivery attempt ID"]},{"slug":"orphan-spans","title":"Orphan Spans","summary":"Use when a span references a parent that Trace has not received.","symptoms":["Completion contains has_orphans.","Span has parentSpanId but the parent is absent.","Service map has a dangling edge."],"likelyCauses":["Parent span was never ingested.","Trace IDs were mixed across service boundaries.","A client generated a new traceparent instead of propagating the existing one."],"checks":["Open /api/v1/spans/orphans.","Compare traceparent and X-PlatPhorm-Trace-Id across source and target logs.","Search for the missing parent span ID."],"commands":["platphormctl trace spans <traceId>","platphormctl trace propagate --service agentui"],"linkedTools":["Trace","AgentUI","BrowserOps","MCP"],"evidenceToCollect":["orphan span ID","missing parentSpanId","source service","target service","trace headers"]},{"slug":"missing-evidence","title":"Missing Evidence","summary":"Use when a span claims work happened but has no public-safe artifact, result reference, or redacted summary.","symptoms":["Evidence count is zero for an important span.","Report generation has insufficient refs.","The timeline cannot prove a claimed outcome."],"likelyCauses":["The source service did not call link_evidence.","Evidence was private and correctly withheld from public view.","Adapter is degraded and cannot persist artifact references."],"checks":["Open /api/v1/traces/{traceId}/evidence.","Inspect span metadata for publicSafe and protected flags.","Check storage state in /api/health."],"commands":["platphormctl trace get <traceId>","platphormctl trace report <traceId>"],"linkedTools":["Docs","Sheets","BrowserOps","Evals","Sandbox"],"evidenceToCollect":["span ID","artifact URL or protected ref","publicSafe flag","redaction summary"]},{"slug":"missing-traceparent-propagation","title":"Missing Traceparent Propagation","summary":"Use when services appear as separate traces or child spans are missing because trace context was not forwarded.","symptoms":["Multiple trace IDs for one user workflow.","Target service spans are present but disconnected.","Propagation summary is degraded."],"likelyCauses":["Outbound client did not forward traceparent.","Proxy stripped trace headers.","Service used local trace IDs instead of W3C context."],"checks":["Validate traceparent with /api/mcp validate_trace_context.","Check X-PlatPhorm-Source-Site and X-PlatPhorm-Target-Site.","Open /api/v1/network/propagation."],"commands":["platphormctl trace propagate --service agentui","platphormctl harness run trace-propagation-check --dry-run"],"linkedTools":["Trace","BrowserOps","AgentUI","Monitor"],"evidenceToCollect":["request ID","traceparent","tracestate","source service","target service"]},{"slug":"broken-mcp-tool-call","title":"Broken MCP Tool Call","summary":"Use when an MCP initialize, tools/list, tools/call, resources/read, or prompts/get workflow fails.","symptoms":["MCP method span failed.","tools/call result is absent or redacted error only.","MCP client reports JSON-RPC error."],"likelyCauses":["Invalid JSON-RPC envelope.","Tool is protected and no PLATPHORM_API_KEY was supplied.","Tool handler returned a real degraded adapter state."],"checks":["POST /api/mcp initialize.","POST /api/mcp tools/list.","Inspect the tools/call span arguments after redaction."],"commands":["platphormctl mcp validate trace","platphormctl trace get <traceId>"],"linkedTools":["MCP","Trace","Claws"],"evidenceToCollect":["JSON-RPC id","method","tool name","redacted arguments","response error code"]},{"slug":"browserops-failed-journey","title":"BrowserOps Failed Journey","summary":"Use when a browser journey span fails or screenshot/accessibility evidence is missing.","symptoms":["browserops span failed.","Screenshot evidence ref is absent.","Journey stopped before finish span."],"likelyCauses":["Target route failed to render.","BrowserOps adapter did not link artifact refs.","Protected target rejected the journey."],"checks":["Open BrowserOps run evidence if public-safe.","Inspect /api/v1/traces/{traceId}/timeline.","Check route compliance for the target service."],"commands":["platphormctl harness run trace-propagation-check --dry-run","platphormctl trace report <traceId>"],"linkedTools":["BrowserOps","Trace","Monitor"],"evidenceToCollect":["browser run ID","screenshot ref","route URL","accessibility summary"]},{"slug":"evals-failed-scorecard","title":"Evals Failed Scorecard","summary":"Use when an Evals suite, rubric, assertion, or release gate emits a failed scorecard span.","symptoms":["evals span failed.","Scorecard evidence is failed or missing.","Release evidence report is blocked."],"likelyCauses":["A required assertion failed.","Scorecard artifact was not linked.","The target service did not expose enough public-safe evidence."],"checks":["Open Evals scorecard ref.","Inspect /api/v1/traces/{traceId}/evidence.","Check failed span error code."],"commands":["platphormctl trace report <traceId>","platphormctl harness run spec-evals-browserops-loop --target https://trace.platphormnews.com --dry-run"],"linkedTools":["Evals","Spec","BrowserOps","Trace"],"evidenceToCollect":["eval run ID","suite","rubric","assertion","scorecard ref"]},{"slug":"sandbox-timeout","title":"Sandbox Timeout","summary":"Use when a sandbox command, replay, or dry-run span times out.","symptoms":["sandbox span timed_out.","Async job deadline passed.","Sandbox output is unavailable or partial."],"likelyCauses":["Command exceeded bounded runtime.","Sandbox worker stopped heartbeating.","Execution adapter is degraded."],"checks":["Open /api/v1/jobs/{id}.","Inspect heartbeatAt and deadlineAt.","Check evidence refs for sandbox_output."],"commands":["platphormctl trace spans <traceId>","platphormctl trace report <traceId>"],"linkedTools":["Sandbox","Trace","Claws"],"evidenceToCollect":["sandbox run ID","job ID","deadlineAt","last heartbeat","redacted output ref"]},{"slug":"webhook-delivery-failure","title":"Webhook Delivery Failure","summary":"Use when a webhook event, attempt, replay, or delivery span fails.","symptoms":["webhooks span failed.","Delivery attempt has error code.","Replay span is protected or degraded."],"likelyCauses":["Receiver returned non-2xx.","Payload validation failed.","Replay requires PLATPHORM_API_KEY."],"checks":["Inspect webhook delivery evidence.","Check attempt count and status.","Verify secrets were redacted."],"commands":["platphormctl trace get <traceId>","platphormctl trace report <traceId>"],"linkedTools":["WebhookLab","Trace","Sandbox"],"evidenceToCollect":["event ID","delivery ID","attempt status","redacted response summary"]},{"slug":"spec-contract-mismatch","title":"Spec Contract Mismatch","summary":"Use when Spec validation, conformance, diff, generation, or release-gate spans fail.","symptoms":["spec span failed.","Contract evidence reports mismatch.","Release gate blocks downstream work."],"likelyCauses":["Route output does not match OpenAPI or platform contract.","Discovery files disagree.","Schema changed without regenerating docs."],"checks":["Open Spec validation evidence.","Validate /openapi.yaml and /llms-index.json.","Compare route response shape to { ok, data } or JSON-RPC."],"commands":["platphormctl site inspect trace","platphormctl policy inspect trace"],"linkedTools":["Spec","Evals","Docs","Trace"],"evidenceToCollect":["spec validation ID","route","schema","diff summary"]},{"slug":"agentui-workflow-stall","title":"AgentUI Workflow Stall","summary":"Use when an AgentUI workflow node, save/export/share/delegate, or dry-run/run span stalls.","symptoms":["agentui span is waiting.","Workflow node has no terminal event.","Delegation edge is missing from service map."],"likelyCauses":["Workflow run did not emit heartbeat.","Storage adapter is local-only.","Delegated service did not propagate headers."],"checks":["Inspect async job state.","Open trace service map.","Check node execution span parentage."],"commands":["platphormctl trace propagate --service agentui","platphormctl trace incomplete"],"linkedTools":["AgentUI","Trace","Claws","Sandbox"],"evidenceToCollect":["workflow ID","node ID","job ID","delegate target","trace headers"]},{"slug":"claws-toolchain-degraded","title":"Claws Toolchain Degraded","summary":"Use when Claws planning, dry-run, delegation, or toolchain evidence enters degraded state.","symptoms":["claws span degraded.","Toolchain evidence ref is absent.","Remediation action is auth-required."],"likelyCauses":["Protected toolchain was invoked without PLATPHORM_API_KEY.","Adapter is not configured.","Required downstream service is unavailable."],"checks":["Inspect Claws toolchain span.","Check public/protected boundary.","Open related evidence refs."],"commands":["platphormctl trace report <traceId>","platphormctl policy inspect trace"],"linkedTools":["Claws","Trace","Docs"],"evidenceToCollect":["toolchain ID","plan ID","dry-run result","protected action boundary"]},{"slug":"monitor-stale-health","title":"Monitor Stale Health","summary":"Use when Monitor health or provider sync spans are stale or unavailable.","symptoms":["monitor span is waiting or degraded.","Health summary has stale fetchedAt.","Network graph status is degraded."],"likelyCauses":["Monitor sync has not run.","Root graph or sitemap source is unavailable.","Provider health adapter timed out."],"checks":["Open /api/v1/network.","Open /api/health.","Compare fetchedAt and generatedAt values."],"commands":["platphormctl site inspect trace --best-effort","platphormctl harness run trace-propagation-check --dry-run"],"linkedTools":["Monitor","Trace","Atlas"],"evidenceToCollect":["health snapshot timestamp","source URL","status","trace ID"]},{"slug":"docs-ingestion-failure","title":"Docs Ingestion Failure","summary":"Use when Docs source fetch, parse, scoring, publishing, or report spans fail.","symptoms":["docs span failed.","Document ref is missing.","Docs report publishing is protected or degraded."],"likelyCauses":["Source fetch failed.","Parser rejected content.","Publish adapter requires PLATPHORM_API_KEY."],"checks":["Inspect docs_report evidence.","Open related trace timeline.","Check protected report route output."],"commands":["platphormctl trace report <traceId>","platphormctl policy inspect trace"],"linkedTools":["Docs","Trace","Sheets"],"evidenceToCollect":["document ID","source URL","parse summary","publish result"]},{"slug":"sheets-import-failure","title":"Sheets Import Failure","summary":"Use when Sheets import, schema, quality, report, or matrix spans fail.","symptoms":["sheets span failed.","Sheet matrix evidence missing.","Export is auth-required."],"likelyCauses":["Input schema mismatch.","Quality check failed.","Sheets export adapter is not configured."],"checks":["Open sheets_matrix evidence.","Inspect span error code.","Check report/export route boundary."],"commands":["platphormctl trace report <traceId>","platphormctl policy inspect trace"],"linkedTools":["Sheets","Trace","Docs"],"evidenceToCollect":["sheet ID","matrix ref","schema errors","quality summary"]},{"slug":"ja4-digest-correlation","title":"JA4 Digest Correlation Issue","summary":"Use when Vercel JA4 digest correlation is expected but missing or unsafe.","symptoms":["ja4 hash presence is false.","Correlation summary is degraded.","Raw digest appears in a private-only artifact review."],"likelyCauses":["x-vercel-ja4-digest was not present.","Header was captured after redaction boundary.","A public renderer attempted to expose raw metadata."],"checks":["Inspect redacted metadata only.","Search public UI and feeds for raw x-vercel-ja4-digest.","Open /api/v1/aggregate/summary correlation."],"commands":["platphormctl policy inspect trace","platphormctl trace report <traceId>"],"linkedTools":["Fingerprint","Trace","Monitor"],"evidenceToCollect":["hashed digest summary","redaction status","source service","trace ID"]}]}}