Version 1.1 | March 2026 | Reviewed by Dev the Dev

What this reference is for Look up what a specific MVAL field requires, check whether your entry meets the standard, or find the correct treatment for failure events. If you want to understand why the MVAL protocol exists, see the System Overview. If you need to configure the corpus your entries go into, see Corpus Management.

MVAL Quick Reference

MVAL is not a form to fill out after the work is done. It is the structure through which the work gets done. Every log entry must address all six fields before the entry is considered complete. An entry with five fields is not a partial entry — it is an incomplete entry. Incomplete entries will not pass Critic review.

Field	What it captures	Most common failure mode
WHAT	The specific task or experiment attempted	Too general — "worked on pipeline" instead of the specific action taken
WHY	Reasoning, alternatives considered, decision logic	Absent — this is the field most lost during personnel transitions
HOW	Exact methodology, code logic, steps taken	Too high-level — cannot be reproduced from the entry alone
ENVIRONMENT	Library versions, cloud config, credentials (names only), dataset checksums	Incomplete — missing version numbers or dataset identifiers
RESULTS	Actual outcome including failures, error messages, stack traces	Euphemized — "had some issues" instead of verbatim error output
QUESTIONS	Uncertainties, open hypotheses, follow-up threads	Left blank — "done" is treated as equivalent to "no open questions"

Field Specifications

WHAT

The specific task or experiment attempted. Must describe the operational goal in granular, actionable detail. The reader should know exactly what was being attempted without reference to any other document or conversation.

❌ Insufficient

"Worked on pipeline." / "Made progress on the scraper." / "Did some testing."

✓ Sufficient

"Implemented retry logic for the ATS scraper to handle 429 rate-limit responses from LinkedIn's public search endpoint. Target: graceful backoff with jitter, max 3 retries per request."

WHY

The underlying reasoning for the chosen approach, including alternatives considered and rejected. This is the field most often lost during personnel transitions. It captures institutional logic — the "why this and not that" that lives nowhere else.

❌ Insufficient

"Because it was the next step." / "Team decided to do it this way." / left blank.

✓ Sufficient

"The scraper was failing silently on rate-limit responses, returning empty results rather than errors. The 429 handling is needed before we can trust any data volume metrics. Considered a proxy rotation approach but rejected it — ToS risk, and rate limits suggest we're pulling too fast rather than being blocked."

HOW

Precise methodology: code logic, data transformations, API calls, tool configurations, and exact steps taken. The standard: a competent researcher should be able to reproduce the work from this field alone without asking anyone questions. This is the "virtual witnessing" passage.

❌ Insufficient

"Wrote a retry function and tested it." / "Used exponential backoff."

✓ Sufficient

"Added tenacity library retry decorator to scrape_page(). Config: wait_exponential(multiplier=1, min=4, max=60), stop_after_attempt(3), retry_if_exception_type(RateLimitError). Implemented custom RateLimitError exception raised on HTTP 429. Added jitter via random.uniform(0, 2) added to base wait. Tested with mock server returning 429s for first 2 requests."

ENVIRONMENT

Runtime configuration, library versions, cloud infrastructure, credentials used (role names only — never raw keys), dataset identifiers and checksums. The cloud laboratory must be rebuildable from this field. If the environment is not logged, the result is not reproducible — it is merely repeatable until it isn't.

❌ Insufficient

"Python 3, GCP, latest libraries." / "Standard environment."

✓ Sufficient

Security rule: Log credential role names and service account identifiers — never raw API keys, passwords, or secret values. Raw keys in MVAL entries are a security incident.

RESULTS

Actual outcome — including failures. A failed pipeline is logged with the same rigor as a successful result. Include error messages verbatim, stack traces, and unexpected outputs. Do not interpret, soften, or summarize errors — paste them. Failures are not mistakes; they are data.

❌ Insufficient

"Had some issues with the retries." / "Mostly worked." / "Got an error but fixed it."

✓ Sufficient — successful run

"Retry logic confirmed working against mock server. 3 simulated 429s followed by success on 4th attempt. Total requests: 847 across 2-hour test. Zero silent failures. Data volume: 12,340 job postings ingested. MD5 of output: d4e8..."

✓ Sufficient — failed run

"Retry decorator raised RetryError after max attempts on 14% of requests — higher than expected. Stack trace: tenacity.RetryError: RetryError[<Future at 0x... state=finished raised RateLimitError>]. Root cause unclear: may be IP-level throttling rather than account-level. Need to test with rotating source IPs."

QUESTIONS

A record of uncertainties, open hypotheses, and follow-up threads generated by this session. Prevents the closure illusion — the false sense that a completed task means all related questions are resolved. These questions become the starting context for the next session and the next researcher.

❌ Insufficient

left blank, or "None — task complete."

✓ Sufficient

"Is the 14% retry failure rate IP-throttling or account-level? Does jitter need to increase? Should we log 429 responses to a separate error table before retry to preserve the raw signal? What is the acceptable failure-rate threshold before we escalate to proxy rotation?"

Failure Artifact Protocol

Failures are not optional entries. A failed experiment that is not logged is worse than a failed experiment — it is a failed experiment that will be repeated. The failure artifact protocol exists because negative results carry the same scientific value as positive ones.

Event Type	MVAL Treatment	Required Fields	Critical Obligation
Successful pipeline run	Standard MVAL entry	All six fields	—
Failed pipeline run	Standard MVAL entry — identical rigor to success	All six + error verbatim in Results	Do not summarize error messages. Paste them.
Partial / ambiguous result	Standard MVAL with explicit uncertainty stated	All six + explicit uncertainty in Questions	Label it partial. Do not present ambiguity as resolution.
Abandoned approach	MVAL entry logging the rejection reasoning	Why (critical) + Results (why stopped)	Why you stopped is as important as what you tried.
Undocumented prior decision	Retroactive MVAL reconstruction	Why + How + note that this is reconstructed	Mark it explicitly: "Reconstructed [date] from memory / code review."

Entry Compliance Checklist

Before submitting any MVAL entry, verify all of the following. An entry fails compliance if any item is unchecked.

MVAL Compliance — Six-Field Verification

Check	Field	Verification question
□	WHAT	Can a new team member reconstruct what was attempted from this field alone?
□	WHY	Does this field explain why this approach rather than the alternatives?
□	HOW	Is this reproducible from this field alone — without asking anyone?
□	ENVIRONMENT	Are all library versions, cloud specs, and dataset identifiers present? No raw keys?
□	RESULTS	Are errors quoted verbatim? Is ambiguity labeled as ambiguity?
□	QUESTIONS	Are open questions stated — even if the task is complete?

BD-006: MVAL Not Yet Enforced at Platform Level MVAL compliance currently depends on researcher discipline — there is no hard field validation or submission gate. This is a known structural gap. A structured intake form and enforcement mechanism are in development. See Roadmap AI-001.

MVAL in Non-Technical Contexts

The standard MVAL includes an Environment field designed for cloud computing contexts — library versions, compute instances, API credentials. For executive education and policy research contexts, "environment" refers to organizational and analytical context rather than infrastructure.

Field	Technical research	Executive education / Policy research
WHAT	Specific experiment or pipeline run	Specific analysis, case discussion, or decision made
WHY	Algorithmic or architectural reasoning	Strategic reasoning; stakeholder considerations; alternatives rejected
HOW	Code, tooling, methodology	Analytical framework applied, data sources used, process followed
ENVIRONMENT	Cloud specs, library versions, dataset checksums	Organizational context, data vintage, regulatory constraints, team composition
RESULTS	Pipeline output, error logs, metrics	Decision reached, recommendation made, consensus or disagreement recorded
QUESTIONS	Open technical hypotheses	Unresolved strategic questions, assumptions that need testing

An official Executive Education MVAL variant with adapted field definitions is on the roadmap. See Roadmap §25.

MVAL PROTOCOL

MVAL Quick Reference

Field Specifications

Failure Artifact Protocol

Entry Compliance Checklist

MVAL in Non-Technical Contexts