bkn-ontology-builder

BKN Ontology Builder

Objective

bkn-ontology-builder Generate a business-reviewable ontology modeling proposal for a KWeaver 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:

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

If the user explicitly requests creating, updating, validating, binding, testing, or pushing a BKN, hand it over to bkn-creator. If the user only has a very rough idea and the business objectives, scenarios, processes, and acceptance questions are insufficient, first output the maturity gaps, and if necessary recommend using bkn-requirement。

Output Modes

Select the mode based on the input state; do not force generation of a complete proposal by default.

Input State	Default Mode	Output
Only a rough idea, insufficient business objectives or materials	`intake_or_readiness_check`	Gaps, recommended supplementary materials, whether to recommend first going through `bkn-requirement`
Has a PRD, handoff, meeting minutes, process descriptions, 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 of the PRD and the ontology modeling proposal	`compare_mode`	Differences, gaps, reinforcement suggestions

If the user says "give BKN_Creator as a reference", still use scheme_mode or refine_mode to output/revise the proposal Markdown, without setting up a separate handoff output mode.

refine_mode must identify the revision basis:

Subtype	Trigger	Handling Focus
`business_feedback_refine`	Business review comments, new meeting minutes, supplementary materials, PRD iteration	Revise objects, relationships, scenario paths, confirmation status, and open questions
`verifier_refine`	Verifier findings indicate hard stop, major, or minor	Revise in a targeted way 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 reverse-exposes modeling issues	Backfill changes to object boundaries, relationship directions, Action boundaries, Skill contracts, governance, and the evidence chain

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

Project directory and input archiving

and bkn-requirement share the project folder rules; the default project directory is:

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

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

docs/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 plans in the project directory are only registered by path and version, not copied again.
Files marked as copied must have their archive paths verified to actually exist.
When copying fails, permissions are insufficient, or the path is inaccessible, the archive status must not be falsified; the beginning of the plan must state "Input archiving incomplete" and its impact.
The beginning of the ontology modeling plan must list the "Input sources for this round", explaining which raw materials, requirement discovery artifacts, and unarchived materials were used, and whether this plan is the initial version, generated based on the PRD, or revised based on the previous version.

If the user provides only 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 requirement discovery validation output,BKN_Creator handoff summary or the 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 there are multiple equally credible inputs that would affect the output should the user be asked to confirm.

Main process

The formal ontology modeling plan 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 plans without directly declaring 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 → runtime state and audit → governance boundaries → evidence paths".

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

Verifier

Independently inspect candidate plans without directly modifying documents. At minimum, check:

Whether it starts from business goals and scenarios rather than source tables, fields, pages, reports, or interfaces;
Whether inputs are archived or registered, and whether references indicate version and path;
Whether objects avoid mis-objectification of 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 and runtime state are separated;
Whether the boundaries of metrics, operators, explanation logic, Skills, Agents, and Actions are clear;
Whether it covers object lifecycles, workflows, state transitions, task queues, action triggers, exception handling, and feedback loops;
Whether workspace, collaboration, private views, 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 incorrectly claims 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 the project directory in this round, an independent *-verifier-findings.mdmust also be written. Verifier findings should not only be embedded in the main plan body.

Reviser

Revise only in a targeted manner 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

The Final Gate only judges plan quality and does not decide whether the project can enter BKN_Creator。

Status	Condition	Output
`pass`	No hard stop, majors have been addressed or are explainable	Formal ontology modeling plan
`warn`	No hard stop, but key items still pending confirmation	Candidate plan, with pending confirmation issues and next steps
`fail`	Hard stop not cleared	Do not declare the plan reviewable; output the reasons for failure and the list of supplementary materials

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

Harness artifact boundaries

When the formal scheme_mode or refine_mode is written, 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 repeatedly copy 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 judges plan quality; does not decide whether to enter BKN_Creator
Final Output	Final plan	`<项目名>-本体建模方案 vX.Y.md` or `<项目名>-本体建模方案 vX.Y-candidate.md`	`warn` keep the Candidate identifier

During development and 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 according to the materials. When not applicable, explain the reason; 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, and Trace / Eval reverse revision, read references/ontology-builder-method.md 's implementation_feedback_refine protocol, and use assets/implementation-feedback-refine-template.md。
When independent Verifier or Final Gate artifacts need to be persisted, use assets/verifier-findings-template.md and assets/final-gate-template.md。
When BKN objects, relationships, metrics, operators, Action, governance, or Skill / Agent boundaries are involved, read references/bkn-methodology.md。
When complex collaboration, shared Base, private judgment, or separation of runtime state and event auditing is involved, read references/complex-ontology-patterns.md。

Final Self-Check

Before output, confirm:

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