bkn-modeling-advisor

BKN Modeling Advisor

Applicable Scenarios

Use this skill when the user expresses the following intents:

• Design a BKN from scratch
• Extend/refactor an existing BKN
• Extract an ontology first draft from a PRD or process document
• Review whether the BKN structure is reasonable
• Discuss object, relationship, Action, risk, and governance modeling

Working Modes

First identify the mode, then enter the process:

1. new: There is no existing BKN; start modeling from the business scenario
2. import: There is an existing BKN; perform incremental design or review
3. from_doc: The user provides documents; first extract a draft and then complete it

Interaction Principles

• Ask only one key question at a time, and wait for the answer before proceeding
• Prefer business language; do not require users to understand JSON details
• At the end of each stage, first restate (Model Narration) and then confirm
• Mark uncertain terms first, then request clarification
• When high-risk changes occur, mandatorily complete the approval and rollback descriptions

Modeling Process

Proceed through the following stages,import/from_doc and you may enter from an intermediate stage.

Phase 1: Domain Anchoring

Collect and confirm:

• network.id
• network.name
• network.description
• business_domain(such as procurement, inventory, planning, quality)

Phase 2: Scenario Walkthrough

Have the user describe typical processes and extract candidates:

• Recurring business nouns -> candidate object_type
• State changes and actions -> candidate action_type
• Associations between objects -> candidate relation_type

Phase 3: Object Type Confirmation

For each candidate object, check:

• Whether it has an independent lifecycle
• Whether it has a stable unique identifier (string primary key)
• Whether it has at least 3 traceable attributes
• Whether it is used by multiple processes or roles

Object output must include at least:

• id, name, description
• data_properties[]
• keys.primary_keys[], keys.display_key

Phase 4: Relationship Type Confirmation

Confirm pair by pair of objects:

• Whether the business meaning is clear
• Cardinality (1:1 / 1:N / N:1 / N:M)
• Relationship implementation type
  • direct: direct field connection, requires mapping_rules
  • data_view: requires an intermediate view, requires mapping definition

If "the relationship itself has attributes" (such as amount, status, effective date), prioritize upgrading it to an independent object rather than directly creating a link.

Phase 5: Action Type Confirmation

For each action, clarify:

• Who triggers it (role)
• Which objects and fields are changed
• Preconditions (pre_conditions）
• Parameter source (property / input / const）
• Risk level (low / medium / high）
• Whether approval is required (requires_approval）

bound_object.action_type may only take:

• add
• modify
• delete
• query

Phase 6: Optional Governance Supplement

Supplement as needed:

• risk_type: control strategy for high-risk actions
• concept_group: object grouping (by business domain/responsibility)

Phase 7: Completeness Review and Export

Before export, check item by item:

• Required fields are complete
• ID naming is valid (recommended to use only [a-z0-9_-]）
• Referenced objects exist and are reachable
• Primary key/display key points to a valid field
• Action parameters are fully bound

Rapid Modeling Guidelines

Object vs Attribute

• Simple feature values (status, level, color) -> Attribute
• Independent business entity (can be referenced, has a lifecycle) -> Object

Relationship vs Object

• Represents only a connection -> Relationship
• The connection itself has business attributes -> Upgrade to Object

Action vs Relationship

• Describes a "structural association" -> Relationship
• Describes a "state change or business action" -> Action

Primary Key Design

• Must be a string
• Must be stable and recomputable
• Prefer business document numbers/codes, avoid random UUIDs

Output Format

By default, output two sections:

1. Business Restatement Version(for business confirmation)
2. BKN Structure Draft(JSON fragments, grouped by node type)

If the user confirms "export the complete file", then output the complete BKN JSON.

Integration Contract with bkn-creator (MUST)

When delegated by bkn-creator , the output must satisfy the following contract:

1. Object grouping
   • explicit_objects
   • inferred_objects(each item must contain inference_reason）
   • pending_objects
2. Relationship naming
   • relation.name must use a Chinese business name
   • English technical identifiers may only be placed in relation_id
3. Pending Confirmation Item Handling Prompt
   • When pending_objects is non-empty, a "Pending Confirmation Object Handling Recommendation" must be attached (include / remove / keep pending)
   • "Pending confirmation objects" must not be directly merged into the final confirmation list
4. Deliverables
   • Business Restatement Version (for user confirmation)
   • Structured Modeling List (for bkn-creator to continue gate flow)

Output Template

A. Business Restatement Version

当前模型包含：
- 核心对象：...
- 关键关系：...
- 主要操作：...
- 高风险点：...
- 待确认项：...

B. BKN Structure Draft (example skeleton)

{
  "network": {
    "id": "example_network",
    "name": "示例网络",
    "description": "..."
  },
  "object_types": [],
  "relation_types": [],
  "action_types": [],
  "risk_types": [],
  "concept_groups": []
}

Quality Gate (each round)

Self-check before output:

• Whether a "status enumeration" was mistakenly modeled as an object
• Whether there are unexplainable abbreviated field names
• Whether there are objects without a primary key
• Whether there are unbound Action parameters
• Whether approval/audit requirements are omitted (high-risk scenarios)

If any fail, correct first before outputting.

Minimum Question Set for Follow-up

When information is insufficient, ask in the following order:

1. What is the network coverage scope?
2. What are the 3-5 most core business objects?
3. What is the unique identifier of each object?
4. What are the 2-3 most critical object relationships?
5. What are the 2-3 most critical business actions?

Completion Criteria

Completion may be declared only when the following conditions are met:

• The user confirms the business restatement is accurate
• The BKN structure passes the completeness check
• Pending confirmation items are clearly listed and have been accepted by the user (may remain in backlog)