[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 log_search/log_aggregate, 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.

[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 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 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] 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] 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 case_open) 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.

[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 case_timeline later.

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

[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] 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).

RETURNS: {grade, previous, direction, reasons, ceiling, ceiling_reasons, rules_source, rules_origin}. 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] 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): 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/.

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

WHEN: right after case_open, 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 case_submit_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] Register a candidate explanation, or read the ledger — step 06.

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 case_record_gap(blocks=[...]) and case_submit_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 and what produced it: refuted (an observation ruled it out, with the evidence id), blocked (a gap is in the way, with the gap id and how to close it), or open. Status is computed from what points at the hypothesis — a hypothesis does not get to claim it is well supported, the same way a case does not get to state its own grade.

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 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 case_submit_evidence says so at the time.

[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] 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.