omfa

name	omfa
description	Guide modelers in applying good modeling practice across the full computational modeling lifecycle, from problem framing through evaluation, uncertainty disclosure, governance, and readiness for handoff to implementation. Use this skill when users want lifecycle guidance, quality self-assessment, required modeling deliverables, or protocol-specific checks for ABM, uncertainty, ethics, participatory modeling, deep uncertainty, or immediate lifecycle triage and handoff. Expected output: staged modeling guidance, identified deficiencies against required practices, handoff-readiness assessment, and a concrete set of required artifacts and review checks.
license	MIT
compatibility	Works with agent-based, system dynamics, statistical, simulation, and hybrid models
metadata	{"domain":"computational-modeling","maturity":"beta","audience":"anyone interested in computational modeling","category":"methodology"}

Good Modeling Practice

A modular guidance and skill framework for transparent, reviewable, computational modeling.

Purpose and Scope

Help modelers learn, adopt, and self-assess against established good modeling practices. Covers reviewable and transparent computational modeling across the full modeling lifecycle.

Use this skill to:

• structure scientific and policy-oriented modeling workflows
• improve transparency and scientific decision provenance
• document assumptions and uncertainties
• support participatory and ethical modeling practices
• standardize modeling deliverables
• guide iterative improvement of model quality and documentation
• support peer review and publication readiness
• enable auditability and machine-assisted review

Applicable model types:

• agent-based models (ABM)
• system dynamics models
• statistical and probabilistic models
• simulation workflows
• hybrid and ensemble modeling approaches

Applicable domains: research workflows, decision support, computational social science, environmental modeling, participatory simulation, policy exploration under uncertainty, complex adaptive systems analysis.

Activation Logic

If the request requires a more specific skill, emit only the handoff and stop. If a prerequisite artifact is missing, request or generate that artifact and stop. If the request asks for implementation planning, architecture, module mapping, parameter schema, or verification-plan artifacts, route to omfb and stop. If the request is about initializing, bootstrapping, or scaffolding a repository, adopting science.toml, OMF conformance, modernizing repository infrastructure, repository readiness, or reconciling a filesystem profile, load references/guidance/project-bootstrap.md before generic lifecycle treatment and follow its workflow. Only continue when OMFA is the authoritative skill for the current question.

Primary responsibilities:

• classify request
• determine whether lifecycle guidance is required
• identify current lifecycle state
• determine whether scientific prerequisites are ready for handoff to omfb
• determine applicable guidance
• recommend specialist skills
• synthesize results

Skill Boundaries

• For narrative documentation (model write-ups, methods narratives, publication-ready descriptions, README-style overviews) requiring sustained prose and rubric-driven fidelity to OMF standards and structure: use the document skill
• For publication-readiness metadata, reproducibility assessment, packaging, archival, environments, stewardship, and FAIR management plans: use the fair skill
• For peer review assessment with pass/fail criteria: use the peer-review skill
• For ongoing modeling practice guidance throughout the lifecycle: use this skill

This skill provides the foundational framework that the other skills assess against.

This skill is the primary entry point for the repository. Route here first when the user is trying to understand what to do next, what modeling stage they are in, or which specialist skill should run.

Conformance Language

• MUST / REQUIRED: Flag absence as a deficiency; request justification.
• SHOULD: Recommend but accept reasoned omission.

Core Modeling Principles

All modeling workflows MUST:

1. Be fit-for-purpose.
2. Produce reviewable artifacts that support inspection, revision, and reuse
3. Explicitly document all consequential assumptions.
4. Treat uncertainty as inherent, requiring explicit management, and disclosed transparently.
5. Prioritize contextual validity over universal claims (models are valid for specific purposes and conditions, not universally).
6. Justify abstraction and simplification choices.
7. Maintain scientific evidence provenance and decision provenance.
8. Document stakeholder and governance context.
9. Use transparent and auditable workflows.
10. Communicate limitations and appropriate use.

The following are prohibited:

• unsupported certainty claims
• undocumented calibration tuning
• hidden assumptions
• irreproducible workflows
• opaque preprocessing pipelines
• overfitted evaluation claims
• unqualified extrapolation beyond modeled conditions
• superficial stakeholder participation (participation lacking meaningful influence on model design decisions and interpretation)

---

Lifecycle Coordination

The computational modeling lifecycle is defined by references/guidance/lifecycle.md

The omfa skill is responsible for:

• identifying the current lifecycle state [MUST]
• loading references/guidance/lifecycle.md when lifecycle reasoning is required [MUST]
• following its routing recommendations to load additional guidance as needed [MUST]
• identifying missing artifacts [SHOULD]
• recommending downstream specialist skills [SHOULD]

---

Guidance Library

Use specialized guidance when applicable. Load only the guidance modules necessary to answer the user's methodological question. Guidance modules are composable and may be combined when their scopes are complementary.

Context	Required Guidance
Lifecycle coordination	references/guidance/lifecycle.md
Repository bootstrap and OMF conformance	references/guidance/project-bootstrap.md
Conceptual modeling	references/guidance/conceptual-modeling.md
Uncertainty analysis	references/guidance/uncertainty.md
Agent-based modeling	references/guidance/abm.md
Participatory modeling	references/guidance/participatory.md
FAIR workflows and reproducibility	fair skill
Ethics and governance review	references/guidance/ethics.md
Deep uncertainty and adaptive planning	references/guidance/deep-uncertainty.md
Model implementation handoff	omfb skill

Guidance modules encode expert methodological reasoning by helping agents:

• recognize when a methodology applies
• produce reviewable intermediate artifacts that preserve scientific reasoning across the entire modeling lifecycle
• make consequential analytical choices
• select appropriate methods
• avoid common methodological failure patterns

OMFA does not create competing implementation-planning artifacts; route implementation planning, architecture, module mapping, parameter schema, and verification-plan requests to omfb.

The bootstrap and OMF conformance module establishes only the minimum repository substrate; route detailed implementation architecture to omfb and stewardship, packaging, citation, and publication hardening to fair.

For ABMs, OMFA owns the canonical scientific artifacts (artifacts/model-card.md and artifacts/abm-spec.md). ODD/ODD+2 narrative generation is owned by document and must be handed off there when a publication-facing narrative or comparable formal model description is required.

---

Required Deliverables

Required deliverables are reviewable scientific artifacts that externalize assumptions, decisions, evidence, and evaluation for downstream collaborators, tools, and reviewers. The following artifacts are REQUIRED unless explicitly justified otherwise:

All reviewable artifacts MUST be stored under an artifacts/ directory at the project root. Use the provided templates in assets/ to ensure consistency and compatibility with downstream skills (e.g., omfb). All OMFA artifact filenames MUST use kebab-case. Do not create snake_case variants such as model_card.md, research_questions.md, or decision_log.md. If an existing project contains snake_case artifact names, report them as naming drift and prefer migrating or mapping them to the canonical kebab-case names. OMFA may assess whether the scientific prerequisites for implementation are ready for handoff, but it must not create or maintain implementation-planning artifacts owned by omfb.

When artifacts/ is first created, add artifacts/README.md that states:

• artifacts are living documents,

• artifacts are created early and revised throughout the project lifecycle,

• downstream use is gated by explicit status/review triggers.

• artifacts/model-card.md: summarize model design, performance, and limitations (domain-specific)

• artifacts/decision-log.md: record scientific decisions, evidence, rationale, alternatives, and approvals

• artifacts/conceptual-model.md: describe model purpose, scope, and assumptions

• artifacts/assumptions.md: make assumptions explicit for later review

• artifacts/uncertainty-register.md: document parameter, structural, and scenario uncertainty

• artifacts/stakeholder-register.md: identify affected stakeholders and participatory processes

• artifacts/evaluation-report.md: summarize evaluation context, methods, and results

• artifacts/ethics-impact-statement.md: document ethical considerations, representational harms, and vulnerable populations

ABMs additionally REQUIRE:

• artifacts/abm-spec.md

If an ABM request includes publication-facing narrative documentation, the ODD/ODD+2 handoff to document becomes a required gate after the canonical scientific artifacts above are current.

All deliverables SHOULD:

• use open formats,
• support machine inspection,
• include version information,
• identify authorship and provenance,
• document limitations and intended scope.

---

Minimum Handoff Readiness Checks

All modeling projects MUST, at minimum, confirm the conditions needed for a safe handoff to FAIR or OMFB:

• use version control,
• declare dependencies and environments,
• identify input datasets and provenance,
• document workflow execution steps,
• preserve parameterization and configuration,
• support deterministic reruns where feasible,
• archive release artifacts.

Recommended practices:

• semantic versioning,
• CI-compatible validation,
• automated testing,
• containerized or pinned environments,
• FAIR-aligned metadata.

For detailed reproducibility assessment, metadata, packaging, citation, archival, environments, and stewardship artifacts, route to the fair skill.

---

Uncertainty Policy

Uncertainty disclosure is mandatory.

Projects MUST document:

• parameter uncertainty,
• structural uncertainty,
• scenario uncertainty,
• data limitations,
• sensitivity to assumptions,
• calibration ambiguity and equifinality.

Claims MUST remain proportional to available evidence.

Predictive confidence MUST NOT be overstated.

See:

• references/guidance/uncertainty.md
• references/guidance/deep-uncertainty.md

---

Evaluation Policy

Evaluation MUST:

• align with model purpose,
• specify evaluation context,
• disclose evaluation limitations,
• distinguish calibration from validation,
• avoid metric-only performance claims,
• include robustness or sensitivity evidence where relevant.

ABMs SHOULD incorporate TRACE-style evaluation guidance.

---

Ethics and Participation

Projects with governance, policy, or societal implications MUST:

• identify affected stakeholders,
• document participatory processes,
• disclose exclusion and misuse risks,
• assess representational harms,
• identify vulnerable populations,
• record unresolved disagreements.

See:

• references/guidance/participatory.md
• references/guidance/ethics.md

---

Gotchas

• Lifecycle guidance can become a substitute for artifacts. Do not stop at advice when a user needs reviewable model materials; identify the concrete artifact that should be created or revised.
• Implementation planning belongs in OMFB. Do not create competing implementation plan, architecture, module mapping, parameter schema, or verification-plan artifacts; route those requests to omfb.
• ODD/ODD+2 narrative belongs in document. For ABMs, keep OMFA focused on the canonical scientific artifacts and route publication-facing ODD narrative generation to document once the handoff gate is met.
• Reproducibility work belongs in fair. This skill should only use reproducibility gaps as triage signals and route to fair for packaging, metadata, citation, release, archival, environments, and stewardship details.
• Participation is not automatically ethical review. Stakeholder engagement guidance helps document who was involved and how, but unresolved harms, exclusions, misuse risks, or vulnerable populations must still be surfaced explicitly.
• Model-stage routing can over-trigger specialist skills. Recommend document, fair, or peer-review only when the user intent reaches that specialist's boundary; otherwise provide lifecycle guidance here.

---

Review and Enforcement

Projects SHOULD fail review if:

• assumptions are undocumented,
• uncertainty is omitted,
• workflows cannot be reproduced,
• calibration lacks evaluation context,
• ABMs lack the required handoff to document for ODD/ODD+2 narrative when publication-facing documentation is needed,
• stakeholder processes are undocumented,
• provenance information is missing.

Review logic is defined in:

• the lifecycle guidance in references/guidance/lifecycle.md
• specialist readiness checks in the peer-review skill

---

Engineering Guidance

See the fair skill for detailed research software engineering practices. Key principles: prefer transparency over sophistication, robustness over overconfidence, and reviewable, modular, standards-based workflows.

---

References

Full citations maintained in references/REFERENCES.md.

• Good Modeling Practice: Sun et al. (2026), Swannack et al. (2025), Jakeman et al. (2024), Hamilton et al. (2022), Elsawah et al. (2017), Jakeman et al. (2006), Refsgaard & Henriksen (2004)
• Model Documentation: Grimm et al. (2006, 2010, 2020) [ODD protocol], Grimm et al. (2014) [TRACE]
• Model Evaluation: Augusiak et al. (2014), Hamilton et al. (2019)
• Uncertainty: Beven (2006)
• FAIR Principles: Wilkinson et al. (2016), Barker et al. (2022) [FAIR4RS]
• Software Practices: Lemmen et al. (2024)
• Decision Under Uncertainty: Lempert et al. (2003), Haasnoot et al. (2013)