Architecture Class Diagram Prompts¶

This file collects six end-to-end prompts that teach learners how to drive the FCC agent team through the creation and review of Mermaid classDiagram artifacts for concrete src/fcc/ subsystems. Each prompt targets a specific diagram under docs/architecture/class-diagrams/ and pins the personas, the R.I.S.C.E.A.R. slot the work lands in, and the exact deliverable shape expected back.

1. Critique the Plugin Hierarchy¶

When to use. You are onboarding a plugin author and want the team to review the existing hierarchy before extension.

Personas/subsystems invoked. tr (technical reviewer), dal (data analyst lead). R.I.S.C.E.A.R. slot: Expected Output + Constraints.

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

Open the diagram at docs/architecture/class-diagrams/plugin-hierarchy.md.

TASK: Produce a classDiagram critique that:
1. Lists every abstract base class shown and the concrete subclasses it has in src/fcc/plugins/.
2. Flags any missing plugin type (FCC currently has 11: personas, engines,
   templates, scorers, validators, providers, governance, scenarios,
   workflows, subscribers, vocabulary_providers).
3. Identifies which ABC methods are optional vs required, and whether the
   diagram shows that distinction.

CONSTRAINTS:
- Do not invent new APIs; reference only classes that exist in src/fcc/plugins/.
- Keep findings under 400 words.
- Output must be a Markdown report with a "Findings" table and a corrected
  Mermaid classDiagram snippet.

Deliverable shape:
| Finding # | Class/method | Issue | Recommended fix |
Plus a revised Mermaid block ready to paste back into the doc.

Expected output notes. Expect 5 to 8 findings, a corrected classDiagram block with all 11 plugin types, and no invented class names.

2. Generate a PersonaSpec Class Diagram¶

When to use. A new contributor is ramping up and needs a class-level view of the persona models.

Personas/subsystems invoked. dal, cw (content writer). R.I.S.C.E.A.R. slot: Expected Output.

You are the Data Analyst Lead (dal) with Content Writer (cw) as reviewer.

TASK: From src/fcc/personas/models.py and dimensions.py, produce a Mermaid
classDiagram that:
- Shows RISCEARSpec, PersonaSpec, DimensionAttribute, PersonaDimension,
  PersonaDimensionProfile, and DimensionRegistry.
- Annotates each attribute with its type (str, list[str], dict, etc.).
- Uses composition arrows where PersonaSpec holds a RISCEARSpec.
- Includes a two-sentence caption naming the file path(s) read.

CONSTRAINTS:
- No Pydantic references (the codebase uses dataclasses).
- No attributes not actually present in the source.
- Target audience: intermediate Python developer new to FCC.

Deliverable: a single Markdown file body with a `classDiagram` block and
the caption. Must parse as valid Mermaid v10.

Expected output notes. Expect roughly 6 class boxes, dataclass-only types, a valid Mermaid classDiagram block.

3. Extend the Collaboration Engine Diagram¶

When to use. Planning a change to CollaborationEngine and need to see the ripple before writing code.

Personas/subsystems invoked. tr, sre (site reliability engineer). R.I.S.C.E.A.R. slot: Responsibilities + Role Collaborators.

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

Read docs/architecture/class-diagrams/collaboration-engine.md and
src/fcc/collaboration/.

TASK: Propose an extension that adds a `TurnPolicy` abstraction enforcing
approval-gate ordering. Produce:
1. A revised Mermaid classDiagram showing TurnPolicy, its two concrete
   subclasses (StrictOrdering, RelaxedOrdering), and its relationship to
   CollaborationEngine.
2. A table of impacts on the 11 frozen dataclasses in collaboration/models.py.
3. A list of tests that would need to be added under tests/collaboration/.

CONSTRAINTS:
- Do not alter existing frozen dataclass field names.
- Explicitly mark new classes with <<new>> stereotypes in Mermaid.

Deliverable: Mermaid block, impact table, test list.

Expected output notes. Classes must remain frozen; new boxes clearly stereotyped; test list cites real test directories.

4. Contrast Object Model vs Federated¶

When to use. You need to teach the distinction between single-project and federated object-model views.

Personas/subsystems invoked. dal, ra (risk analyst). R.I.S.C.E.A.R. slot: Style + Expected Output.

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

Open docs/architecture/class-diagrams/object-model-vs-federated.md.

TASK: Produce a side-by-side classDiagram comparison that teaches:
- ModelFacade vs FederatedKnowledgeGraph differences.
- VocabularyMapping's role in both views.
- Where CrossProjectAssessment sits.

Style: Treat the reader as a new architect. Use inline Mermaid `note` blocks
to explain each class in 1 sentence. Produce two separate classDiagram blocks
labelled "Individual" and "Federated".

CONSTRAINTS:
- Reference only symbols exported from src/fcc/objectmodel/ and
  src/fcc/federation/.
- Explain at least one risk trade-off per side.

Deliverable: Two Mermaid blocks + a three-bullet trade-off summary.

Expected output notes. Two valid Mermaid blocks, correct module names, at least one governance trade-off per side.

5. Knowledge Graph Type Lattice¶

When to use. Teaching 9 node types and 9 edge types in the KG.

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

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

Open src/fcc/knowledge/graph.py and docs/architecture/class-diagrams/
kg-vs-federated-kg.md.

TASK: Produce a Mermaid classDiagram showing:
- KnowledgeGraph class with all 9 node types and 9 edge types as
  nested enums or class stereotypes.
- FederatedKnowledgeGraph extending/using KnowledgeGraph.
- Serializer classes (OWL, RDF, SKOS, JSON-LD) linked to KnowledgeGraph.

CONSTRAINTS:
- Node and edge types must match the exact names in graph.py.
- No invented serializers beyond the four shipped.

Deliverable: One `classDiagram` block plus a 3-row table mapping each
serializer to its primary file extension.

Expected output notes. Exactly 9 node and 9 edge types named correctly; table lists .owl, .ttl, .skos, .jsonld.

6. Author a New Search Subsystem Diagram¶

When to use. No class diagram exists yet for src/fcc/search/; the team should author one.

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

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

No diagram currently exists at docs/architecture/class-diagrams/search-index.md.
Author one.

TASK: From src/fcc/search/ produce a classDiagram that covers:
- EmbeddingProvider Protocol
- MockEmbeddingProvider (384-dim) concrete class
- SearchIndex (pluggable backend)
- PersonaSearchIndex, ActionSearchIndex

Include:
- A Protocol arrow from SearchIndex to EmbeddingProvider (uses).
- Attribute types from the actual source.
- A 3-bullet Role Adoption Checklist at the end telling a new contributor
  what to do to add a third specialized index.

CONSTRAINTS:
- Do not invent indexes beyond the two shipped.
- Must be a new Markdown file ready to land at
  docs/architecture/class-diagrams/search-index.md.

Deliverable: complete Markdown file with front matter, Mermaid block,
checklist.

Expected output notes. New Markdown file, valid front matter, Mermaid block references only real classes, 3-item adoption checklist.