VMware Debug

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

[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: `refuted` (ruled out by case_grade'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.

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

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

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

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