OrgLens: models, checks, and organisational judgement
OrgLens turns accounts of an organisation into a report through three systems lenses. Doug Belshaw’s source repository describes an experiment tested on fictional organisations, simulated participants, and AI judges. Its usefulness in a real organisation remains to be established.
OrgLens (formerly VSMkit) · Open the tool · Plain-English guide
Follow the evidence through the pipeline
The technical account separates four operations: a model represents what people said; code checks that representation; fixed wording describes the findings; and a language model writes a report that receives further quotation and consistency checks. A correct quotation establishes that the words were present. It does not establish that the speaker’s account was complete or that the diagnosis follows.
| Lens | What the source implements | What still requires judgement |
|---|---|---|
| Structure | Checks for recorded operations, coordination, control, audit, intelligence, policy, and channels. | Whether a missing model element reflects a missing capability, poor questioning, or an inappropriate system boundary. |
| Feedback | Loop sign, delays, and archetype rules combining graph structure with variable roles. | Whether the causal links hold, how strong they are, and what behaviour their interaction produces over time. |
| Perspectives | CATWOE accounts, different success measures, unheard groups, and is/ought boundary answers. | Who was able to speak, whose interpretation prevailed, and whether an attributed ought says what the report claims. |
Source locators: structure checks; loop and archetype checks; perspective checks. Repository revision 6ab72502. Code was inspected; the complete experiment was not rerun.
Use the differences between the lenses
The lens-selection survey explains why the project added feedback and perspective checks. Its compressed descriptions of the parent methods also need scrutiny. For example, treating VSM as assuming an uncontested purpose would turn a modelling choice into a property of the method. A finding about an interview representation cannot settle a dispute about an organisation.
Compare Viable System Model (VSM), System Dynamics, Soft Systems Methodology (SSM), and Critical Systems Heuristics (CSH). The tool selects parts of these traditions; it does not replace their broader practice.
Questions for a practitioner
- Invite the people described to correct the model and identify voices it missed.
- Separate the report’s quotations, inferences, and suggested actions.
- Check a proposed causal pattern against events over time and competing explanations.
- Find who could authorise the suggested change and what constraints they face.
- Record what happened after using the report, including harm, disagreement, and conclusions that failed.
These are editorial questions for using a diagnostic aid, not findings from OrgLens trials.
Evaluation, data, and reuse
The project’s evaluation account reports experiments on three fictional cases. Simulated reader clarity and checked quotations do not demonstrate organisational improvement. Its README also says submitted material goes to third-party model services and asks users to leave out private information; consult the current service before using it.
The repository states GNU AGPL version 3 or later. This guide links and paraphrases; no OrgLens code is included in the atlas. The earlier development article supplies a separate account of the plain-language reporting work.