RISK.md

A Shared Language for Underwriting

A White Paper on Portable, Evidence-Linked Risk Context for Businesses and Insurance Markets

Version 0.2 — Revised Draft · July 7, 2026

Working document for discussion and iteration. Not legal, regulatory, actuarial, claims, or licensed insurance advice.

Executive Summary

Insurance does not need one universal underwriting model. It needs a shared way to describe a business before every company, broker, syndicate, claims team, and agent asks for the same facts again.

RISK.md is a proposal for that shared layer: one company-owned, agent-readable context packet containing the current facts, exposures, controls, incidents, evidence, unknowns, permissions, questions, and material changes relevant to understanding the risk of a business.

The file would not decide whether a risk is acceptable. It would make the underlying context consistent enough for different parties to apply their own appetite and judgment without rebuilding the record from scratch.

The strategic opportunity is simple:

• answer a factual question once, then reuse the answer wherever it is authorized and still current;
• preserve each market's distinct questions without duplicating the underlying company facts;
• let underwriters see what changed instead of rereading an entire submission;
• let agents read, update, validate, and translate the same context packet; and
• let claims and portfolio insights return to the record that future decisions begin from.

The goal is not to standardize underwriting. It is to standardize the risk context underwriting starts with.

1. The Cost of Reconstructing Risk

Business risk context is scattered across applications, spreadsheets, contracts, control reports, loss runs, claims notes, data rooms, security systems, and the memories of people who may not join the next meeting.

Every handoff compresses the story differently. A company restates its operations for a broker. The broker restructures the same facts for a market. Each underwriter asks for overlapping evidence. Claims teams later reconstruct which facts were known, when they changed, and what was represented. Portfolio teams aggregate inconsistent labels after decisions have already been made.

This fragmentation creates more than administrative cost:

• repeated ingestion delays risk selection;
• stale or unsupported facts survive through copied documents;
• uncertainty is flattened into confident prose;
• different parties cannot tell whether disagreement comes from appetite or inputs;
• sensitive information is overshared because disclosure scope is not explicit; and
• lessons from claims do not reliably return to the underwriting record.

The market should be able to preserve plural judgment without paying to rediscover the same underlying context every time.

1.1 A Cyber Liability Broker's View

The pattern is especially visible in cyber liability. In my experience as a cyber broker, insurers often used different applications with slightly different language, sequencing, and thresholds. Yet much of the requested information described the same underlying company: revenue, data types, security controls, vendors, incidents, backups, authentication, endpoint protection, and response readiness.

The administrative burden was not always new risk discovery. Often it was translation and re-entry:

• determine whether two differently worded questions were asking for the same fact;
• copy an answer into another form;
• adapt the wording to a market's terminology;
• reconcile answers that drifted across versions; and
• return to the client when the difference was genuinely material.

That work is costly and error-prone, but the answer is not one universal cyber application. Markets should be free to change questions, thresholds, and appetite. The reusable object should be the company's risk context underneath those applications.

With RISK.md, a market-specific application becomes a view or question set layered over a shared record. A new question can add a field or request evidence. An old answer can be refreshed once. A genuinely distinct question remains distinct. The company and broker stop retyping the same facts merely because the form changed.

1.2 Scope and Definition

For this proposal, a risk record is a structured, time-bounded description of an organization, its material exposures, controls, dependencies, incidents, evidence, and known unknowns.

RISK.md is the portable human-readable and machine-parseable representation of that record. It is designed to support preparation, review, comparison, and controlled exchange. It is not itself an underwriting decision, a policy, a submission, a warranty, a claims notice, or proof that a control works.

2. Why Markdown, and Why Now

Markdown has become a practical interface for persistent AI context.

Google Labs' DESIGN.md combines machine-readable YAML frontmatter with human-readable design rationale. Exact tokens tell an agent what the values are; prose explains why they exist and how to apply them. Google describes the result as a persistent, structured understanding of a design system that can travel across tools.

The same pattern now appears across leading agent systems:

• OpenAI's Codex uses AGENTS.md to carry repository instructions, structure, commands, and validation expectations.
• Anthropic uses CLAUDE.md for persistent project context loaded across sessions.
• GitHub Copilot supports repository, path-specific, and agent instruction files, including AGENTS.md, CLAUDE.md, and Markdown files with YAML frontmatter.
• The llms.txt proposal uses Markdown to give language models a concise, structured map of a website while remaining readable by humans and conventional parsers.

These examples do not validate RISK.md as an insurance standard. They validate the underlying interface pattern: a named Markdown file can be a durable, portable layer of context between people, agents, tools, and sessions.

2.1 The DESIGN.md Precedent

DESIGN.md is useful because it does more than serialize colors and type scales. It preserves intent. It also creates a stable contract around the file:

• a canonical location and name;
• structured frontmatter for exact values;
• prose for rationale and exceptions;
• a specification for expected sections;
• linting and validation;
• version control and readable diffs; and
• import and export across tools.

RISK.md applies the same philosophy to a more sensitive domain. The risk record needs exact fields and human explanation, but also provenance, permissions, uncertainty, evidence references, effective dates, and accountable review.

2.2 The Value of a Plain File

Markdown is valuable here because it is:

• Portable: not trapped inside one broker, carrier, data room, or software vendor.
• Human readable: a risk manager, broker, underwriter, or claims professional can inspect it directly.
• Agent readable: models can navigate headings, fields, lists, tables, and linked evidence without a bespoke interface.
• Machine parseable: YAML frontmatter and stable sections can be validated with ordinary software.
• Versionable: Git-style diffs can show which facts, controls, claims, and permissions changed.
• Composable: class-specific and market-specific modules can extend a small common core.
• Tool independent: a better system can import or export the file without owning the standard.

The important claim is not that Markdown is a database. It is that Markdown can be the canonical context packet: the smallest inspectable object that tells a human or agent what is known, what is unknown, what changed, and where the supporting evidence lives.

3. The Proposed Record

A first useful RISK.md should combine normalized frontmatter with stable Markdown sections.

---
schema_version: risk-md-v0
record_id: acme-2026-q3
company_legal_name: Acme Systems Inc.
effective_at: 2026-07-07
risk_context_state: EVIDENCE_LINKED
attestation_status: PARTIALLY_REVIEWED
overall_confidence: MEDIUM
evidence_index: RISK_EVIDENCE_INDEX.md
question_sets: [core, cyber-liability, market-a-2026]
known_unknowns: "Supplier concentration and open claim reserve require review."
permitted_use: "Internal review and named underwriting pilot only."
---

The body should include, at minimum:

1. executive risk summary;
2. legal entities, ownership, governance, and jurisdictions;
3. operations, revenue, products, customers, and material dependencies;
4. enterprise risk register and decision thresholds;
5. controls, policies, tests, and evidence;
6. cyber, technology, data, AI, and automation risk;
7. contracts, vendors, and third-party obligations;
8. financial, capital, and insurance context;
9. claims, incidents, disputes, circumstances, and loss history;
10. missing information and expected reviewer questions;
11. review notes, sharing boundaries, escalation, and attestation; and
12. instructions for authorized agents using the record.

3.1 One Core, Many Question Sets

The record should separate reusable facts from the questions used to elicit or evaluate them.

A market can maintain its own question set, definitions, thresholds, and evidence requirements. The question set maps back to the canonical record where possible and creates a new field where the distinction is real.

This architecture preserves competition. Markets can ask better questions and reach different conclusions without forcing the company to restate identical facts in every application.

3.2 Evidence as the Spine

Each material statement should be traceable to an evidence item, an authorized attestation, or an explicit uncertainty label. An evidence reference should identify the source, owner, effective period, sensitivity, facts supported, freshness, and limitations.

The file should not absorb every underlying document. It should point to governed evidence while avoiding credentials, raw secrets, unnecessary personal information, full confidential contracts, and sensitive security details.

3.3 Facts, Analysis, and Decisions

The format should separate three layers:

• Facts: what the company and its evidence establish.
• Analysis: how a reviewer or model interprets those facts for a defined purpose.
• Decisions: appetite, pricing, wording, capital, claims, compliance, or other accountable conclusions.

RISK.md is primarily the first layer. It may preserve attributed analysis, but it should not make one party's conclusion appear to be an objective property of the company.

4. Alignment with Lloyd's Market Operational Efficiency

The proposal is directly aligned with the operational problem described for Lloyd's Lab Cohort 17: fragmented data, complex workflows, repeated ingestion, and the need to do more with less without weakening underwriting discipline.

It is not a complete answer to every market gap. It is a shared context layer that could make several higher-value tools easier to build and adopt.

4.1 Shared Ingestion, Vetting, and Clearance

A permissioned risk record could let a company or coverholder assemble core evidence once, then let each authorized reviewer verify freshness, provenance, and scope. Market participants could add private analysis without forking the underlying facts.

The potential result is less re-keying, faster triage, and clearer disagreement. Two underwriters may reach different conclusions, but they can see whether they began from the same evidence.

RISK.md would not make a self-reported fact authoritative. Shared vetting still needs trusted data providers, regulated checks, clear liability, and rules for reliance. The contribution is to stop moving the same context through incompatible forms.

4.2 Portfolio Steering and Capital Allocation

Comparable does not mean identical. Stable fields, identifiers, and change histories can make it easier to aggregate exposures, detect drift, trace the source of risk through distribution, and distinguish a portfolio change from a data-quality change.

The record should support portfolio analysis without pretending a common schema creates common appetite. RISK.md is the input layer, not the steering model.

4.3 Claims and Early-Loss Signals

Structured, dated observations across a claim lifecycle can give early-loss models better inputs and make interventions auditable. Status changes, reserve movements, expert evidence, injuries, litigation milestones, and missing facts can be represented consistently without asking the file to predict severity itself.

The predictive model remains a separate product. RISK.md improves the evidence it is authorized to consume and the audit trail behind its output.

4.4 The Go-to-Market Wedge

A credible first pilot is not “standardize all risk.” It is to choose one repetitive workflow where the same facts are already being translated between forms.

Cyber liability is a strong candidate:

1. select a bounded set of applications used by participating markets;
2. map semantically equivalent and genuinely distinct questions;
3. create a minimal cyber risk module and evidence index;
4. generate each existing application as a purpose-specific view;
5. measure re-keying time, unanswered questions, answer drift, stale evidence, and underwriter follow-ups; and
6. preserve every market's ability to ask additional questions and apply its own appetite.

The same method could later be tested for coverholder onboarding, financial-crime evidence, claims bordereaux, or another high-friction market workflow.

5. What Must Remain Unstandardized

Underwriting discipline depends on plural judgment. Appetite, pricing, wording, capital strategy, fraud detection, sanctions decisions, reserving, claims handling, and regulatory conclusions should not collapse into a public template.

The standard should govern representation, provenance, uncertainty, change, and permission—not compel reliance.

A receiving party must still decide:

• which attestations it accepts;
• which evidence it must verify independently;
• which facts are material to its own appetite;
• what additional questions a class or jurisdiction requires; and
• which decisions require licensed, legal, actuarial, claims, executive, or regulatory authority.

The first implementation should resist a giant ontology. A thin common core with explicit extensions is more adoptable than a schema that attempts to encode every class of business before anyone has used it.

6. Technical and Tooling Direction

The concept is designed around simple, inspectable components:

• Format: Markdown with normalized YAML frontmatter and stable section headings.
• Schema: machine validation of metadata, evidence references, states, and required sections.
• Question registry: mappings between canonical facts and market-specific wording.
• Lint: structural errors, missing sources, stale evidence, conflicting answers, and unsafe disclosures.
• Diff: material changes in exposures, controls, incidents, evidence, permissions, and attestations.
• Export: purpose-limited applications, claims, board, cyber, AI-governance, and diligence views.
• Audit: who generated, reviewed, changed, approved, or shared each version.
• Extensions: namespaced modules for classes, jurisdictions, and market workflows.

The file is not the database, the evidence vault, or the permission system. Software may manage access, evidence, workflows, and audit state while importing or exporting a portable RISK.md. The format should remain usable without requiring one vendor or product.

7. Research Plan and Decision Gates

Immediate:

• Map a sample of cyber liability applications into shared facts, equivalent questions, and genuine deltas.
• Test the minimum record against synthetic and permissioned company cases.
• Ask companies, brokers, underwriters, claims specialists, compliance reviewers, and risk leaders which fields they actually reuse.
• Test agent accuracy when reading, updating, comparing, and exporting the record.
• Measure time to triage, duplicate evidence requests, stale-field detection, answer drift, reviewer agreement on facts, and handoff quality.

Build gate:

• Build broader tooling only after reviewers use the same record in a real, bounded workflow.
• Add fields only when they improve a defined decision or evidence handoff.
• Add automation only where outputs remain attributable, reviewable, and permissioned.

Open-standard gate:

• The white paper and Markdown mirror are the public review surface today.
• Publish a standalone specification, examples, validator, and governance process only after external reviewers validate the object, name, and minimum schema.
• Prefer compatibility with existing market data standards over a competing vocabulary where those standards already work.

Stop conditions:

• Existing market standards already provide an adequate portable record.
• Reviewers do not reuse the record across a real workflow.
• The question-mapping layer creates as much work as it removes.
• Maintenance cost exceeds the duplication it removes.
• The artifact creates false confidence, encourages oversharing, or becomes stale faster than it can be governed.

Success is not the existence of another standard. It is evidence that a shared, company-owned risk context packet improves a real decision while preserving professional judgment.

8. Project Scope and Maturity

RISK.md is a public research concept published on clarainsure.com. It is not an adopted insurance standard, a completed software product, or a claim that market participants should rely on self-reported Markdown.

The current artifacts are:

• this white paper;
• a public Markdown mirror;
• a downloadable PDF; and
• a proposed record structure for testing.

A standalone specification repository, reference examples, validator, question registry, and governance process are future decision-gated work. The concept should earn those layers through a bounded market pilot.

9. Conclusion

Insurance markets do not need every participant to reach the same answer. They need a better way to preserve the facts, evidence, uncertainty, permissions, questions, and changes that each answer depends on.

RISK.md tests one proposition: whether a simple, portable, inspectable context packet can reduce repeated ingestion, improve handoffs, support better portfolio and claims analysis, and give companies more control over their own risk information.

The idea is deliberately plain. Put the durable context in one named Markdown file. Let humans inspect it. Let agents work with it. Let software validate and translate it. Let markets layer their own questions and private judgment on top.

If the market does not reuse the record, the proposal should stop. If a bounded pilot shows that the same evidence can travel further without losing provenance or context, the next step is to formalize the smallest useful schema and build the tools around it.

References and Further Reading

• Google Labs: Stitch's DESIGN.md format is now open-source
• Google Labs: DESIGN.md draft specification and tooling
• OpenAI: Codex and AGENTS.md
• Anthropic: How Claude remembers projects with CLAUDE.md
• GitHub: Adding custom instructions for Copilot CLI
• llms.txt: A proposal for LLM-readable web context
• Sønr: Lloyd's Lab Cohort 17 themes

RISK.md — A Shared Language for Underwriting

Version 0.2 · July 7, 2026 · Revised concept draft for market review.

Public Markdown: clarainsure.com/research/risk-md.md