Skip to main content
Limited Release. The EDK is currently in limited release and is not available to all customers. Commands, generated file layouts, and package APIs may change before general availability. Confirm you’re on the latest EDK version before starting new projects.
Troubleshoot from the workspace outward. Confirm the target first, then isolate authoring and deployment failures before investigating records, automations, or agents. This order reduces unnecessary live changes and keeps each conclusion tied to evidence. The examples assume the organization workspace selects one matching saved profile. See Authentication if the target is ambiguous. Use the /elementum-debug coding-agent playbook when you want an assistant to follow this evidence-first sequence. See Playbooks. Before running commands, capture:
  • The exact action that failed.
  • The expected and actual results.
  • The profile and App namespace.
  • When the behavior last worked.
  • Any record, automation execution, or conversation identifier.
Do not edit source until the evidence identifies the failing layer.

​
1. Confirm the Profile and Workspace

Run from the affected organization workspace:
Confirm that the profile’s instance and organization match the workspace path. If the workspace is new or its generated references may be stale, verify that it was bootstrapped with:
Classify an early failure as one of:
  • Authentication or permissions.
  • Profile and workspace mismatch.
  • Missing workspace setup.
  • Stale organization references.
  • Missing or incomplete App or Element source.
Pull the affected App or Element before editing an existing deployed object:
Review pull diagnostics and skipped items. Do not continue as though an unsupported part of the solution is managed by the generated source.

​
2. Isolate Typecheck and Build

Run the validation layers separately:
If typecheck fails:
  1. Fix the first causal error rather than every downstream error.
  2. Confirm builder imports use public @elementumai/edk subpaths.
  3. Confirm cross-entity references come from @catalog.
  4. Refresh the organization or owning App when an expected catalog token is missing.
  5. Do not use a broad cast, guessed token, UUID, or generated-file edit to silence the error.
If build fails, use the source path and diagnostic in the output. A build diagnostic can mean that valid TypeScript contains an option the current deployment path cannot represent safely. Remove or change it only when that matches the intended behavior; otherwise report the limitation. Do not edit org.ts, generated/catalog.ts, .tf/in/, or .tf/out/ to repair a typecheck or build failure. Refresh or regenerate those paths with their owning commands.

​
3. Isolate Plan and Apply

After typecheck and build pass:
Separate:
  • Authentication or workspace selection failures.
  • Backend or deployment state failures.
  • Invalid authored configuration.
  • An unexplained create, replacement, or removal.
  • A difference that was authored correctly but has not been applied.
If the plan shows known deployed objects as new, stop. The deployment state binding may be missing or stale. Restore the workspace and state from the approved source, or re-pull the affected App and Element to connect them. Do not apply a plan that would recreate known live objects. If a plan succeeds but live behavior is stale, confirm that the intended plan was applied and that any required automation revision or publication change was included. Never apply a speculative fix. Review the plan and obtain approval first. After an approved apply, run a fresh plan and confirm that no unintended changes remain.

​
4. Inspect Records and Automations

When deployment is current, inspect live data:
Compare the stored record with the expected trigger inputs and final business result. Confirm field values, status or stage, relationships, files, and validation behavior. For an automation failure, begin with the execution timeline:
Then inspect only the failed action:
Compare the trigger data, action input, action output, persisted record state, and expected business outcome. Expand to the complete input and output report only when the failing boundary remains unclear:
This sequence distinguishes a trigger problem from an action problem, a persistence problem, or a downstream integration problem.

​
5. Inspect Agents and Tools

Reproduce an agent failure with one minimal turn:
Determine which layer failed:
  • Routing to the intended agent or capability.
  • Agent instructions or confirmation boundaries.
  • Tool selection.
  • Tool inputs.
  • The automation or service behind the tool.
  • Returned data.
  • Interpretation of the result in the final response.
  • Multi-turn context.
If a file is involved, reproduce with the same file type and a representative size by adding -a <path>. Verify the tool call and its effect independently; a reasonable final response does not prove that the correct tool ran. When an agent delegates work, inspect the delegated result separately from the parent agent’s use of that result.

​
Verify the Fix

State one evidence-backed root cause and the smallest layer that owns it. After changing source, rerun:
plan builds the current source automatically. After an approved apply, repeat the original record, automation, or conversation reproduction. Add one adjacent regression check that could have been affected by the fix. Report:
  • Root cause and owning layer.
  • Evidence used to reach the conclusion.
  • The change made.
  • Validation and live verification results.
  • Any remaining uncertainty or untested boundary.