Skip to content

Chapter 25: Industry Verticals

New in v1.2.0. FCC ships with six industry vertical packs — healthcare, finance, legal, insurance, energy, and government — containing 45 research-grounded personas on the rich schema v2 R.I.S.C.E.A.R. format. This chapter explains how the vertical system works, when to use built-in packs, and how to author your own.

Why verticals?

The 102 core personas describe the generic FCC cycle: research, blueprint, documentation, runbook, governance. Real adopters need domain-specific personas that carry the vocabulary, compliance frameworks, and workflow shapes of a single industry. A SOX compliance auditor looks nothing like a HIPAA compliance officer even though both are "compliance." A claims fraud detection analyst needs different inputs, constraints, and expected outputs than a credit risk analyst.

Verticals answer that need. Each pack is a self-contained YAML file under src/fcc/data/verticals/ that registers personas, scenarios, gates, and compliance frameworks for one industry.

Built-in packs

As of v1.2.0 the framework ships six packs, all auto-discovered from the filesystem by src/fcc/verticals/loader.py:

Domain Personas Headline frameworks
healthcare 11 HIPAA, HL7 FHIR R5, ICD-11, DICOM, IEC 62304
finance 11 SOX, Basel III, MiFID II, IFRS 9, SR 11-7
legal 5 GDPR, CCPA, eDiscovery
insurance 6 ACORD, IFRS 17, Solvency II
energy 6 IEC 61970 CIM, NERC CIP, FERC Order 2222
government 6 DCAT-US 3.0, NIEM 6.0, FedRAMP, NIST 800-53

All six packs use schema v2 (introduced in v1.2.0) with a full nested R.I.S.C.E.A.R. block per persona. The v1 flat riscear_role field is still accepted by the loader for backward compatibility with custom packs.

Schema v2 structure

A vertical persona has the same ten R.I.S.C.E.A.R. components as a core persona:

personas:
  - id: HCO
    name: HIPAA Compliance Officer
    role_title: HIPAA Compliance Officer
    category: healthcare
    compliance_frameworks: [HIPAA, HITECH, FedRAMP]
    risk_category: high            # EU AI Act category
    riscear:
      role: Oversee HIPAA compliance across all PHI-handling systems...
      inputs:
        - Current state of PHI handling pipelines
        - Recent incident reports and breach notifications
        - Audit trail exports from EHR systems
      style: Authoritative, risk-averse, audit-ready
      constraints:
        - Must document every access decision
        - Cannot approve any system without a BAA in place
      expected_output:
        - HIPAA readiness assessment report
        - Breach risk matrix by system
        - Approved exceptions log
      archetype: Regulatory Shepherd
      responsibilities:
        - Maintain the HIPAA risk register
        - Lead breach response coordination
      role_skills:
        - HIPAA Privacy and Security Rules
        - OCR enforcement patterns
        - BAA negotiation
      role_collaborators: [CDA, FIS, CTR, PSE, DPO]
      role_adoption_checklist:
        - Complete HIPAA Privacy Rule certification
        - Establish regular OCR monitoring cadence

The richer schema lets FCC generate distinct model cards, non-boilerplate risk classifications, and a cross-reference matrix that traces collaboration across packs.

Loading a pack

from fcc.verticals.registry import VerticalRegistry

reg = VerticalRegistry.from_builtin()
print(f"Loaded {len(reg)} packs, {sum(len(p.personas) for p in reg.all_packs())} personas")

insurance = reg.get("insurance")
for persona in insurance.personas:
    print(f"  {persona.id}: {persona.name}")

To merge vertical personas into the core registry (so they appear in simulation runs, doc generation, model cards, etc.):

from fcc._resources import get_personas_dir
from fcc.personas.registry import PersonaRegistry

core = PersonaRegistry.from_yaml_directory(get_personas_dir())
merged = reg.merge_into(core)  # returns a new registry, does not mutate

The merge path at src/fcc/verticals/registry.py:merge_into prefers the nested R.I.S.C.E.A.R. block when present and falls back to the legacy boilerplate path for schema v1 packs — so existing community packs keep working.

EU AI Act risk classification

v1.2.0 introduces an explicit mapping layer at src/fcc/data/compliance/vertical_risk_profiles.yaml. Each entry records the risk category for a specific (persona_id, domain) tuple anchored in an Annex III clause:

- persona_id: IUW
  domain: insurance
  risk_category: high
  rationale: >-
    Insurance underwriting determines access to essential services
    including life, health, and property coverage.
  annex_reference: "III.5.c (insurance-related services)"

The AIActClassifier consults this file first, before its generic keyword heuristics. Supplying vertical_domain= at classification time activates the override:

from fcc.compliance.classifier import AIActClassifier

classifier = AIActClassifier()
persona = merged.get("IUW")
classifier.classify_persona(persona, vertical_domain="insurance")
# RiskCategory.HIGH  (explicit override, not the generic heuristic)

Authoring a new pack

  1. Copy src/fcc/data/verticals/healthcare.yaml as a template.
  2. Pick a unique domain string, a readable display_name, and set schema_version: 2.
  3. Enumerate 5–8 personas on the nested R.I.S.C.E.A.R. format. Every persona ID must be unique across core and all vertical packs; run python scripts/check_persona_id_collisions.py before committing.
  4. Declare 3–5 scenarios that orchestrate multiple personas and 5–8 quality gates with threshold values.
  5. List the compliance frameworks the pack operates under.
  6. Add a research note at src/fcc/data/verticals/research/<domain>.research.md with at least 3 cited sources (URL + retrieval date), a persona count justification, and a rejected-candidates table. The research note is the audit trail for why each persona exists.
  7. Add the new (persona_id, domain) entries to src/fcc/data/compliance/vertical_risk_profiles.yaml so the AI Act classifier can anchor their risk category in an Annex III clause.
  8. Re-run the cross-reference generator: python scripts/generate_vertical_cross_references.py --write.
  9. Regenerate model cards: fcc model-card generate --all.
  10. Update tests/test_verticals.py::VERTICAL_EXPECTATIONS with the new counts and run make test.

Common pitfalls

Ghost collaborator IDs. If a persona's role_collaborators list references an ID that doesn't exist, the cross-reference generator will emit edges pointing at nothing. The test suite catches this via test_entry_ids_are_valid_persona_ids, but catch it earlier by running the collision script with the --verify-collaborators flag (planned for v1.3.0).

Forgetting schema_version: 2. The loader will happily accept a v1 pack; you'll only notice later when the merged personas all have the same archetype ("Vertical Specialist") and identical boilerplate skills.

Display-name churn. Renaming an existing pack's display_name propagates into 12+ doc files (sample prompt titles, MkDocs nav, model cards). Pick a stable name on day one.

Over-broad compliance lists. Listing every regulation your industry touches dilutes the signal. Limit each pack to 3–5 headline frameworks that actually shape persona behavior.

See also