Authoring workflow

Two front doors

A finding model reaches the corpus through one of two routes. A web application handles one finding at a time with a person driving. A set of agent skills in the content repository handles conversational and bulk authoring with a person reviewing. Both produce the same JSON, and both end at the same validator.

Finding Model Forge

Forge is the hosted authoring front end, deployed at fmf.oidm.org and profiled in applications. The workflow documented on its dev branch has four stages, all served into one page by content swaps rather than page navigation.¹

1. Basic information. Sign in with GitHub, enter a finding name, and the application generates a description from it.
2. Description refinement and similarity check. Review and edit the generated description, optionally add synonyms, then check for similar existing models. If similar models are found they are shown for review; if not, a draft is created immediately.
3. Draft editing. The name is read-only; description, synonyms, and an attributes markdown editor are editable, and changes autosave. Generating the preview produces the full finding model JSON.
4. Preview and submission. The generated model is displayed with its draft status; submitting locks it.

A draft carries the user, the name, the raw inputs, the server-generated JSON, a status, and an action log. Status moves through draft, submitted, under-review, and then added or declined. Submitting locks further editing, and resuming a submitted name goes to the final display view.² Editing a model after it has been published is open as issue 13 and is not implemented on main.

The findingmodel-ai command line

The findingmodel-ai package is the scriptable half of the same capability, installable from PyPI and configured with an API key for at least one model provider.³ Three commands cover the common path.

findingmodel-ai make-info "pneumothorax"        # name to description and synonyms
findingmodel-ai make-stub-model "pneumothorax"  # a basic model template
findingmodel-ai markdown-to-fm outline.md       # markdown outline to a finding model

The same functions are available as a Python API, and an optional web-search key enables a detail pass that returns citations alongside the generated description. Model choice is configurable per agent.

Agent skills in the content repository

Three skills live under .claude/skills/ in findingmodels and divide the work by shape of the job.

Skill	Use it when	Shape
finding-author	one finding at a time, discussed interactively	search, then either add a synonym to an existing model or draft a new one
finding-batch	a list, CSV, or directory of source content	triage the whole batch, then draft each finding in an isolated sub-agent
finding-review	existing definition files named by path, glob, or directory	lint, then review each file in an isolated sub-agent, then human sign-off

Each skill file is deliberately thin. All rules, command cheatsheets, and procedures live in prompts/fragments/, and the skill loads the fragment named at each step rather than carrying the rules itself.⁴ Sixteen fragments cover naming, synonym rules, scope and specificity, presence and change, the associated-versus-component distinction, search and triage, mechanical lint, the quality checklist, review file generation, CSV writeback, and handoff to the review interface. core_concept.md is the orientation fragment every skill reads first; it states the two guiding principles as “a finding is a noun phrase; everything else is an attribute” and “findings exist in time.”⁵ A companion defaults.yml holds the contributor and organization defaults, the permitted source codes for identifier minting, and suggested tag sets per campaign, which the skill confirms with the user at session start.

Three constraints run through all three skills.

• Context isolation is mandatory in bulk work. Each finding in a batch, and each file in a review, is handled by a fresh sub-agent with no exposure to its neighbors, so one finding’s drafting cannot contaminate the next.⁶
• Search results are evaluated, not forwarded. The skill generates two or three complementary search targets, pools the results, judges them itself, and reports one of three outcomes rather than handing the user a raw candidate list.⁴
• Review starts from a clean tree. The review skill refuses to run when defs/ has uncommitted changes, so its edits can be diffed cleanly. There is no command-line override; the user overrides it conversationally.⁷

Review runs mechanical lint first, with auto-fix for trivially fixable errors such as underscores in names and self-synonyms, then a quality pass, then a terminal interface where a person approves, requests changes, or reverts through git.

The gate every route passes

Whatever produced the JSON, it lands in defs/ and is committed. A pre-commit hook runs uv run scripts/validator.py --with-git-adds on every commit, serially, whether or not a definition was staged.⁸ The validator validates every definition against the format, fails on a duplicate finding or attribute identifier, reformats the JSON in place, regenerates the markdown render in text/, rewrites the corpus index, rewrites ids.json, and stages all of it. See identifiers for what the duplicate check protects.

The practical consequence is that the generated artifacts cannot drift from the source. It is also why the repository’s guidance forbids editing them by hand.

Requests and cleanup

Content requests arrive as GitHub issues on the content repository. Five of the ten open issues are content batch requests, naming RadElement-derived definitions, chest CT and chest radiograph device lists, abdomen CT findings, knee MRI findings, and CDEStaging source material. Those issues are what the in-flight branches described in the content catalog are working against.

Two plan documents on main govern the conventions the workflow applies.

• The definition cleanup plan, marked draft and for review, is a conventions pass over the existing corpus rather than new authoring. It sequences the work: lowercase 123 title-cased names and move acronyms to synonyms, add the missing presence and change-from-prior attributes to 124 models that lack them, resolve 84 names carrying population qualifiers, audit synonyms, split or re-attribute 71 names containing a “with” clause, fix punctuation on 18, and finally reclassify the Gamuts entries that are differential-diagnosis patterns rather than findings, which the plan flags as needing a design discussion.⁹
• The rebuild finding skills plan tracks the restructuring of the skill surface into rule fragments, substep fragments, review fragments, relocated scripts, and trigger evaluations. Phases 0 through 8 are done; end-to-end verification and the final plan update remain.¹⁰

Footnotes

1. Finding model creation workflow, FindingModelForge dev branch ↩

2. Finding model draft workflow, FindingModelForge dev branch ↩

3. findingmodel-ai package README, findingmodel main branch ↩

4. finding-author skill, findingmodels main branch ↩ ↩²

5. core_concept.md prompt fragment, findingmodels main branch ↩

6. finding-batch skill, findingmodels main branch ↩

7. finding-review skill, findingmodels main branch ↩

8. Pre-commit configuration, findingmodels main branch ↩

9. Definition Cleanup Plan, findingmodels main branch ↩

10. Rebuild finding skills plan, findingmodels main branch ↩