Generated from smart-base/L1/skills/smart-l1/classify-and-code-content.md — do not edit here.

✎ Edit this page’s source

classify-and-code-content

Skill id: classify-and-code-content · Package: authoring-who-smart-guidelines · Methodology: terminology-coding · Process: classify-and-code-content.bpmn (Process_ClassifyAndCodeContent) · Tool: terminology-lookup

An agent proposes classifications, codes and coverage exclusions; a person in the named reviewer lane judges and signs them. The process has three lanes:

  1. authoring-agent codes slots and stages candidates (Step 1).
  2. l1-extraction-reviewer (a person) signs or rejects proposed L1 exclusions against the printed page (Step 2).
  3. terminologist (a person, the terminologist / ontologist reviewer) judges candidate codings, SKOS mapping predicates and glossary candidates (Step 3).

Input and output

Step 1 — Agent: classify and code slots with terminology-lookup

For each slot in an L1 extraction or L2 component, run the Tool, record provenance (declared, context, inferred) and status: "candidate", and stage the codings and any proposed exclusions for review:

bun run smart-base/scripts/terminology-lookup.ts \
  --slot <condition|intervention|persona|medicine|domain|business-process|recommendation-strength|recommendation-direction|evidence-certainty> \
  --query <term-or-code> \
  [--vocabulary <guide-vocabulary.json>] \
  [--generic <smart-base-generic-personas.json>] \
  [--scheme <scheme-id>] \
  [--out <result.json>]

Stop at the first rung that matches (terminology-coding §2):

  1. Rung 1 (rung-1-target-guide): the target guide’s own persona or business process from l1-scenario-vocabulary/v1, when its scope covers the statement.
  2. Rung 2 (rung-2-smart-base): smart-base generic personas (DAK.Persona.*), GRADE code-lists/*.json, or the guideline-domain SKOS scheme (clinical, public-health, health-system-strengthening).
  3. Rung 3 (rung-3-external-standard): the slot’s external standard (ICD-11, ICHI / CDHIv2, ISCO-08, ATC), distinguishing skos:exactMatch from skos:closeMatch per ontologist.
  4. Rung 4 (rung-4-local-candidate):
    • Unmatched persona or domain concept: record a local glossary candidate (status: "candidate", source: "extracted") per glossary-terms and emit WARNING <slot>-glossary-candidate.
    • Unmatched business process: never invent a process; record could-not-determine and emit WARNING process-not-determined.

Step 2 — l1-extraction-reviewer: read proposed exclusions against the page and sign

When recommendation-candidates writes exclusions.proposed.json, every entry carries:

{
  "signerRole": { "role": "l1-extraction-reviewer" }
}

and no signedOffBy. Until a reviewer signs it, l1-coverage counts the sentence as unaccounted and coverage stays below 100 %. In Lane_ExtractionReviewer:

  1. Open the printed page beside the work list. Locate location (p<page>:s<n>) in library/<doc_id>/sections/page-<NNN>.md (and the rendered page image when layout is ambiguous).
  2. Read the sentence in place, with its paragraph, heading and table context — never judge an exclusion from the isolated sentence.
  3. Check the proposed reason against the five closed reasons:
    • background-fact — epidemiology, disease burden, history, or biological fact with no normative action for a guideline user;
    • manufacturer-statement — a product insert or manufacturer specification quoted as context rather than a WHO recommendation;
    • editorial — licence text, imprint, how-to-read-this-document prose, chapter navigation checkpoints, or glossary definitions;
    • research-question — a gap or priority for future research, not a current practice or recommendation;
    • duplicate-of:<id> — a verbatim or near-verbatim repetition of a statement already captured under <id>, verified against <id>’s statement text.
  4. Sign or reject:
    • Sign if the sentence is non-normative for the stated reason: record signedOffBy (the reviewer’s handle) and timestamp in the curation / exclusions file, and re-run l1-recommendation-candidates so coverage updates.
    • Reject if it states a recommendation, implementation practice or remark that belongs in L1, with a reason, so the authoring-agent re-curates the location as a node.

Step 3 — terminologist: review candidate codings and glossary candidates

In Lane_Terminologist, the terminologist (equipped with ontologist, glossary-terms, and terminology-management) judges each staged coding:

  1. Scheme and rung: the slot was coded against the scheme named in terminology-coding §1, and no higher rung held an applicable concept.
  2. Precision: no narrower or broader concept is asserted as exactMatch (use closeMatch).
  3. Glossary candidates: for each Rung 4 candidate, promote it to status: "authored" (checking definition quality and skos:broader / skos:closeMatch links), replace it with an existing code from Rungs 1–3, or reject it.
  4. Verdict: record (approve, request-changes, or reject) in the mapping (review: {by, at}) or component QaReview.

Input and output contracts

What this skill takes and gives, as a class diagram drawn from its JSON Schema contracts by the schemas viewer’s own renderer. Each box links to its definition; each type to its specification.

input [1..1]output [1..1]authorityScheme [1..1]matches [0..*]term [0..1]candidateToMint [0..1]classify-and-code-content«skill»classify-and-code-contentinput : ClassifyAndCodeContentInput [1..1]output : ClassifyAndCodeContentOutput [1..1]ClassifyAndCodeContentInput«json-schema»ClassifyAndCodeContentInputslot : "condition" | "intervention" | "persona" | "medic… [1..1]query : string [1..1]vocabulary : string [0..1]generic : string [0..1]scheme : string [0..1]out : string [0..1]ClassifyAndCodeContentOutput«json-schema»ClassifyAndCodeContentOutputslot : string [1..1]query : string [1..1]authorityScheme : ClassifyAndCodeContentOutput.authority… [1..1]bestMatchKind : "exactMatch" | "closeMatch" | "none" [1..1]selectedRung : "rung-1-target-guide" | "rung-2-smart-bas… [1..1]matches : ClassifyAndCodeContentOutput.matches[] [0..*]candidateToMint : ClassifyAndCodeContentOutput.candidate… [0..1]ClassifyAndCodeContentOutput.authorityScheme«json-schema»ClassifyAndCodeContentOutput.authoritySchemeid : string [1..1]title : string [1..1]uri : string [1..1]localSources : string[] [0..*]ClassifyAndCodeContentOutput.matches«json-schema»ClassifyAndCodeContentOutput.matchesrung : "rung-1-target-guide" | "rung-2-smart-base" | "ru… [1..1]scheme : string [1..1]code : string [1..1]label : string [1..1]definition : string [0..1]matchKind : "exactMatch" | "closeMatch" [1..1]uri : string [0..1]sourcePath : string [1..1]ClassifyAndCodeContentOutput.candidateToMint.term«json-schema»ClassifyAndCodeContentOutput.candidateToMint.termid : string [0..1]prefLabel : string [0..1]status : "candidate" [0..1]source : "extracted" [0..1]ClassifyAndCodeContentOutput.candidateToMint«json-schema»ClassifyAndCodeContentOutput.candidateToMintaction : "mint-glossary-candidate" | "could-not-determin… [1..1]status : "candidate" | "could-not-determine" [0..1]term : ClassifyAndCodeContentOutput.candidateToMint.term [0..1]warning : string [1..1]

Processes that run this skill

This skill has its own process: Classify and code content.

BPMN diagram: Classify and code content

processstep(s) that name it
Classify and code contentIdentify slots and proposed exclusions; Run reuse-first lookup and record candidates; Check exclusions against page and sign; Adjudicate slot codings and glossary candidates

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