Formal risk checklist (Markdown)

Export the risk register as a sign-off-ready Markdown document for a governance team. Below is the code, then its rendered output.

Download the Markdown

Example code

Source: examples/example_risk_checklist.py

"""Export a Formal Risk Review Checklist (Markdown) for a governance team.

A small governed pipeline declares risks (with mitigations and owners) via
``describe(risks=...)`` and ``describe_process``, then ``cf.to_risk_checklist``
renders the risk register as a sign-off-ready Markdown document: conformare fills
in each risk (severity, where it occurs, declared mitigation, owner, governance
concern) and leaves blank columns plus a sign-off block for reviewers to complete.

Run:  python examples/example_risk_checklist.py
Then open output/risk_checklist.md (renders nicely on GitHub or any Markdown viewer).
"""

import os

import narwhals as nw
import pandas as pd

import conformare as cf


def main(out=None):
    out = out or os.path.join(
        os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "output", "risk_checklist.md"
    )
    os.makedirs(os.path.dirname(out), exist_ok=True)

    cf.trackNarwhals()
    cf.describe_process(
        "Nightly UK customer analytics: clean customers and summarise spend by region.",
        risks=cf.risk(
            "compliance.gdpr",
            mitigation="Annual DPIA on file; lawful basis documented",
            owner="data-governance",
        ),
    )

    customers = nw.from_native(
        pd.DataFrame(
            {
                "customer_id": [1, 2, 3, 4],
                "email": ["a@x.com", "b@x.com", "c@x.com", "d@x.com"],
                "region": ["London", "Leeds", "London", "Bristol"],
                "age": [34, 17, 41, 29],
                "spend": [120.0, 0.0, 80.0, 200.0],
            }
        )
    )

    with cf.describe(
        "Clean customers",
        purpose="Keep UK adults only",
        risks=cf.risk(
            "privacy.pii_exposure",
            "compliance.gdpr",
            note="email retained through the pipeline",
            mitigation="Mask email before any export",
            owner="data-platform",
        ),
    ):
        adults = customers.filter(nw.col("age") >= 18)

    with cf.describe(
        "Spend by region",
        purpose="Average spend per region",
        risks=cf.risk("fairness.proxy_variable", note="region may proxy for a protected attribute"),
    ):
        # no mitigation declared -> this risk ranks as High governance concern
        adults.group_by("region").agg(nw.col("spend").mean())

    md = cf.to_risk_checklist(
        out,
        process="Nightly UK customer analytics",
        reviewers=["", ""],  # two blank sign-off rows for the review board
    )
    cf.restore()
    print(f"wrote {out} ({len(md):,} chars, {md.count(chr(10)) + 1} lines)")
    return md


if __name__ == "__main__":
    main()

The rendered checklist

The document below is the actual output of cf.to_risk_checklist(...) from the code above — exactly what a governance team would receive to review, comment on and sign.

Formal Risk Review Checklist

Process: Nightly UK customer analytics
Description: Nightly UK customer analytics: clean customers and summarise spend by region.
Generated: 2026-06-24
Document status: Draft — pending governance review

This checklist is generated by conformare from the pipeline’s risk register. The pre-filled columns describe each declared risk; the Review decision, Reviewer comments and Action & target date columns are for the governance team to complete, followed by sign-off below.

Summary

• Total risks: 3
• Mitigated: 2 (with a named owner: 2)
• Unmitigated: 1
• Governance concern: 1 high, 0 medium, 2 low

Concern ranking: a risk with a declared, owned mitigation is Low; a mitigation without a named owner is Medium; no mitigation is High.

Risk register

#	Risk ID	Category	Risk	Severity	Affected steps	Declared mitigation	Mitigation owner	Concern	Review decision	Reviewer comments	Action & target date
1	fairness.proxy_variable	Bias / Fairness	Proxy variable	Medium	Spend by region	—	—	High	[ ] Accept [ ] Mitigate [ ] Reject
2	privacy.pii_exposure	Privacy	PII exposure	High	Clean customers	Mask email before any export	data-platform	Low	[ ] Accept [ ] Mitigate [ ] Reject
3	compliance.gdpr	Compliance	GDPR processing	High	Clean customers, Entire process	Mask email before any export; Annual DPIA on file; lawful basis documented	data-platform, data-governance	Low	[ ] Accept [ ] Mitigate [ ] Reject

Risk details

1. Proxy variable (fairness.proxy_variable)

Category: Bias / Fairness · Severity: Medium · Concern: High

A feature acts as a proxy for a protected attribute.

• Affected steps: Spend by region
• Declared mitigation: —
• Mitigation owner: —
• Notes from the pipeline:
  • Spend by region: region may proxy for a protected attribute

Reviewer decision: [ ] Accept [ ] Mitigate further [ ] Reject
Comments: _______________
Responsible owner: _____ **Target date:** _____

2. PII exposure (privacy.pii_exposure)

Category: Privacy · Severity: High · Concern: Low

Personally identifiable information may be exposed or retained beyond need.

• Affected steps: Clean customers
• Declared mitigation: Mask email before any export
• Mitigation owner: data-platform
• Notes from the pipeline:
  • Clean customers: email retained through the pipeline

Reviewer decision: [ ] Accept [ ] Mitigate further [ ] Reject
Comments: _______________
Responsible owner: _____ **Target date:** _____

3. GDPR processing (compliance.gdpr)

Category: Compliance · Severity: High · Concern: Low

Processing falls under GDPR; lawful basis and minimisation apply.

• Affected steps: Clean customers, Entire process
• Declared mitigation: Mask email before any export; Annual DPIA on file; lawful basis documented
• Mitigation owner: data-platform, data-governance
• Notes from the pipeline:
  • Clean customers: email retained through the pipeline

Reviewer decision: [ ] Accept [ ] Mitigate further [ ] Reject
Comments: _______________
Responsible owner: _____ **Target date:** _____

Governance review sign-off

Reviewer (name)	Role	Overall decision	Signature	Date

Overall comments:

---

---

---

Generated by conformare on 2026-06-24. Pre-filled fields reflect the pipeline as authored; reviewer entries above are the system of record for this review.