idmp-analysis

analysis

Read ../idmp-shared/SKILL.md first.

Before any write: Follow the 🛑 Destructive op confirmation protocol. Read-only commands stay read-only here, but delete / write / patch flows still require the shared yes-gate.

Recommended shortcuts

Shortcut	Purpose
+list	Read analyses under one element.
+search	Search analyses globally, including an empty-keyword starting point.

Recommended references

• analysis read flows
• ../idmp-workflow-analysis-create/SKILL.md
• ../idmp-workflow-alert-create/SKILL.md

Missing context to resolve first

Context	Why it must be resolved before create or resume
Final owner and mode	You need the exact elementId or elementTemplateId before you can choose the right command family or reserve a name.
Business root	Element-mode analysis creates still need rootElementId from the business root, even when the real owner moves to a data-bearing leaf. Prove that root with element elements path plus element fullpath get before you send the create payload.
Candidate analysis name	analysis.analyses.new-name and analysis-template.analyses.new-name require a candidate name.
Trigger scope	You need to know applyOnSelf, child-template scope, and which trigger type is valid after that choice.
Output plan	Decide whether to reuse or create output attributes, which valueType they need, and whether they land on self or child scope.
Runtime target	Decide whether Ready is acceptable or whether the final workflow must end in Running and therefore needs resume.

Constrained live behaviors

• Prefer POST /api/v1/ai/analysis/create for natural-language analysis or alert intents, then persist the returned draft through the normal create path. Use the structured DTO workflow as the fallback when the draft is unsuitable or persistence fails.
• analysis.analyses.new-name and analysis-template.analyses.new-name require a candidate name and --ack-risk; do not call them with only the owner scope.
• In element mode, rootElementId comes from the business root rather than the current leaf element.
• Shared environments can force analysis creation onto a data-bearing leaf when trigger-types list is empty on the current owner.
• Child scope does not inherit self-scope triggers. When applyOnSelf=false, the backend can legitimately expose only Session and Interval, so do not assume DataInput or Event will stay available.
• Minimal create payloads need rootElementId, startAfterCreated, a valid trigger, and real output.attributes[].attrId values. For current live ELE_SUBET flows, child-scope analyses can use owner-element output attributes while output.elementTemplate.id continues to point at the child template.
• Analysis create is not complete until get, list, and, when needed, resume prove the backend kept the object in the expected runtime state.
• Current live backends can return success for analysis delete while the generated output attributes remain referenced. Once create, reread, and resume prove the analysis itself worked, classify leaked output-attribute cleanup as a backend boundary instead of a wrong create payload.
• If the workflow must emit events or notifications, switch to ../idmp-workflow-alert-create/SKILL.md instead of treating it as a generic read or create flow.

Evidence of completion

• A reserved name is only useful when the later create reread shows the same name on the persisted object.
• A create is only complete when analysis analyses get and analysis analyses list show the same id, owner scope, and expected state bits.
• If the success condition is a running analysis, do not stop at Ready; reread after resume and confirm the runtime state actually changed.
• Shared-environment cleanup is best-effort. If delete returns success but the output attribute still shows a backend reference leak, keep the leaked IDs with the report and do not downgrade an already-proven create or running analysis into a payload-shape failure.
• If rootElementId was part of the write path, keep the element elements path and element fullpath get evidence with the create proof.

Product behavior to preserve

• Read path, attributes, sub-templates, trigger-types, and new-name before create or edit.
• For natural-language creation asks, prefer the AI draft endpoint first and keep the structured create flow as the fallback.
• analysis.analyses.new-name and analysis-template.analyses.new-name require a candidate name and --ack-risk; do not call them with only the owner scope.
• In element mode, the create payload needs rootElementId from the business root, not the current element.
• Copyable live-safe create shapes belong in ../idmp-workflow-analysis-create/SKILL.md, especially when the payload must include output.attributes[].
• Trigger type choices depend on applyOnSelf and, for child scope, the selected template.
• If a create flow is abandoned after reserving a temporary output attribute, clean up that temporary attribute before retrying.
• After create or update, read the analysis back and resume it if the expected state is running.

Key commands

idmp-cli schema analysis.analyses.list
idmp-cli analysis analyses list --params '{"elementId":123,"current":1,"size":20}'

idmp-cli schema analysis.analyses.get
idmp-cli analysis analyses get --params '{"elementId":123,"id":456}'

idmp-cli schema analysis.analysis.search
idmp-cli analysis analysis search --params '{"keyword":"voltage","current":1,"size":20}'

idmp-cli analysis analyses new-name --ack-risk --params '{"elementId":123,"name":"demo-analysis"}'
idmp-cli analysis trigger-types list --params '{"elementId":123,"applyOnSelf":true}'
idmp-cli analysis trigger-types list --params '{"elementId":123,"applyOnSelf":false,"elementTemplateId":456}'

idmp-cli schema analysis.analyses.resume
idmp-cli analysis analyses resume --ack-risk --params '{"elementId":123,"id":456}'

Exception and failure handling

• If trigger-types list changes after applyOnSelf or the child template changes, discard the earlier trigger choice and re-read it.
• If child-scope trigger types only show Session or Interval, redesign the analysis around those trigger families or move back to self scope; do not force Event or DataInput.
• If the element path does not resolve to a business root, do not create the analysis until rootElementId is known. Treat “resolved” as element elements path plus element fullpath get agreeing on the same first-level owner.
• If output attributes were created only for a draft analysis and the draft is canceled, remove the temporary outputs before the next attempt.
• If delete succeeds but attribute elements attributes-delete still reports the output attribute is referred by the analysis, classify that as a backend cleanup boundary after you have already captured the create or running proof; stop retrying generic cleanup loops.
• If create or update succeeds but get still shows an unexpected state, verify with list and then use resume instead of sending another create.
• If search results are ambiguous, confirm the owner element before editing; do not reuse an id from a different element or template scope.

Validation scenarios

1. Read the owner list with idmp-cli schema analysis.analyses.list and idmp-cli analysis analyses list --params '{"elementId":123,"current":1,"size":20}'.
2. Read one analysis in detail with idmp-cli analysis analyses get --params '{"elementId":123,"id":456}'.
3. Check global discoverability with idmp-cli analysis analysis search --params '{"keyword":"voltage","current":1,"size":20}'.
4. Resolve the business-root proof chain with idmp-cli element elements path --params '{"elementId":123}' and idmp-cli element fullpath get --params '{"rootElementId":100,"elementId":123}', then validate create prerequisites with idmp-cli analysis analyses new-name --ack-risk --params '{"elementId":123,"name":"demo-analysis"}' and idmp-cli analysis trigger-types list --params '{"elementId":123,"applyOnSelf":false,"elementTemplateId":456}'.
5. Preview and verify the write path with idmp-cli analysis analyses create --dry-run --ack-risk --params '{"elementId":123}' --data '{...}', then prove the runtime branch with idmp-cli analysis analyses get --params '{"elementId":123,"id":456}', idmp-cli analysis analyses list --params '{"elementId":123,"current":1,"size":20}', and idmp-cli analysis analyses resume --dry-run --ack-risk --params '{"elementId":123,"id":456}'.