mbse-system-modeling

name: mbse-system-modeling description: "Explore the current system and generate or update multi-level architecture documentation using an MBSE-lite approach: system context, capability map, containers, runtime sequences, state machines, subsystem decompositions, and boundary-smell analysis." keywords: - mbse - system modeling - reverse architecture - system design documentation - context diagram - sequence diagram - class diagram - state machine - responsibility map - decomposition related: - monorepo-architecture - domain-driven-design - state-machine-workflow-patterns - event-driven-messaging-patterns - requirements-engineering

MBSE System Modeling

Use this skill when the goal is to understand the current system design through multiple views and abstraction levels, not to propose a future architecture first.

When to Use

System understanding is harder than implementation.
Responsibilities, scopes, or subsystem boundaries feel ambiguous.
You need diagrams and structured views of the current design.
You want to reveal overlaps, duplicated control, or mixed abstraction levels.
A refactor or RFC needs an evidence-backed model of the system as it exists.

Core Principle

Model the system as-is, not as intended.

Start broad, then decompose only the hotspots. Keep filenames and section headings stable so later runs update existing documents instead of inventing new ones.

Output Layout

All generated or updated docs live under:

docs/system-models/

Read references/layout.md before writing. It defines the exact tree, file names, and required sections.

If the scaffold does not exist yet, initialize it:

python3 "${CLAUDE_SKILL_DIR}/scripts/init_mbse_docs.py" --root "$(git rev-parse --show-toplevel)"

To scaffold specific hotspot subsystems:

python3 "${CLAUDE_SKILL_DIR}/scripts/init_mbse_docs.py" \
  --root "$(git rev-parse --show-toplevel)" \
  --subsystem supervisor-agent \
  --subsystem agent-adapter \
  --subsystem attention-router

Modeling Standards

Read references/standards.md before drafting diagrams.

Non-negotiable rules:

Prefer C4-style hierarchy for structural views: context -> containers -> components.
Use Mermaid in Markdown for diagrams unless a table is clearer.
Label relationships as command, query, event, state sync, or artifact flow.
Use real repo terms and file/package names, not invented abstractions.
Every model file must include an Evidence section with concrete paths.
Every model file must include Observed Smells or explicitly say none were found.
Keep diagrams readable: split views before they exceed roughly 15-20 nodes.
Class/module diagrams are for hotspot subsystems only, not the whole repo.

Workflow

1. Define Scope

Decide whether this run is:

full system refresh
top-level refresh only
hotspot decomposition for 1-3 subsystems

Start with top-level docs unless they are already current.

2. Collect Evidence Progressively

Use cheap signals first:

package and folder inventories
route and service lists
manifests (services.yml, subsystem-manifest.yml)
key entrypoints
a few hotspot files

Only then read deeper implementation files.

3. Refresh Top-Level Models In Order

Update these first:

00-scope-and-method.md
01-system-context.md
02-capability-map.md
03-container-view.md
04-runtime-interactions.md
05-state-machine-catalog.md
06-boundary-and-responsibility-smells.md
07-decomposition-candidates.md

Do not start subsystem deep-dives until the top-level story is coherent.

4. Select Hotspot Subsystems

Choose subsystems with one or more of:

god files / oversized coordinators
duplicated control logic
unclear state ownership
mixed policy + transport + persistence concerns
repeated operator confusion

Create or update subsystem folders only for those hotspots.

5. Decompose Each Hotspot

For each subsystem:

summarize purpose and scope
draw a component/module view
document 2-4 key sequences
capture state machines only if stateful behavior matters
list boundary smells and split candidates

6. Keep Stable Headings

When rerunning the skill:

update existing files in place
preserve stable section headings
add evidence and dates
avoid creating alternate versions like -v2, -final, -draft2

7. Diagnose, Don't Just Describe

Each modeling pass should leave the reader with:

what the subsystem owns
what it depends on
where boundaries leak
where control is duplicated
what decomposition would reduce complexity

Required Deliverables

At minimum, each run should leave:

updated docs/system-models/INDEX.md
updated top-level views for the scoped area
updated hotspot subsystem docs if decomposition was in scope
explicit smell findings and decomposition candidates

Common Pitfalls

Drawing target architecture instead of current architecture
Modeling everything at one level of detail
Making diagrams without evidence-backed narrative
Creating many one-off files instead of updating the fixed layout
Turning the docs into a changelog rather than a model
Confusing runtime containers with code packages

Final Output Format

System modeling updated in docs/system-models/

Scope:
- <top-level refresh / hotspot decomposition>

Views updated:
- <file>
- <file>

Hotspots modeled:
- <subsystem>

Primary smells found:
- <smell>
- <smell>

Recommended decomposition candidates:
- <candidate>
- <candidate>