marivo-analysis

name	marivo-analysis
description	Use when a user wants to run or continue a trusted Marivo investigation over governed metrics, Events, StateModels, or persisted analysis artifacts.

marivo-analysis

Purpose and ownership

Use this skill to turn a business, product, or operational question into a bounded, evidence-backed Marivo investigation. This skill owns workflow boundaries, handoffs, evidence continuity, and closeout obligations. The agent owns planning, method choice, analytical judgment, synthesis, and stopping.

Trust the verified installed Marivo environment and its live guidance:

• marivo.help("analysis") owns the environment fingerprint, responsibility boundary, and progressive entry map;
• analysis.entry, analysis.methods, analysis.inputs, analysis.artifacts, analysis.evidence, and analysis.runtime are the six discovery hubs;
• focused marivo.help("analysis.<target>") owns exact signatures, constraints, return types, and examples;
• governed semantic objects own reusable business meaning;
• .show() owns bounded current artifact state;
• .contract() owns mechanically valid next actions;
• marivo.help("analysis.boundary.to_pandas") owns the exact terminal exit;
• structured errors own repair guidance.

Do not reconstruct those contracts from this skill, remembered syntax, or private implementation details.

Bounded analysis loop

1. Frame the question as an Evidence obligation

Before execution, identify the answers the investigation owes the user. For each required answer, record the claim or decision it supports, the exact population and governed inputs, the time and comparison scope, the minimum supporting evidence, and whether the answer is observed, interpreted, or currently unsupported.

Preserve scopes named by the user. Do not replace a selected cohort, segment, top-N set, time window, comparison direction, or exhaustive request with a broader or easier analysis. Add optional analysis only when it can materially change a required conclusion, recommendation, or limitation.

2. Establish the governed starting point

Use the host-selected verified Marivo environment throughout. Create or resume one question-scoped session. Resolve the exact typed semantic inputs together and inspect readiness only for the required closure. Reuse a current semantic handoff for the same project and scope instead of repeating it.

If the required capability is unknown, start with marivo.help("analysis"). Route through marivo.help("analysis.inputs") for input construction or marivo.help("analysis.entry") for the first typed Artifact, then consult the focused Help for the selected capability. Avoid broad catalog browsing when an exact typed ref or full semantic identity is already available.

3. Build the minimum typed Evidence chain

Produce a bounded typed Artifact early. Inspect .show() when current state contributes evidence and use .contract() when the mechanically valid next actions are unknown. Route method discovery through marivo.help("analysis.methods"), but choose subsequent methods from the question and the Artifact in hand rather than from a fixed recipe.

Before treating a calculation as custom, classify its analytical intent against the installed capability map. Stay in typed flow whenever Marivo expresses that intent. Batch compatible work into one decision round, prefer the smallest chain that supports a required answer, and stop expanding when another result cannot materially change the answer or its limitations.

4. Validate before interpreting

For every material result, check the semantic identity and exact population; time coverage, completeness, censoring, and comparison alignment; grain, units, additivity, and reconciliation where applicable; missingness, uncertainty, and quality blockers; and the boundary between observation, association, projection, hypothesis testing, and causal evidence.

Use marivo.help("analysis.artifacts"), marivo.help("analysis.evidence"), the Artifact's current state, and its structured contract for the installed inspection mechanics. Preserve warnings and partial coverage. Do not turn absence into zero, association into causation, a point forecast into certainty, or a segment result into a population claim.

5. Synthesize, hand off, or stop

Close the investigation when every required answer is supported or explicitly blocked. Separate observed or computed facts, interpretations supported by those facts, recommendations or hypotheses requiring judgment, and unsupported questions with their smallest missing evidence or semantic object.

Hand only reusable semantic gaps to marivo-semantic. Resume the affected analysis branch from the returned analysis-ready inputs; do not restart unaffected branches or require redundant user approval.

Hard boundaries

Semantic authority

Take metrics, dimensions, Events, StateModels, participant roles, relationships, units, definitions, and admissible joins from the semantic catalog. Analysis may choose question-specific windows, alignments, cohorts, policies, seeds, and completeness declarations, but it must not author or edit reusable semantic definitions while this skill is active.

A missing or disputed reusable business object stops only the affected branch. Record the smallest gap and hand it to marivo-semantic. Never substitute a physical column, guessed join, different metric, or presentation label for governed meaning.

A runtime metric remains a question-scoped expression over governed inputs; it does not become reusable organizational truth. Preserve the assumptions and limits that materially affect a conclusion, and hand the definition to marivo-semantic if it must become reusable.

Typed execution and terminal exits

Do not query business rows through Ibis, DuckDB, pandas readers, backend connections, private datasource handles, or ad hoc SQL to bypass Marivo.

Before a terminal conversion, read marivo.help("analysis.boundary.to_pandas"). Exit typed flow only when the required method is outside the installed governed surface and a bounded typed Artifact already establishes the inputs, scope, and Evidence chain. Keep the terminal calculation rerunnable alongside the exit, do not export and reload Artifact rows, and never feed a terminal result back into typed analysis.

Evidence continuity and recovery

Use one question-scoped session and carry exact Artifact identities across decision rounds. Do not depend on process memory, an implicit latest result, imported prior scripts, chat summaries, or repeated successful observations as substitutes for persisted identity.

When resuming work, start with marivo.help("analysis.runtime") and use only its public runtime reads to recover the relevant branch. Consult marivo.help("analysis.evidence") before treating recovered Evidence as current. Use the installed revalidation and repair guidance when authority-sensitive reuse requires it; mechanical compatibility alone is not current semantic authority.

Runtime history, graph projections, and persisted Evidence reads aid recovery and audit. They do not by themselves establish current semantic authority, datasource freshness, causal interpretation, or business validity. Stop and disclose an affected branch when its authority or Evidence cannot be restored, and disclose freshness as unchecked unless a separate current source check establishes it.

Cold-start recovery starts with bounded Run history. Use the runtime Help route to choose the installed Run read, restore the exact committed Artifact through the public runtime read, use a focused Session graph only for factual adjacency, and choose Artifact-owned Finding reads when audit details are required.

Structured repair and stopping

Follow the structured repair or focused Help for a failed public capability. Do not invent a neighboring API, private workaround, or silent fallback. Stop and disclose the affected branch when the current public contract cannot produce the required Evidence.

Closeout

Answer the user's questions first in their business vocabulary. For every material conclusion:

• state the supported direction and the magnitude or uncertainty needed to interpret it;
• preserve the exact source, scope, definition, and comparison that govern it;
• distinguish Evidence, interpretation, recommendation, and hypothesis;
• disclose material blockers, warnings, omissions, quality limits, and terminal exits;
• keep the supporting semantic refs, Session, Run, Artifact, and scope recoverable without exposing runtime bookkeeping unless the user requests an audit;
• name missing reusable semantic objects and route their authoring to marivo-semantic.

Do not prescribe a fixed report template or continue exploring after the required answers and limitations are complete. Delivery or publication belongs to an independent capability when the user requests it.