Plugin Development: VocabularyProvider Prompts¶

This file collects six end-to-end prompts for building a new VocabularyProviderPlugin, the 11th plugin type added in v1.2.1. Providers broker cross-project entity resolution against the 175 packaged YAML mappings under src/fcc/data/objectmodel/. Each prompt pins personas, R.I.S.C.E.A.R. slots, and the deliverable shape.

1. Scope the Provider¶

When to use. At the start of a new vocabulary-provider project before any code is written.

Personas/subsystems invoked. dal, cw. R.I.S.C.E.A.R. slot: Role + Input.

You are the Data Analyst Lead (dal). Content Writer (cw) reviews.

TASK: Produce a scoping document for a new VocabularyProviderPlugin
named "esg_taxonomy_provider" that targets the energy vertical.

Include:
1. Source vocabularies (at least 2 standards).
2. Intended subset of the 175 packaged YAML files under
   src/fcc/data/objectmodel/ it will bridge.
3. Target ecosystems (pick 2 of the 11 registered).
4. Out-of-scope terms (at least 3).

CONSTRAINTS:
- Reference v1.2.1 as the earliest supported FCC version.
- Do not invent new plugin hooks beyond the VocabularyProviderPlugin
  ABC.

Deliverable: a 4-section scoping Markdown, total 250 to 400 words.

Expected output notes. 2 standards, 2 ecosystems, 3 out-of-scope terms, v1.2.1 pinned.

2. Implement the Plugin Skeleton¶

Personas/subsystems invoked. tr, dal. R.I.S.C.E.A.R. slot: Expected Output.

You are the Technical Reviewer (tr). Data Analyst Lead (dal) reviews.

TASK: Produce the Python skeleton for the esg_taxonomy_provider plugin.
File would live at src/fcc/plugins/esg_taxonomy_provider.py.

Requirements:
1. Subclass VocabularyProviderPlugin.
2. Implement load(), get_env_var_hint() if relevant, and
   get_mappings().
3. Use dataclasses, not Pydantic.
4. Use importlib.resources via fcc._resources for any packaged YAML
   lookups.

CONSTRAINTS:
- No sys.path hacks.
- No Path(__file__) chains.
- No invented ABC methods.

Deliverable: a single .py file body of 40 to 80 lines with docstrings.

Expected output notes. Uses fcc._resources, dataclasses only, fewer than 80 lines.

3. Load the Mappings¶

Personas/subsystems invoked. dal, tr. R.I.S.C.E.A.R. slot: Constraints.

You are the Data Analyst Lead (dal). Technical Reviewer (tr) reviews.

TASK: Implement the load() method that reads 3 to 5 YAML files from
src/fcc/data/objectmodel/ and returns a list of VocabularyMapping
frozen dataclass instances.

CONSTRAINTS:
- Validate each mapping against MappingStore protocol.
- Skip malformed entries with a warning, do not crash.
- Respect the existing frozen dataclass fields; do not extend.

Deliverable: the load() implementation plus a 2-bullet list of error
conditions it handles.

Expected output notes. Real YAML file names, non-crashing error path, 2 error conditions documented.

4. Write Tests¶

Personas/subsystems invoked. tr. R.I.S.C.E.A.R. slot: Expected Output.

You are the Technical Reviewer (tr).

TASK: Produce pytest test cases for the esg_taxonomy_provider. File
would live at tests/plugins/test_esg_taxonomy_provider.py.

Required cases:
1. Happy path: load returns >= 5 VocabularyMapping entries.
2. Missing YAML: load emits a warning and returns the remainder.
3. Malformed YAML: load drops the bad entry and logs.
4. Integration: provider registers into NamespaceRegistry without error.

CONSTRAINTS:
- Use pytest fixtures, not unittest.
- Reach >= 98% line and >= 80% branch coverage (v1.3.1+ gate).
- No network calls.

Deliverable: a single pytest file body of 60 to 120 lines.

Expected output notes. pytest style, 4 cases, no network, coverage gate respected.

5. Emit Events and Observability¶

Personas/subsystems invoked. sre, tr. R.I.S.C.E.A.R. slot: Role Collaborators.

You are the Site Reliability Engineer (sre). Technical Reviewer (tr)
reviews.

TASK: Wire the plugin into the EventBus and observability layer.
Produce:
1. Event types emitted (pick from the 81 in
   src/fcc/messaging/events.py).
2. A span created via FccTracer around load().
3. A metric recorded via FccMetrics (pick one of the 7 pre-defined).

CONSTRAINTS:
- Do not invent new event types; if none fits, say so and propose an
  enum addition separately.
- Use the @traced decorator where possible.

Deliverable: a diff-style patch that adds observability calls, plus a
short note on metric cardinality risk.

Expected output notes. Event types real, @traced applied, cardinality note present.

6. Governance and Adoption Checklist¶

Personas/subsystems invoked. ra, dal. R.I.S.C.E.A.R. slot: Role Adoption Checklist.

You are the Risk Analyst (ra). Data Analyst Lead (dal) reviews.

TASK: Produce the governance artifacts needed before shipping the new
vocabulary provider:
1. ConstitutionRegistry entry with 3 tiers.
2. ComplianceRequirement hits (even if empty, justify).
3. A 6-item Role Adoption Checklist covering docs, tests, CI, release
   notes, semver impact, and downstream sister-project verification.

CONSTRAINTS:
- Reference the co-evolution pattern: sister repos rely on the plugin,
  not on runtime imports.
- Semver: adding a provider is MINOR.

Deliverable: Markdown with 3 sections, total 250 to 400 words.

Expected output notes. 3 tiers, 6-item checklist, MINOR semver justified.