Architecture Sequence Diagram Prompts¶

This file collects six end-to-end prompts that drive the FCC team through the authoring and critique of Mermaid sequenceDiagram artifacts. Each prompt focuses on one subsystem under src/fcc/ and ties back to a file under docs/architecture/sequence-diagrams/, with personas, R.I.S.C.E.A.R. slots, and deliverable shapes explicitly pinned.

1. Walk the Find-Create-Critique Cycle¶

When to use. A new contributor needs to see how the workflow engine dispatches actions across the FCC phases.

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

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

Open docs/architecture/sequence-diagrams/find-create-critique-cycle.md.

TASK: Produce an improved Mermaid sequenceDiagram that makes the three
FCC phases visible as labelled blocks (par/alt). Actors to include:
- Caller (CLI or test)
- ActionEngine (src/fcc/workflow/action_engine.py)
- SimulationEngine (src/fcc/simulation/)
- EventBus (src/fcc/messaging/bus.py)
- Two personas: one Find-phase, one Critique-phase

CONSTRAINTS:
- Use `rect` blocks to separate Find, Create, Critique.
- Every message must name a real method or event type (81 event types
  exist in src/fcc/messaging/events.py).
- Keep the diagram under 40 lines of Mermaid.

Deliverable: a single sequenceDiagram block plus a 3-row "phase to event
type" mapping table.

Expected output notes. Exactly three rect blocks; messages reference real methods; event type names match events.py.

2. Trace the Event Bus Pub/Sub Flow¶

When to use. Debugging a subscriber that is not receiving events.

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

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

Open docs/architecture/sequence-diagrams/event-bus-pubsub.md.

TASK: Produce a sequenceDiagram that shows:
1. Publisher calls EventBus.publish(event).
2. EventBus applies EventFilter chain.
3. Two subscribers: one synchronous, one backgrounded via
   EventSubscriberPlugin.
4. Failure branch when a subscriber raises — bus must keep delivering.

CONSTRAINTS:
- Reference only methods on EventBus/EventFilter/Subscriber as they
  exist in src/fcc/messaging/.
- Show the thread boundary with a `Note over` annotation.
- Include one alt block for the failure path.

Deliverable: Mermaid sequenceDiagram plus a 5-line "if you see X, check Y"
debugging checklist.

Expected output notes. Alt block for failure; thread boundary noted; debugging checklist references real filter/bus APIs.

3. RAG Persona-Aware Retrieval¶

When to use. Explaining how a RAG query is shaped by the calling persona.

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

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

Open docs/architecture/sequence-diagrams/rag-persona-aware-retrieval.md
and src/fcc/rag/pipeline.py.

TASK: Produce a sequenceDiagram showing:
- User query enters RAGPipeline.query(persona_id, question).
- Pipeline fetches PersonaSpec from PersonaRegistry.
- DocumentChunker (pick 1 of the 6 strategies) is consulted.
- SemanticRetriever performs the search.
- Retrieved chunks are re-ranked using persona dimensions.
- Final answer returned.

CONSTRAINTS:
- Name the chunking strategy explicitly (one of the six in
  src/fcc/rag/chunker.py).
- No invented methods; stick to the pipeline.py public API.

Deliverable: Mermaid sequenceDiagram plus a short paragraph (<=80 words)
explaining how the persona dimensions change ranking.

Expected output notes. One named chunking strategy; paragraph under 80 words; only real pipeline methods used.

4. Compliance Audit Pipeline Timing¶

When to use. Training a compliance officer on how CompliancePipeline emits findings.

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

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

Open docs/architecture/sequence-diagrams/compliance-audit-pipeline.md
and src/fcc/compliance/pipeline.py.

TASK: Produce a sequenceDiagram of a full audit run:
1. CompliancePipeline.run(persona_id) invoked.
2. AIActClassifier returns a RiskCategory.
3. ComplianceAuditor evaluates requirements (reference
   eu_ai_act_requirements.yaml and nist_ai_rmf_mapping.yaml).
4. Findings published on EventBus.
5. ComplianceSubscriber reacts and schedules re-audit if high-risk.

CONSTRAINTS:
- Show the re-audit loop with an opt block.
- Reference the real file names (256+ EU AI Act requirements,
  29 NIST AI RMF subcategories).

Deliverable: sequenceDiagram plus a one-sentence SLA statement for
end-to-end audit latency.

Expected output notes. Opt loop for re-audit; references real YAML files; SLA statement present.

5. Federation Entity Resolution¶

When to use. Tracing a cross-project lookup between two ecosystems.

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

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

Open docs/architecture/sequence-diagrams/federation-entity-resolution.md.

TASK: Produce a sequenceDiagram showing EntityResolver.resolve() across
two of the 11 registered ecosystems (pick FCC and any other). Include:
- NamespaceRegistry lookup.
- VocabularyMapping applied.
- ChangeTracker entry recorded.
- Result returned to caller.

CONSTRAINTS:
- Use the exact class names from src/fcc/federation/.
- Show a miss path (entity not found) with alt block.

Deliverable: Mermaid sequenceDiagram + one bullet naming which of the 11
ecosystems you used.

Expected output notes. Alt block for miss path; uses real classes from federation/; names a real ecosystem.

6. Vocabulary Provider Load on Startup¶

When to use. Understanding how a VocabularyProviderPlugin contributes mappings at boot time.

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.

Open docs/architecture/sequence-diagrams/vocabulary-provider-load.md.

TASK: Produce a sequenceDiagram showing startup load of 2 of the 12
packaged vocabulary providers. Include:
- Plugin discovery.
- VocabularyProviderPlugin.load() invocation.
- MappingStore registration.
- Event emission for successful load (pick the correct event type from
  the 81 in events.py).

CONSTRAINTS:
- Reference only existing providers under src/fcc/plugins/.
- Show one failure branch (malformed YAML) that surfaces a warning.

Deliverable: sequenceDiagram plus a small table of which 175 YAML files
(src/fcc/data/objectmodel/) are touched by each provider in your example.

Expected output notes. References real plugin and event names; failure branch surfaces a warning rather than crashing; table rows cite real YAML file counts.