[READ] Correlate already-fetched VMware events into one incident view.

WHEN: use this after you've pulled events for an incident from the data-source skills (vmware-monitor get_events/get_alarms, vmware-aria list_alerts/list_anomalies, vmware-log-insight search_logs/aggregate_logs, vmware-nsx) — feed them here to find what correlates and where to look next. Not sure which events to pull? Run list_symptom_categories first. This tool does NOT fetch anything itself.

RETURNS: {event_count, window, binning, classification, spikes (strongest anomalous bins), spikes_total, hypotheses (ranked root-cause candidates, each with a suggested_check), next_checks (which skill/tool to run next)}. Read binning for the resolution you were given, and classification for how much of the stream matched nothing — the ranking describes only the part that did.

GOTCHAS: read-only, stateless, no network — nothing is executed. Remediation routes to vmware-aiops (single fix) or vmware-pilot (multi-step). A malformed event returns {error, hint} naming the offending index.

[WRITE] Record the final grade and archive the case — step 08.

WHEN: when the investigation is finished, or is being handed over. Closing turns a working folder into a record other people rely on, so it computes and records the grade rather than accepting one.

RETURNS: {case_id, state, grade, open_gaps, path, note}. open_gaps names anything still blocking a hypothesis at the moment of closing — stated here rather than left in the file for someone to find.

GOTCHAS: a closed case is not closed again and its record is never rewritten. To reopen the question, open a new case that cites this one, so the original conclusion and whatever changed it both stay readable.

[READ] One case: its scope, its ledger sizes, and its grade history.

WHEN: to pick up an investigation, or to see why a case sits at the grade it does. Returns counts and identifiers rather than the whole ledger — read the case folder itself (the path from open_case) for full evidence bodies.

RETURNS: {case_id, path, state, grade, opened_at, scope, evidence_count, sources, gap_count, blocking_gaps, grade_history}. sources is the distinct skills evidence came from, which is what corroboration is counted in.

[READ] What the knowledge layer accepts, and what is mounted.

WHEN: when someone asks what can be added to make conclusions stronger, or when a case will not reach Confirmed and you need to say why in terms they can act on. This is the answer to "which knowledge formats do you take" — the first question anyone mounting a library asks.

RETURNS: {root, sections, entries, with_applies_to, by_source, unreadable, unsupported, formats, needs_conversion, note} — plus {applicable, decisive_here} when a case_id is given.

formats lists every extension read and how each carries its metadata: Markdown front-matter, YAML/JSON whole-file, JSONL per line, CSV/TSV per row, and plain text with a sibling .yaml. needs_conversion names the ones that must become Markdown first (PDF, DOCX, PPTX, HTML).

GOTCHAS: an entry is decisive ONLY if its applies_to block was checked against the case scope and passed — matching is by version applicability, never by similarity, because an entry written for the wrong build reads exactly like the right one. An entry with no applies_to can support a hypothesis but can never make a case Confirmed. A constraint the case scope cannot answer is not a match either: silence is not a pass.

[READ] What strength of conclusion can this environment reach?

WHEN: before starting an investigation, or when a case will not go higher and you want to know whether that is fixable. Answering this first is worth far more than discovering it halfway through.

RETURNS: {classes, categories, unrecognised_skills, note}. A name that matched no skill in the catalogue comes back in unrecognised_skills rather than being absorbed into "not installed" — otherwise a typo reads as advice to install something you already have. Per evidence class: whether it is available, through which tools, and if not, how_to_supply. Per symptom category (storage, network, compute, ha_drs, configuration, accelerator, kubernetes, hardware, host_lifecycle, power_lifecycle, auth, platform, licensing, data_collection): a ceiling and the independent_sources behind it. There is deliberately no single score — "readiness 78%" cannot be acted on, "storage reaches Probable, hardware reaches Candidate" can.

GOTCHAS: two classes served by the SAME skill count as one source, so two available classes do not always mean Probable. The hardware class is unavailable no matter what is installed — nothing in this family reaches below ESXi — and the knowledge class becomes available only when entries are mounted under $OPS_HOME/knowledge/.

[WRITE] Compute and record the conclusion grade — steps 07/08.

WHEN: when you think the investigation has reached a conclusion, or to record where it stands before handing it over.

There is deliberately NO parameter for the grade. You cannot state a conclusion level; it is recomputed from the ledger on every call. If you disagree with the result, change the ledger — submit the evidence that is missing, or record the gap that is blocking it.

The levels: Candidate (a hypothesis exists); Probable (at least two INDEPENDENT sources agree — two calls to the same skill are one source — and nothing outstanding could overturn it); Confirmed (that, plus a decisive item: a direct hardware diagnostic, a version-checked knowledge-base entry, or a vendor SR, and no gap left open); Excluded (an observation that actually rules the hypothesis out — "we looked and found nothing" is a gap, not an exclusion). Exclusion is per hypothesis, counting only sources that falsify THAT hypothesis; the case is Excluded only when every registered one is. A hypothesis contradicted but not yet ruled out holds the case at Candidate. Otherwise the grade counts only evidence that falsifies nothing.

RETURNS: {grade, previous, direction, reasons, ceiling, ceiling_reasons, rules_source, rules_origin, hypotheses}. hypotheses lists every registered hypothesis as {id, status: open|excluded}. direction is initial/up/down/unchanged — grades may go DOWN, and the history records it when they do.

GOTCHAS: on a stock install ceiling is "probable", because Confirmed needs a decisive source and there is neither a hardware-diagnostic channel nor a knowledge library mounted yet. That is a real limit, not a caution. Every grading is appended to conclusion.md and none is ever rewritten.

[READ] List investigation cases, newest first.

WHEN: to find the id of a case you or someone else opened earlier. Returns the family list envelope {items, returned, limit, total, truncated, hint}; each item is {case_id, summary, state, grade, opened_at}. A case whose folder is damaged appears with state="unreadable" rather than vanishing from the list.

[READ] List the symptom categories vmware-debug recognises, each with example keywords and a suggested next check (which skill/tool to run). Takes no parameters. Use this when you don't yet know what to look at — it turns "something's wrong" into concrete investigation steps. Then gather the events those checks name and pass them to build_incident_timeline. Returns the family list envelope {items, returned, limit, total, truncated, hint}; each item is {category, example_keywords, suggested_check}. The routing table is a fixed constant, so truncated is always false and total exact — this is every category, not a page. Read-only; no network access.

[WRITE] Open an investigation case — step 01, define the event.

WHEN: at the start of an incident you expect to reason about rather than glance at. For a one-off lookup use build_incident_timeline alone.

RETURNS: {case_id, path, state, grade, ceiling, ceiling_reasons, next}. Read ceiling now — it is the best grade this install can reach at all.

GOTCHAS: writes only under $OPS_HOME, never to a VMware system, and never over an existing case.

[READ] What to fetch next for this case — step 02, recomputed each call.

WHEN: right after open_case, and again after each round of evidence. It is not a checklist: submit something and the next plan is shorter, lose a source and it routes around it.

RETURNS: {category, category_signals, steps, already_covered, held_back, unavailable, ceiling, note}. Steps are interleaved across evidence classes, so you get breadth before depth — corroboration is counted in distinct sources, which is what actually moves the grade. Each step is {evidence_class, skill, tool, purpose, objects, window, degraded} — call that skill's tool, then submit the result with submit_case_evidence.

GOTCHAS: unavailable is the important half. A source this install cannot reach is listed there with how_to_supply rather than left out, so the gap is visible now instead of when the conclusion refuses to firm up. An empty steps is never silent — note says whether everything reachable is already in, or whether nothing here can be reached. category_signals names the words that chose the category, and any category that also matched — check it first, since the rest runs off that one word.

[WRITE] Record something the investigation could NOT obtain.

WHEN: any time a fetch failed, was refused, returned nothing, or the data simply does not exist in this environment. This is the tool that keeps a case honest: an unrecorded gap makes it look better supported than it is.

RETURNS: {case_id, gap_id, grade, reasons}.

GOTCHAS: recording a gap does not punish the case for the evidence it does have — a missing confirmation caps the grade, it does not demote it. Writing gaps down is meant to be free.

[WRITE] Register a candidate explanation — step 06. Called without statement it writes nothing and only reads the hypothesis ledger.

WHEN: as soon as you have a theory worth testing, and again to see where each one stands. Pass statement to add one; omit it to just read.

Every hypothesis gets an id (H1, H2, …). Those ids are what record_case_gap(blocks=[...]) and submit_case_evidence(falsifies=[...]) refer to, and an id that was never registered is REFUSED rather than ignored — a dangling reference blocks nothing and falsifies nothing, which quietly reports a stronger case than you have.

RETURNS: {case_id, added, hypotheses, note}. Each entry carries its status: refuted (ruled out by grade_case's rule), blocked (a gap is in the way, with the gap id and how to close it), or open. refuted_by lists every falsifying item; the first next step says when more sources are needed. Status is computed from what points at the hypothesis, never asserted.

GOTCHAS: refuted outranks blocked. Once an observation settles the question, a missing measurement no longer matters.

[WRITE] Correlate everything this case has collected — steps 04/05.

WHEN: once evidence is in. Unlike build_incident_timeline, this takes no events: it reads the payloads already submitted, so the result is reproducible from the case folder alone months later, on a machine with access to nothing.

RETURNS: {event_count, window, binning, classification, spikes, spikes_total, hypotheses, evidence_without_events, evidence_without_events_detail, rejected, note} and writes timeline.md.

GOTCHAS: note distinguishes three states that all show zero events — no evidence submitted at all, evidence that carried none, and a genuinely quiet window — and names which items carried none, with what they held instead. rejected names any row that could not be read, with the evidence item it came from; dropping those silently would shrink the picture the conclusion rests on. Submit a read tool's raw result as payload for its events to reach here — a summary of the result carries no rows, and submit_case_evidence says so at the time.

[WRITE] Record one retrieved fact — steps 02/03 of the evidence loop.

WHEN: after every read-tool call you intend to reason from.

RETURNS: {case_id, evidence_id, payload_events, payload_note, grade, reasons} — the resulting grade, so you need no second call to see whether this changed anything, and what the payload was read as, so a summary submitted in place of a result is visible here rather than as a zero from record_case_timeline later.

GOTCHAS: a fetch that failed or came back empty goes to record_case_gap, not here.