Trace a workflow failure
Diagnosis starts from an observed action and its last confirmed outcome. Identify the environment, actor, company, resource and component versions before deciding which layer failed. A visible error, timeout or empty view does not identify whether the underlying transaction committed or an external effect occurred.
Prerequisites and safe evidence
Section titled “Prerequisites and safe evidence”Use the affected user’s authorized scope or the established diagnostic procedure. Shared functional checks use Vi Målar; keep its persistent identities and sessions. Do not reproduce an accounting send or payroll-queueing approval there: its Fortnox company is real. Source review and synthetic local checks usually need no shared provisioning.
Record a sanitized action, time, request/error code, relevant synthetic or access-controlled record identifiers and current component versions. Keep customer payloads, access tokens, token-bearing URLs and provider credentials out of Git and routine logs. Raw diagnostics belong only in their authorized restricted source.
Symptom reference
Section titled “Symptom reference”| Symptom | First discriminating evidence | Next owner/check |
|---|---|---|
| Page or asset fails | HTTP route/status and frontend build identity | Static publication/proxy |
| Read denied | Accepted actor/company and exact resource predicate | RLS or API authorization; never bypass with service role |
| Save conflicts | Revision conflict and fresh owning record | Editor/transaction reconciliation |
| Request times out | Last durable local state and operation identity | Transaction/provider uncertainty before retry |
| Queue does not finish | Intent, claim, attempts, scheduler progress and receipt | Background component or integration recovery |
| Totals disagree | Same record identity, amount definition and source coverage | Financial reconciliation, not UI formatting alone |
| Whole API unavailable | Liveness, readiness and independent monitor evidence | Runtime/configuration incident |
Trace procedure
Section titled “Trace procedure”- Reproduce only the permitted, minimally necessary read/action. Capture the failing route and whether the path uses browser RLS or the privileged API. A missing control is not a permission test.
- Establish current identity/company/resource scope. Distinguish denial, missing record and an incomplete paginated projection. Avoid turning an access failure into a claim that the record does not exist.
- Read the owning transaction state. For a conflict, obtain the fresh revision and let the owning editor resolve it. For a timeout, determine whether the durable change exists before repeating a mutation.
- If work is asynchronous, follow intent to claim, processing state and confirmed receipt. Compare component progress and configured enablement. An idle queue can be correct; a running scheduler can be failing every tick.
- At the provider boundary, use the same operation and destination identity. Reconcile an uncertain result through its supported contract before retrying. A local HTTP success or queued row is not provider completion.
- Correct the smallest established defect through its owner. Preserve failed evidence, then verify both the negative boundary and the intended positive behaviour at the corrected version.
Concrete synthetic example
Section titled “Concrete synthetic example”A synthetic staff member reports that a customer notification remains pending. The browser save succeeded and a durable intent exists, so recreating the intent risks duplicate work. Check the API version and notification component progress. If progress is stale, inspect the scheduler’s bounded error evidence. If progress is fresh, inspect that intent’s claim/attempt/outcome and the external receipt path.
After fixing an established scheduler defect, verify that it resumes eligible work and still refuses an unauthorized recipient. A new heartbeat alone proves only progress; a delivered receipt for the named synthetic operation proves its scoped outcome. Background states and external recovery own the retry rules.
Failure handling and conclusion
Section titled “Failure handling and conclusion”If the required evidence is missing, record the unresolved boundary and next discriminating check. Do not invent a result, mass-repair records or broaden access. Active exposure or a complete outage moves to incident response. API errors, health and financial reconciliation provide the layer-specific contracts. A diagnosis is complete when the owner and confirmed failure boundary are known; recovery still needs the affected behaviour check.