bkn-ontology-builder

BKN Ontology Builder

Goal

bkn-ontology-builder Generate a business-reviewable ontology modeling proposal for an OpenBKN BKN project. It organizes PRDs, meeting minutes, process descriptions, system and data materials,BKN_Creator handoff summaries, or rough business descriptions into a modeling proposal that the business side can confirm: how the business world is abstracted into objects, relationships, logic, actions, governance, and collaboration boundaries.

The core deliverable is 《<项目或场景> 本体建模方案》, not a review report, and not a .bkn file.

Positioning and Boundaries

This Skill is an optional step between requirements discovery and formal BKN modeling:

业务材料 / PRD / handoff
  -> 可选 bkn-ontology-builder
  -> 业务可评审的本体建模方案
  -> BKN_Creator
  -> .bkn、校验、绑定、测试、平台操作

It does not do the following:

It does not generate .bkn files;
It does not bind data sources or platform data views;
It does not push the knowledge network to OpenBKN;
It does not execute platform Actions or platform queries;
It does not replace bkn-requirement in generating the PRD;
It does not replace bkn-creator in performing formal BKN modeling, validation, binding, and pushing;
It does not treat the ontology modeling proposal as a mandatory admission gate for BKN_Creator .

If the user explicitly requests to create, update, validate, bind, test, or push a BKN, it should be handed off to bkn-creator. If the user has only a very rough idea and the business goals, scenarios, processes, and acceptance questions are insufficient, maturity gaps should be output first, and if necessary it is recommended to use bkn-requirement。

Output Modes

Select the mode according to the input state; do not forcibly generate a complete proposal by default.

Input State	Default Mode	Output
Only a rough idea, insufficient business goals or materials	`intake_or_readiness_check`	Gaps, suggested supplementary materials, whether it is recommended to first go through `bkn-requirement`
Has a PRD, handoff, meeting minutes, process description, system/data materials, or sufficient business description	`scheme_mode`	Ontology modeling proposal
Has an existing ontology modeling proposal and requires optimization based on business feedback, Verifier findings, BKN construction, data binding, Action / Skill implementation, testing, Trace / Eval, or runtime evidence	`refine_mode`	Revised proposal, targeted revision suggestions, or delivery-archived proposal
Requires comparison between the PRD and the ontology modeling proposal	`compare_mode`	Differences, gaps, strengthening suggestions

If the user says "provide for BKN_Creator reference", still use scheme_mode or refine_mode to output/revise the proposal Markdown, and do not set up a separate handoff output mode.

refine_mode Must identify the revision basis:

Subtype	Trigger	Processing Focus
`business_feedback_refine`	Business review comments, new meeting minutes, supplementary materials, PRD iteration	Revise objects, relationships, scenario paths, confirmation status, and questions to be confirmed
`verifier_refine`	Verifier findings indicate hard stop, major, or minor	Revise in a targeted manner according to the findings; do not regenerate divergently
`implementation_feedback_refine`	BKN construction,`.bkn`, data binding, Action / Skill implementation, testing, Trace / Eval, or runtime audit exposes modeling problems in reverse	Backfill changes to object boundaries, relationship directions, Action boundaries, Skill contracts, governance, and evidence chains

implementation_feedback_refine Note that the ontology modeling proposal is one of the project deliverables and will be continuously refined along with implementation, validation, and operational evidence; however, this Skill still only revises the proposal and does not generate .bkn, does not bind data, and does not push to the platform.

Project Directory and Input Archiving

Shares the project folder rules with bkn-requirement ; the default project directory is:

projects/prj-<客户或项目简称>/

Each round of input materials should be archived or registered to:

projects/prj-<客户或项目简称>/inputs/round-XX/source-manifest.md

Rules:

External input files are first copied to this round's inputs/round-XX/, then registered.
Existing PRDs, validation outputs, handoffs, or modeling proposals within the project directory are only registered by path and version, not copied again.
Files marked as copied must have their archive path verified to actually exist.
When copying fails, permissions are insufficient, or the path is inaccessible, the archive status must not be falsified; the proposal must state at the beginning "input archiving not completed" and its impact.
The ontology modeling proposal must list "input sources for this round" at the beginning, explaining which raw materials, requirements discovery artifacts, and unarchived materials were used, and whether this proposal is an initial version, generated based on a PRD, or revised based on a previous version.

If the user only provides the project directory, automatically identify the latest materials:

The highest version of <项目名>-本体建模方案 vX.Y.md；
The highest version of <项目名>-PRD vX.Y.md；
The latest requirements discovery validation output,BKN_Creator handoff summary or handoff content at the end of the PRD;
The latest meeting minutes, research outline, and this round's inputs/round-XX/ materials;
Data dictionaries, field descriptions, sample data, and system materials.

Only when multiple equally credible inputs exist and would affect the output should the user be asked to confirm.

Main Process

The formal ontology modeling proposal must execute the Agentic Harness:

Archive / Context
→ Generator
→ Verifier
→ Reviser（如有必要）
→ Final Gate
→ Final Output

Archive / Context

Identify the type, version, path, and purpose of input materials;
Archive or register inputs, and verify the manifest;
Distinguish confirmed business facts, material assumptions, modeling candidates, conflicting information, and missing information;
Extract business goals, user roles, P0/P1 scenarios, key decisions, inputs, outputs, acceptance questions, data sources, collaboration boundaries, and governance risks.

Generator

Generate candidate modeling proposals; do not directly declare final approval. Must start from business goals and scenarios, deriving in the order of "business goals → business objects to be managed and judged → stable business relationships → facts/attributes/metrics → logic/Skill candidates → actions with side effects → operational state and audit → governance boundaries → evidence paths".

For the proposal structure and writing style, see assets/ontology-scheme-template.md and references/ontology-builder-method.md。

Verifier

Independently inspect the candidate proposal; do not directly modify the document. At minimum, check:

Whether it starts from business goals and scenarios, rather than from source tables, fields, pages, reports, or interfaces;
Whether inputs are archived or registered, and whether references indicate version and path;
Whether objects avoid mis-objectifying source tables, report rows, temporary results, role names, rules, and prompt logic;
Whether core objects, relationships, Skills, Actions, and governance boundaries explain business definitions, modeling rationale, boundaries, risks, and confirmation status;
Whether stable facts are separated from operational state;
Whether the boundaries of metrics, operators, interpretation logic, Skills, Agents, and Actions are clear;
Whether it covers object lifecycle, workflows, state progression, task queues, action triggers, exception handling, and feedback loops;
Whether workspace, collaboration, private perspectives, and TraceAI / Eval integration appear only when supported by materials;
Whether confirmed content, modeling candidates, items pending business confirmation, and items pending downstream determination are separated;
Whether it is incorrectly claimed that this plan is a BKN_Creator gate or .bkn draft.

Verifier findings are divided into hard_stop、major、minor。hard_stop must revise,major in principle revise,minor may revise or explain in the final summary.

If a candidate plan is written to disk in the project directory this round, an independent *-verifier-findings.mdmust be written to disk at the same time. Verifier findings should not only be embedded in the main body of the plan.

Reviser

Make targeted revisions only based on Verifier findings:

First fix hard_stop, then fix major；
Do not delete confirmed business facts unless the confirmation status is wrong;
Do not rewrite candidate items as confirmed content;
Do not rewrite the plan as .bkn, schema, or platform execution instructions;
After revision, the Verifier must be run again;
Automatic revision is limited to at most 2 rounds; after exceeding that, stop and output the remaining issues and next-step recommendations.

Final Gate

Final Gate only judges the quality of the plan; it does not decide whether the project can enter BKN_Creator。

Status	Condition	Output
`pass`	No hard stop, majors handled or explainable	Formal ontology modeling plan
`warn`	No hard stop, but key items remain to be confirmed	Candidate plan, with pending confirmation issues and next steps
`fail`	Hard stop not cleared	Do not declare the plan ready for review; output the reasons for failure and the list of supplementary materials

If the plan is written to disk in the project directory this round, an independent *-final-gate.mdmust be written to disk at the same time, recording gate status, basis, remaining risks, and next steps.

Harness artifact boundaries

When formal scheme_mode or refine_mode is written to disk, use the following artifact boundaries:

Harness stage	Standard artifact	Naming suggestion	Description
Archive / Context	`source-manifest.md`	`inputs/round-XX/source-manifest.md`	Archive or register the input; do not duplicate files within the project
Generator	Candidate plan	`<项目名>-本体建模方案 vX.Y-candidate.md`	Candidate output; do not declare final passage
Verifier	Independent findings	`<项目名>-本体建模方案 vX.Y-verifier-findings.md`	Only inspect, do not directly modify the plan
Reviser	Revised candidate plan	`<项目名>-本体建模方案 vX.Y-revised-candidate.md`	Produced only when revision is needed
Final Gate	Gate conclusion	`<项目名>-本体建模方案 vX.Y-final-gate.md`	Only judge the quality of the plan; do not decide whether to enter BKN_Creator
Final Output	Final plan	`<项目名>-本体建模方案 vX.Y.md` or `<项目名>-本体建模方案 vX.Y-candidate.md`	`warn` keep the Candidate marker when

During development testing, *-harness-run-report.md may additionally be output to summarize one sample run, but it is not a business deliverable, nor a substitute for the Verifier, Reviser, or Final Gate.

Implementation feedback revision may additionally output <项目名>-本体建模方案 vX.Y-实现反馈修订说明.md. If used for project delivery archiving, <项目名>-本体建模方案 vX.Y-交付归档版.mdmay be output, but business review criteria, implementation verification results, engineering workarounds, and items pending business re-review must be distinguished.

Required sections

By default output 《<项目或场景> 本体建模方案》, recommended sections:

Modeling goals
How business goals are carried by the ontology
Ontology design philosophy
Overall layering
Business object design
Relationship design
Metric / operator / explanation logic modeling
Business operation layer design
Action / action modeling
Skill / Agent application contract
Scenario-to-ontology path mapping
Business evidence chain and explainability design
Collaboration / workspace / private perspective boundaries (as needed)
Model governance principles
Cross-scenario or cross-industry extension methods (as needed)
Final ontology blueprint
Solution boundaries and subsequent enhancements

Sections 7, 8, 9, 10, 12, 13, and 15 must be tailored to the material. If not applicable, explain why; do not force-fit the template.

When to read reference materials

When generating or revising a complete solution, read references/ontology-builder-method.md and assets/ontology-scheme-template.md。
When handling BKN construction, binding, Action / Skill, testing, Trace / Eval reverse revision, read references/ontology-builder-method.md the implementation_feedback_refine protocol, and use assets/implementation-feedback-refine-template.md。
When independent Verifier or Final Gate artifacts need to be persisted to disk, use assets/verifier-findings-template.md and assets/final-gate-template.md。
When BKN objects, relationships, metrics, operators, Actions, governance, or Skill / Agent boundaries are involved, read references/bkn-methodology.md。
When complex collaboration, shared Base, private judgment, and separation of runtime state and event audit are involved, read references/complex-ontology-patterns.md。

Final self-check

Before output, confirm:

The sources of input for this round have been listed;
The solution starts from business goals and scenarios;
Core objects, relationships, logic, Actions, Skills, and governance boundaries all have design rationale;
Stable facts are separated from runtime state;
Queries, computations, and explanations are not directly mistakenly modeled as Actions;
Only operations with side effects are modeled as Actions;
The business operation layer explains the lifecycle, state machine, work queue, human confirmation, action records, and feedback loop;
Key judgments can be traced to objects, relationships, sources, rules, human confirmation, and action results;
Confirmation states are strictly isolated;
refine_mode It has been explained whether the basis for revision belongs to business feedback, Verifier findings, or implementation feedback;
Implementation feedback revisions have distinguished business facts, implementation verification results, engineering workarounds, pending business review, and pending downstream platform determination;
Generator, Verifier, necessary Reviser, and Final Gate have been executed;
The solution has not been declared as .bkn, platform execution results, or BKN_Creator mandatory gate.