Business Context Modeling

Business Context Modeling

Turn an ordinary conversation about work into a model people can inspect, question, and refine. Keep the analysis rigorous behind the scenes and make the published model quiet enough for a reader who wants to understand the business.

Core contract

• Start from the user's language. Do not require a form before producing a first model.
• Work in two surfaces: an authoring workspace for evidence, candidates, classifications, comparisons, and unresolved questions; and a reader-facing artifact for the model, a short explanation, and links to related views.
• Keep project-specific decisions and open questions in the project's private checkpoint when one exists. Do not hide them inside a public sample.
• Preserve the trace from Why / Purpose through the desired outcome, Business, and Actor / Information / System relationships to How / Flow / implementation. Move both downward and upward as the model changes.
• Describe a Business's input, transformation, and output before naming it. Name the transformation, not a method merely used to perform the work.
• Treat modeling as a basic action across Business activities whenever meaning can be externalized. Do not confine it to one activity called modeling.
• Keep a Business Map of constituent capabilities separate from a Business Flow. A map shows composition or relationships; a flow shows order, decisions, and rework.
• Reuse the structure of a reader-facing page, not the semantic structure of its diagram. Re-derive Actors, Information, relationships, and the Context variant from each Business Story.
• Define a Business Context by one Business Use Case or coherent business scene, not by one activity. Put the sibling Business activities that make the scene work in a central backbone. Place executors, providers, and inputs on the left; place value recipients and outputs on the right.
• Treat --> as a semantic exception. Use it only when direction itself changes the answer and left/right placement is insufficient. Record the reason in the authoring workspace and use the explicit checker flag.
• Do not invent Actors, Information, External Systems, exchanges, or responsibilities to fill a notation.
• Treat Information as business vocabulary: a named domain concept that people can reference, check, update, or share and that affects judgment, responsibility, or value. Never create Information only to join two nodes.
• Build the Actor / External System × Business participation matrix and the Information × Business create / update / reference / provide matrix before editing a Business Context. Project the View from that relationship Model.
• Separate an Actor's position from its relations. Position expresses the Actor's main value role across the Use Case; each relation expresses direct participation in one Business. A left or right Actor may relate to several Businesses.
• Keep Markdown Mermaid as the editable source. Do not create .mmd, SVG, or PNG unless the user explicitly requests standalone source or export.

Reference routing

Read only the references needed for the task:

• business-story-and-5w2h.md: build a Business Story, use 5W2H as an analysis lens, and preserve the Why-to-How meaning trace.
• modeling-rules.md: extract candidates, classify Actor / Business / Information / External System, align grain, and name Business activities through semantic compression and transformation.
• master-elements.md: maintain canonical actor, external-system, and information maps when reusable identities or same-type relationships matter.
• multi-view-modeling.md: distinguish Model from View, choose Purpose / Map / Context / Flow views, and keep upward and downward trace.
• reader-facing-artifacts.md: separate the modeling workspace from a public sample and edit for business readers.

Use mermaid-diagram-authoring for the notation and source-only validation of each diagram.

Workflow

1. Frame the work

Infer the purpose, first reader, business boundary, state, and the one question the current View should answer. Ask at most one blocking question; make a reviewable version zero when the language already supports one.

2. Build the Business Story in the workspace

Write a short natural-language account of who provides which Information, what the Business changes, what it produces, and who receives or uses the result. Use 5W2H to find missing meaning, not as a required public-page format. Follow business-story-and-5w2h.md.

3. Extract and name

Preserve concrete source words, then classify the observed Actor, Business, Information, and External System candidates. For each Business, state input, transformation, and output; compress the transformation into a short natural name; and test it as a verb. Record rename / split / merge decisions in the workspace or private checkpoint, not in the reader-facing page.

For Information candidates, test whether people doing the work can use the term as a noun with verbs such as reference, check, update, or share. Maintain the observed phrase, plain definition, stable ID, creating/updating/referencing Businesses, recipients, and confidence in the Information master companion. Reuse one identity across Businesses and Contexts when the meaning is the same.

4. Connect Why to How and choose Views

Keep the meaning chain behind the model. Publish only the Views that answer a reader's question, such as:

• Purpose / Outcome: what state the work seeks;
• System Context: who participates around the whole Business;
• Business Map: which peer Business capabilities constitute the whole;
• Business Context: how multiple Business activities, participants, and Information make one Business Use Case work;
• Business Flow: what order, decision, or rework occurs inside one Context.

Do not make one diagram answer all levels.

5. Reconcile reusable elements

When actor, external-system, or information identities recur across Contexts, reconcile them with the corresponding master map. Reuse stable IDs, labels, icons, and sizes. If a relationship is not observed, keep it unresolved in the workspace rather than drawing it.

Before selecting Context relations, write two compact matrices in the workspace:

• Actor / External System × Business: executes, provides, participates, decides, receives value, or none;
• Information × Business: create, update, reference, provide, or none.

Use these matrices as the relationship Model. Do not infer participation from where Mermaid places a node.

6. Author and validate the working model

Use Mermaid as a discussion surface. Keep one subject, state, relationship meaning, and main abstraction level per diagram. Run the matching source-only checker. Let density or awkward layout send the work back to boundary, grain, or naming before adding layout machinery.

For a Business Context, define left-side nodes first, then the sibling Business activities and any genuine shared Information in a source order that supports their semantic roles, then right-side nodes. Write every relation in approximate left-to-right source order. Do not force a mechanical Business - Information - Business alternation. A direct Business --- Business relation may express continuity when no meaningful Information bridge is observed; it never means a precise procedure sequence. Do not invent an Information node or relation to force the backbone.

Split by a genuine scene change in participants, Information, External System, value recipient, or responsibility boundary, or when visual/cognitive density makes the backbone hard to discuss. Business count and node thresholds are review signals, not automatic boundaries.

Source validation does not finish the View. Inspect the preview and confirm that the Business backbone is central and traceable, providers read on the left, recipients read on the right, Information bridges are meaningful, and no unnecessary arrow, crossing, or endpoint clipping remains.

Treat these checker observations as prompts for semantic review, not automatic deletion: an Information node used only as a two-Business bridge; an Actor connected only to the first or last Business in a multi-Business Context; every Information node having degree two on one path; or a perfectly alternating Business / Information backbone. Confirm each against the dictionary and matrices.

Before copying a previous Context pattern, hide the existing diagram and audit the Business Story, Why, input, transformation, output, and each participant's responsibility. Follow modeling-rules.md.

7. Publish for the reader

Edit the agreed meaning into the reader-facing pattern:

1. a title that names the business question;
2. one or two short sentences;
3. the Mermaid diagram;
4. only the explanation the diagram cannot carry;
5. natural links to its parent, child, or supporting View.

Remove authoring history, candidate tables, method explanations, validation notes, and private uncertainty from that surface. Follow reader-facing-artifacts.md.

8. Garden knowledge and close

• Move reusable methods to this Skill or its nearest reference.
• Move project-specific decisions, unresolved items, and review state to the private checkpoint.
• Delete obsolete or duplicated public explanations instead of hiding them.
• Validate the repository, run git diff --check, and report exports only when they were explicitly requested.

Output contract

Maintain three different outputs when the project needs them:

Authoring workspace

Business Story, 5W2H notes, source evidence, candidate inventory, input / transformation / output, naming decisions, Information dictionary, Actor × Business and Information × Business matrices, boundary, assumptions, omissions, unresolved questions, view trace, and validation results.

Reader-facing artifact

The model diagram, a short business explanation, a short reading, and links to related Models / Views. Do not require the reader to understand the modeling method.

Private checkpoint

Project-specific decisions, alternatives, rename / split / merge candidates, review state, unresolved items, next action, and stopping point.

Field-use readiness

The Skill is ready for a first field use when this chain works end to end:

1. conversation becomes one coherent Business Use Case / scene (Workflow 1–3);
2. the workspace states who provides what, what changes, what is produced, and who receives value (business-story-and-5w2h.md);
3. Actors, Information, and External Systems come from observed meaning, with Information maintained as business vocabulary (modeling-rules.md and master-elements.md);
4. Actor and Information relationships are stated in matrices before sibling Business activities are projected as a readable central backbone (check_business_context.py);
5. executor/provider/input nodes are left and recipient/output nodes are right (template plus business checker);
6. ordinary relations use spatial reading and --- (context checker default);
7. arrows require semantic justification and --allow-arrow-exception;
8. each Business can expand into a Flow or recursive Detailed Business Context, and discoveries return to the parent (multi-view-modeling.md);
9. the public page stays short (reader-facing-artifacts.md);
10. source checks and semantic-smell observations are followed by visual review, including endpoint markers (mermaid-diagram-authoring fixture and checklist).