Author Role Assistant Evidence

Add Evidence to a Role Assistant package so governed asks, gates, and expected
behaviors can be imported for review — without storing vendor schemas as
Evidence. Evidence is the business-significant layer that shapes how work
continues; it is not current Reality and not Knowledge answers.

Why this matters: You do not encode the process as a workflow graph. You
author the asks, gates, and expected behaviors that make governed
continuation testable. Package upload imports candidates; an authorized human
reviews and promotes them before the Runtime may rely on them.

Certify is not Activate. Certified Evidence may be reused later. Certification does not apply a suggestion to live work. Uncertified AI suggestions must not apply. Vendor substance belongs in Knowledge, not Evidence.

Prerequisites

• Role Assistant package on disk (Manage Role Assistant packages)
• Understanding that Evidence is not current Reality and not filled answers
• Concept background: Evidence Fabrix
• Optional: plan how you will prove asks after promote — Test Role Assistants

Where it lives

Evidence holds question templates, confidence gates, and business-significant conditions. Filled answers and vendor substance belong in Knowledge (Author Role Assistant Knowledge).

Ownership reminder:

Vendor operation or schema fact = Knowledge
Vendor mapping and joins         = CIP
Canonical enterprise meaning     = COM
Current authorized business fact = Reality
Business-significant condition   = Evidence

How to set

1. Read live Evidence metadata (allowed kinds, aspects, resources, capabilities) before inventing fields. Reuse existing patterns. Do not author duplicates or rows that exclude each other for the same situation — resolve those conflicts during review so the process stays completable.

2. Author rows under package evidence/ with specific when conditions and actionable expected behavior. Align kind, aspect, and resource type with what the platform supports. Each row must leave a path for work to finish (ask, wait, or continue) — not a dead-end that contradicts another certified gate.

   Kind defaults are not value generated. Selecting an Evidence Kind may show expected contribution vocabulary for that kind. That is catalog guidance — it does not create a realized contribution value until governed outcomes attribute one. Do not invent free-form vendor field names as contribution types.

Illustrative row shape (fields vary by deployment — validate against Evidence contracts):

kind: missing_information
aspect: connected-system-authoring
resourceType: customer
when: "Primary customer identity is ambiguous across more than one candidate record"
expectedBehavior: "Ask a constrained clarification before create or update; do not invent the primary key"

Evidence does not decide create vs update. Author Evidence as asks, gates, and expected behavior for a task — never as "check if the record exists, then update; otherwise create" branching logic. Whether the requested record already exists is Reality, determined by the platform's own Reality check, not by conditions you write into Evidence. Evidence's job is to state what information is needed and what a good outcome looks like; it does not re-implement the existence check.

3. Keep boundaries

Questions and gates → Evidence
Filled answers / substance → Knowledge
Vendor mappings / joins → CIP / COM (not Evidence)
Current facts → Reality

4. Import with the package:

aifabrix validate <roleKey>
aifabrix upload <roleKey> --env dev

Upload discovers evidence/, resolves stable identity, and imports new or
changed candidate rows. It reports row identities, partial results, and pending
lifecycle actions. Required import failures exit non-zero. Upload does not
certify or activate Evidence, and a retry must not overwrite, demote, or
reactivate current server records by accident.

5. Review and promote in Assistants → Evidence with an authorized human
   actor. Confirm scope, provenance, conflicts, and the path to completion before
   promotion. File approval metadata and --force do not grant this authority.

6. Extend a missing ask: add Evidence for the new closed key, document the key in your question catalog, store answers as Knowledge — do not invent free-text question surfaces in product code.

7. Standalone path (optional): Builder aifabrix evidence list/get/insert/load when you need CRUD outside package import.

aifabrix evidence list --role-key sales-representative
aifabrix evidence load ./evidence-batch.json --dry-run

Defaults and examples

Good (shape):

• when: Customer identity confidence is below policy threshold for ownership change.
• expectedBehavior: Pause the change, request secondary verification, require human approval.

Bad:

• when: When needed.
• expectedBehavior: Handle correctly.

Ambiguity handling: flag uncertainty, ask a focused human question, keep candidate Evidence inactive until reviewed.

Validate

If upload fails on Evidence, fix or remove invalid rows under evidence/ and re-upload. Do not bypass required Evidence failures.

Common mistakes

Limits

• Exact Evidence JSON fields follow dataplane Evidence Fabrix contracts and your Builder version.
• Review and promotion controls can vary by deployment. Upload never grants
  promotion authority; confirm the target environment's Evidence review state.
• Category B enterprise capability language is synthesized from Connected Systems, not authored as a predetermined Builder catalogue.
• This page does not create Role Assistants from scratch — assistants remain platform-generated.

Related

• Evidence Fabrix
• Manage Role Assistant packages
• Author Role Assistant Knowledge
• Test Role Assistants
• CLI reference