Suggestion YAML Reference

Field-level specification for Suggestion YAML definitions (suggestions/sug_*.yaml).

Suggestions are the what of the Sense 19 chain. A human-readable recommendation that lives free-floating from any particular execution. Paired (optionally) with one or more Interventions which carry the how.

File Convention

• Location: afs/suggestions/sug_*.yaml
• suggestion_id must match the filename stem (e.g. sug_foo.yaml requires suggestion_id: sug_foo)
• Validator: python3 scripts/suggestioncheck.py
• Contract: contracts/suggestion_contract.v1.json (JSON Schema)
• Storage tier: A-tier — lives on the suggestions orphan branch, shared across every scenario

Top-Level Fields

Field	Type	Required	Description
suggestion_id	string	Yes	Must match filename stem. Pattern: ^sug_[a-z0-9_]+$
version	string	Yes	Semver-shaped. Increment on substantive content change
category	string	Yes	One of the enum below
target	string	No	Free-form pointer at the artifact this is about (e.g. signal_revenue_leakage). Structural binding lives on the Intervention; this field is for discoverability
description	i18n mapping	Yes	At least en required. Multi-language descriptions OK
priority	string	Yes	One of: low, medium, high, critical
status	string	Yes	One of: proposed, accepted, rejected, superseded
origin	string	No	Reference to what triggered this suggestion (verdict_id, smebit_id, observation_id, or human for free-authored). Recorded for audit, not enforced as FK
proposer	mapping	No	See Proposer
interventions	list of strings	No	List of int_* IDs that realise this suggestion. Forward-pointers — the Intervention also carries suggestion_id in reverse
superseded_by	string	Conditional	When status: superseded, the sug_* ID that replaced this one
modified_at	string	No	ISO 8601 timestamp

Valid Categories

The category enum mirrors the verdict root-cause categories so suggestions can compose with them directly:

Value	When to use
threshold	Tune a numeric parameter — signal threshold, validity cutoff
process	Change a workflow step (how data is collected, who reviews what)
system	A system / integration change (extractor, mapping, channel config)
data_quality	Improve a known data-quality gap (validation, dedup, enrichment)
structural	Change to schema, hierarchy, or organisational structure
behavioral	Address a human behaviour pattern (workaround, shortcut, missed step)
external	Action requiring an external party (supplier, regulator, partner)

Status Lifecycle

Status	Meaning
proposed	Authored, awaiting decision
accepted	Decided to apply. Doesn’t auto-merge — the human merges the interventions into main themselves
rejected	Decided not to apply. The description should explain why (audit trail)
superseded	Replaced by another Suggestion. superseded_by names the replacement

Proposer

Field	Type	Required	Description
name	string	No	Person or team name
role	string	No	Their role (analyst, cfo, domain-expert, …)
date	string	No	ISO date the suggestion was first proposed

Example

suggestion_id: sug_tighten_revenue_leakage
version: '1'
category: threshold
target: signal_revenue_leakage
description:
  en: |
    Tighten the revenue-leakage threshold from 10 CHF to 5 CHF.
    Smaller leakages still represent real revenue loss; the OPALE
    feed has enough resolution that the noise floor sits below 5.
priority: high
status: proposed
origin: verdict_billing_workflow_gap
proposer:
  name: mig
  role: analyst
  date: 2026-05-22
interventions:
  - int_lower_revenue_threshold
modified_at: 2026-05-22T08:00:00Z

After Authoring

python3 scripts/suggestioncheck.py    # validate against contract
jin make                              # bake into _<tenant>.suggestion_registry
jin afs push                          # sync to the `suggestions` orphan branch

See also

• Simulation guide — the full chain end-to-end.
• Intervention YAML reference — the paired how shape.
• The Simulation — architecture — structural framing.