L1 recommendations → L2 user-scenario candidates

From an agent’s l1-scenario-mapping/v1, write one smart-kg L2 user-scenario candidate per L1 recommendation, joined to a persona and a business-process by smart-kg L2’s existing edges. Reuses the guide’s own personas and processes, then smart-base’s generic DAK.Persona.*; otherwise a glossary candidate or could-not-determine, each with a WARNING. Never invents a process.

Skills it satisfies

A skill states the capability; this Tool is one way to exercise it. Each skill’s declared input and output contract follows, where it has one.

recommendation-scenarios

Join each L1 recommendation to who acts on it and during which business process: one smart-kg L2 user-scenario candidate per recommendation, from the agent’s mapping, reusing the target guide’s personas and processes first, then smart-base’s generic personas, and never inventing a process. Step 2 of recommendation-extraction; the l1-recommendation-scenarios Tool satisfies it.

Source: smart-base/L1/skills/smart-l1/recommendation-scenarios.md.

input [1..1]output [1..1]recommendation-scenarios«skill»recommendation-scenariosinput : RecommendationScenariosInput [1..1]output : RecommendationScenariosOutput [1..1]RecommendationScenariosInput«json-schema»RecommendationScenariosInputl1 : string [1..1]vocabulary : string [1..1]generic : string [0..1]mapping : string [1..1]out : string [0..1]RecommendationScenariosOutput«json-schema»RecommendationScenariosOutputgraph : string [1..1]warnings : string [0..1]runContext : string [1..1]

input — smart-base/L1/schemas/skills/recommendation-scenarios/input.schema.json

fieldtyperequireddescription
l1stringyesThe recommendations: recommendation-candidates’ L1 3.0 graph, or an authored L1 YAML.
vocabularystringyesThe target guide’s personas and processes (l1-scenario-vocabulary/v1).
genericstringsmart-base’s generic personas, the second rung of reuse.
mappingstringyesThe agent’s persona, process, act, outcome and domain per recommendation, each with a source and a basis.
outstringWhere the outputs are written.

output — smart-base/L1/schemas/skills/recommendation-scenarios/output.schema.json

fieldtyperequireddescription
graphstringyesscenario-candidates.l2.json.
warningsstringscenario-warnings.md: processes not determined, personas that are glossary candidates.
runContextstringyesrun-context.json, cat-harness folio-run-context/v1.

Inputs and outputs

Each port names a shared type by IRI, so two Tools for one skill can be checked for interchangeability.

porttyperequireddescriptionconstraint
inl1RepoPathyesThe recommendations: l1-recommendation-candidates’ L1 3.0 graph, or an authored L1 YAML.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
invocabularyRepoPathyesThe target guide’s personas and processes (l1-scenario-vocabulary/v1).string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
ingenericRepoPathsmart-base’s generic personas (second rung).string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
inmappingRepoPathyesThe agent’s persona, process, act, outcome and domain per recommendation, each with a source and a basis.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
outgraphRepoPathscenario-candidates.l2.json.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
outwarningsRepoPathscenario-warnings.md — processes not determined, personas that are glossary candidates.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
outrunContextRepoPathrun-context.json, cat-harness folio-run-context/v1.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.

Processes and tasks

Steps this Tool can carry out, because each names a skill it satisfies:

processsteplanevia skill
Classify and code contentRun reuse-first lookup and record candidatesAuthoring agentrecommendation-scenarios

How it is deployed and reached

  • Command line. From the repository root: bun run smart-base/scripts/l1-recommendation-scenarios.ts --l1 <l1.json|yaml> --vocabulary <guide.json> [--generic <generic.json>] --mapping <mapping.yaml> --out <dir> [--check].
  • GitHub Actions. No workflow in this checkout runs its command.

As an API: its operation in the OpenAPI document and the MCP tool list of its layer.

installnone
runtimebun
networkno
when to choose it
whenEach extracted recommendation is to say who acts on it and during which business process, before any L2 asset is drawn.
limitsChecks ids against the vocabulary and coverage against the recommendations. Whether a persona or process is the RIGHT one is the agent’s judgement, and stays candidate until a person reviews it. smart-kg’s user-scenario has no slot for domain, link source or review status, so those ride on the edges.
costSeconds, no network.

What it is made of

Linked data

The Tool is published as its own JSON-LD document at its IRI, http://smart.who.int/base/tools/l1-recommendation-scenarios.jsonld, partOf its layer’s document. The node below is the definition this page was drawn from, and is embedded in the page as application/ld+json.

{
  "@context": "http://smart.who.int/base/smart-base.context.jsonld",
  "@id": "http://smart.who.int/base/tools/l1-recommendation-scenarios.jsonld",
  "@type": "https://litlfred.github.io/cat-harness/v0/ns/Tool",
  "partOf": "http://smart.who.int/base/smart-base.jsonld",
  "name": "l1-recommendation-scenarios",
  "title": "L1 recommendations → L2 user-scenario candidates",
  "description": "From an agent's `l1-scenario-mapping/v1`, write one smart-kg L2 `user-scenario` candidate per L1 recommendation, joined to a `persona` and a `business-process` by smart-kg L2's existing edges. Reuses the guide's own personas and processes, then smart-base's generic `DAK.Persona.*`; otherwise a glossary candidate or `could-not-determine`, each with a WARNING. Never invents a process.",
  "install": {
    "none": true
  },
  "invoke": {
    "shell": "bun run smart-base/scripts/l1-recommendation-scenarios.ts --l1 <l1.json|yaml> --vocabulary <guide.json> [--generic <generic.json>] --mapping <mapping.yaml> --out <dir> [--check]"
  },
  "io": {
    "inputs": [
      {
        "name": "l1",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "The recommendations: `l1-recommendation-candidates`' L1 3.0 graph, or an authored L1 YAML.",
        "required": true
      },
      {
        "name": "vocabulary",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "The target guide's personas and processes (`l1-scenario-vocabulary/v1`).",
        "required": true
      },
      {
        "name": "generic",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "smart-base's generic personas (second rung).",
        "required": false
      },
      {
        "name": "mapping",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "The agent's persona, process, act, outcome and domain per recommendation, each with a source and a basis.",
        "required": true
      }
    ],
    "outputs": [
      {
        "name": "graph",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "`scenario-candidates.l2.json`."
      },
      {
        "name": "warnings",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "`scenario-warnings.md` — processes not determined, personas that are glossary candidates."
      },
      {
        "name": "runContext",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "`run-context.json`, cat-harness `folio-run-context/v1`."
      }
    ]
  },
  "satisfies": [
    "recommendation-scenarios"
  ],
  "requirements": {
    "runtime": [
      "bun"
    ],
    "network": false
  },
  "selection": {
    "when": "Each extracted recommendation is to say who acts on it and during which business process, before any L2 asset is drawn.",
    "limits": "Checks ids against the vocabulary and coverage against the recommendations. Whether a persona or process is the RIGHT one is the agent's judgement, and stays `candidate` until a person reviews it. smart-kg's `user-scenario` has no slot for domain, link source or review status, so those ride on the edges.",
    "cost": "Seconds, no network."
  }
}

folio-assistant — code under the Apache License 2.0, documentation under CC BY 3.0. Generated schema and API references are rebuilt from source on every push to main.

deployed dev