RISK.md

A Portable Risk Record

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

Version 0.4 — Open Specification Draft · September 2, 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 Clara's proposal for that shared layer: a portable, human- and machine-readable representation of a living risk record. It can hold the current facts, exposures, controls, incidents, evidence, unknowns, permissions, questions, and material changes relevant to understanding the risk of a business.

Clara is developing RISK.md as a Clara-led open specification and intends to publish reference tooling under an open-source license. The current release is a public proposal. It is not an adopted insurance standard, a certification, or a separate Clara product.

Anyone may generate a draft or self-attested RISK.md. Only a record produced through an expert review that Clara accepts, completes, and records through a Clara account may be described as Clara-reviewed. That designation records provenance; it does not guarantee accuracy, insurer acceptance, coverage, price, placement, or claim payment.

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 risk record; 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.

1.3 Review Provenance

The format must make its review state legible:

• Draft: generated or assembled but not attested by an authorized company representative.
• Self-attested: reviewed or confirmed by an authorized company representative, without implying review by Clara or another professional.
• Clara-reviewed: produced through an expert review that Clara accepted, completed, and recorded through the Clara account, with the reviewed version, date, evidence state, and limitations retained in the account.

Other reviewers may attach their own clearly attributed provenance. No tool, company, or agent may infer a Clara review from format compliance alone. Creating an account or submitting information does not guarantee expert review, acceptance as a client, or insurance placement.

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.

Clara's Orbital Compute pilot found that one line of mission language could change risk behavior, ethics, and strategy in agent-run companies. That is one reason a durable risk record should make objectives, authority, and operating history inspectable: mission statements start to function as governance once agents can act repeatedly without a person approving every step.

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 a portable representation of the risk record: a small 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: clara-risk-md-v0
packet_id: acme-2026-q3
company_legal_name: Acme Systems Inc.
generated_at: 2026-09-02
risk_context_state: COMPANY_REVIEWED
attestation_status: COMPANY_ATTESTED_INTERNAL
review_provenance: SELF_ATTESTED
reviewed_at: 2026-09-02
review_limitations: "No Clara or third-party review."
overall_confidence: MEDIUM
evidence_index_location: RISK_EVIDENCE_INDEX.md
question_sets: [core, cyber-liability, market-a-2026]
known_unknowns_summary: "Supplier concentration requires review."
use_boundary: "Internal planning only; no professional advice."
---

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. Implementation and Release Path

Current:

• use the risk record inside the Clara account and accepted expert-review workflow;
• test the minimum record against synthetic and permissioned company cases;
• keep draft, self-attested, and Clara-reviewed provenance explicit; and
• measure completion, missing-fact resolution, update behavior, reviewer usefulness, and application or placement value.

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-source release path:

• Publish a dedicated specification repository with an explicit open-source license, versioning policy, contribution boundary, examples, schemas, and validator.
• Keep Clara-reviewed provenance dependent on the accepted Clara review workflow, not on access to the open format or tooling.
• Document migrations and compatibility before changing required fields or status meanings.
• Prefer compatibility with existing market data standards over a competing vocabulary where those standards already work.

Adoption boundary:

• Do not call RISK.md an industry standard without independent adoption and evidence.
• Do not create certification, compliance, safety, insurability, or coverage claims from format conformance.
• Narrow or remove fields that do not improve a real review, handoff, or decision.
• Do not expand the specification faster than provenance, privacy, security, and maintenance can be governed.

Success is not publishing another format. It is evidence that a portable, company-controlled risk record improves a real decision while preserving professional judgment.

8. Project Scope and Maturity

RISK.md is a Clara-led open-specification draft published for review on clarainsure.com. Clara intends to release reference tooling under an open-source license, but a dedicated public repository, license, and governance process have not yet been released. RISK.md is not an adopted insurance standard, a certification, a separate Clara product, or a claim that market participants should rely on self-reported Markdown.

The current technical resources are:

• this white paper;
• a public Markdown mirror;
• a downloadable PDF; and
• a public intake contract, JSON schema, and examples used by the current Clara account; and
• an internal reference implementation being prepared for a deliberate public release.

A dedicated specification repository, open-source license, public reference package, versioning policy, and governance process are the next release layer. Their publication must not imply industry adoption or make Clara-reviewed status available outside Clara's accepted review process.

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 representation of a living risk record can reduce repeated ingestion, improve handoffs, 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.

The specification should remain as small as the work permits. Evidence from companies, brokers, insurers, and other reviewers should determine which fields and tools endure. Format conformance must never be mistaken for professional review; provenance is what makes that boundary visible.

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
• Clara: Orbital Compute

RISK.md — A Portable Risk Record

Version 0.4 · September 2, 2026 · Clara-led open specification draft.

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