13 KiB
Architectural Principles — Architecture Experiment 17
These principles have emerged from Experiments 1–17. They are not derived from external design frameworks. They are distilled from observed patterns across the investigation's own evolution.
A principle is only valid until an experiment disproves it. Record contradictions, not comfort.
Principle 1 — Every Layer Has One Responsibility
Source
Emerges from Experiments 10, 12, 14, 15, 16.
Statement
Each architectural layer performs exactly one type of work. It does not perform the work of adjacent layers, even when that would be convenient or efficient.
Derived From
- Graph captures knowledge; narrative translates it; assessment evaluates it; behaviour decides about it; conversation executes it; workspace projects it.
- When a layer performed two types of work (e.g., graph and narrative mixed), the architecture became fragile. Separating them made each layer independently testable and replaceable.
Implication
If you can describe a layer's work with "and" in addition to "to", it is doing too much. Split it.
Principle 2 — Information Flows Downward
Source
Emerges from Experiments 12, 14, 16.
Statement
Data flows unidirectionally down the architecture during a turn: graph → narrative → assessment → behaviour → conversation → workspace. Each layer transforms data for its audience but never pushes transformed data back to a previous layer during the same turn.
Derived From
- The graph is the source of truth. Narrative translates it for humans. Assessment evaluates the translation. Behaviour acts on the evaluation. Conversation executes the action. Workspace displays the result.
- Attempting to push state backward within a turn creates circular dependencies that break deterministic ordering.
Implication
A layer may read its own output and lower layers' inputs, but it never writes to a lower layer during the same turn. Cross-turn feedback (user responses) enters at the top through user input, not through architectural shortcuts.
Principle 3 — Feedback Flows Upward Through the User
Source
Emerges from Experiments 9, 10, 14, 15.
Statement
Information returns to lower layers only through the user. The user's next observation is the mechanism by which new information re-enters the system. No layer injects feedback directly into another layer during a turn.
Derived From
- The investigation is a conversation between human and machine. The conversation loop is the only legitimate feedback mechanism.
- Direct layer-to-layer feedback bypasses user awareness and creates hidden state mutations that are impossible to trace or audit.
Implication
If you need information from layer N+1 to affect layer N-1, go through the user: present it in the workspace, have the user process it, and let their next observation carry the updated understanding back down.
Principle 4 — Reasoning Never Communicates Directly With the UI
Source
Emerges from Experiments 08, 12, 13, 14.
Statement
The reasoning graph (the machine's internal representation) never directly drives UI components. All UI content passes through the investigation narrative, which provides human-appropriate translation regardless of graph schema changes.
Derived From
- Graph nodes use domain-specific categories (observations, unknowns, assumptions, metrics) that are useful for reasoning but not for presentation.
- The narrative layer proved essential: it is the only layer that understands both the graph's meaning and the user's need.
- When UI consumed the graph directly (Experiment 10), developer statistics leaked into user-facing panels.
Implication
The narrative is the contract between reasoning and presentation. Change the graph schema freely — as long as the narrative preserves its fields, the UI never breaks.
Principle 5 — Behaviour Never Reasons
Source
Emerges from Experiments 15, 16.
Statement
Behaviour selection operates exclusively on investigation state (assessment), never on graph content or reasoning results. A behaviour's decision about what to do is based on where the investigation is, not on what the graph says.
Derived From
- Experiment 16 proved that behaviour selection inspecting graph nodes directly couples behaviour to reasoning implementation. Graph schema changes break behaviour decisions.
- When behaviour reads assessment instead of graph, it remains correct regardless of how the graph represents knowledge internally.
Implication
If you can describe a behaviour's logic using "because the graph has node X with status Y," it is reasoning disguised as behaviour. It should read: "because the assessment shows phase F and progress P."
Principle 6 — Presentation Never Interprets
Source
Emerges from Experiments 12, 13, 14.
Statement
Workspace panels render what the narrative provides. They do not re-filter, re-rank, or re-classify content. Panels control how things are shown (layout, emphasis, visibility), not what is shown.
Derived From
- When each panel reimplemented its own filtering logic (Experiment 13), different panels showed contradictory information about the same investigation state.
- A single narrative object consumed by all panels eliminates this class of inconsistency.
Implication
If two panels show different facts about the same investigation, the problem is not the panels — it is that they are consuming different narratives. They must consume the same narrative and differ only in presentation choices (order, emphasis, visibility).
Principle 7 — Assessment Never Generates Evidence
Source
Emerges from Experiment 16.
Statement
The assessment layer describes what the investigation has already established. It never creates new evidence, makes new inferences, or proposes new hypotheses. It only evaluates existing state.
Derived From
- The assessment's role is to provide an accurate mirror of investigation state so that behaviour selection can operate on reality, not on the assessment's own judgments about what might be true.
- When the assessment generates evidence (even implicitly by treating "unknown" as "probably false"), behaviour selection acts on invented information.
Implication
Assessment signals are descriptive only: "this is unknown" not "this is probably X." The distinction between "we don't know" and "we know it's not true" must be preserved at every level.
Principle 8 — Narrative Never Invents Facts
Source
Emerges from Experiments 13, 14.
Statement
Every element in the narrative must be traceable to one or more graph nodes. The narrative may reorganise, prioritise, deduplicate, and translate — but it may never include content that does not exist somewhere in the reasoning graph.
Derived From
- Experiment 13 proved that semantic filtering and deduplication improve presentation without inventing content.
- When narrative synthesis exceeded graph support (e.g., connecting two observations that were never linked by an edge), the facilitator appeared to be hallucinating connections.
Implication
If you can trace a narrative statement back through the narrative structure to specific graph nodes and edges, it is valid. If not, it must be removed regardless of how useful or coherent it seems.
Principle 9 — Assessment Describes, Never Prescribes
Source
Emerges from Experiment 16, Principle: "Signals Are Descriptive, Not Prescriptive."
Statement
The assessment layer reports state using neutral, descriptive language. It never says "therefore the next step should be X." It says "the investigation is in state S along dimension D." The interpretation belongs to behaviour selection.
Derived From
- A prescriptive assessment becomes a decision tree in disguise, locking the architecture into one strategy for interpreting state.
- Descriptive assessment supports multiple strategies: deterministic rules, weighted scoring, LLM-assisted reasoning — all reading the same output.
Implication
Assessment language must survive replacement of the behaviour selection strategy. If the assessment says "Stalled" instead of "You should pause," it passes this test. If it says "Use Pause because progress has stopped," it fails.
Principle 10 — Convergence Over Single Signals
Source
Emerges from Experiment 16, Principle: "Convergence Matters More Than Any Single Signal."
Statement
Behaviour selection should prefer actions supported by multiple independent assessment dimensions over actions supported by a single strong signal. Convergent signals are more reliable than any individual dimension's threshold.
Derived From
- A single dimension reaching a threshold (e.g., Evidence Quality: Contradictory) can produce false positives in edge cases.
- Multiple dimensions agreeing on a pattern (e.g., Stalled progress + Repetitive conversation + Confused understanding) indicates a robust state that warrants intervention regardless of any one dimension's reliability.
Implication
Behaviour confidence should be proportional to the number of converging signals, not the strength of the strongest signal. High-confidence actions require multiple supporting dimensions; low-confidence actions are appropriate for single-signal triggers.
Principle 11 — Assessment Is Stateful Across Turns
Source
Emerges from Experiment 16, Principle: "Assessment Is Stateful Across Turns."
Statement
The assessment accumulates state across turns. It tracks change (deltas), sequence patterns (repetition), trend direction (acceleration), and phase transitions. A turn-by-turn stateless assessment cannot detect looping, spiralling, or convergence.
Derived From
- Investigation state is inherently temporal. "Stalled" means nothing without knowing what came before it.
- The assessment must carry forward state between turns to enable pattern detection across the investigation's history.
Implication
The assessment's data structure must include turn-level history (not just the current snapshot). The minimum viable history is: phase per turn, resolution count per turn, and response length per turn. Trends emerge from sequences, not snapshots.
Principle 12 — Uncertainty About Assessment Is Itself Assessable
Source
Emerges from Experiment 16, Principle: "Uncertainty About Assessment Is Itself Assessable."
Statement
When the assessment cannot reliably evaluate a dimension (insufficient data, conflicting signals, rapid state changes), it should express uncertainty explicitly rather than guessing. The behaviour layer receives "Cannot determine" as a valid signal.
Derived From
- False precision in assessment produces false confidence in behaviour. An overconfident but wrong assessment is worse than a transparently uncertain one.
- User-facing confidence must match the system's actual certainty, including its uncertainty about its own certainty.
Implication
Assessment outputs must include a confidence field per dimension. "Phase: Exploring (confidence: low)" is more useful than "Phase: Exploring (confidence: high)" when the data supports only weak classification. The behaviour layer should treat low-confidence assessments as invitations for conservative action.
Principle 13 — Investigation Progress Is Qualitative Not Quantitative
Source
Emerges from Experiments 10, 15, 16.
Statement
Investigation progress is measured by the quality of understanding, not the quantity of resolved nodes. A single resolved critical unknown provides more investigative value than ten peripheral ones. Progress is trajectory and depth, not count.
Derived From
- Early experiments focused on node counts (Experiment 10). This proved misleading: a graph can grow large while understanding remains shallow.
- Expert investigators measure progress by "do we understand the situation better?" not "how many items do we have left?"
Implication
The assessment should evaluate whether new information clarifies existing understanding or merely adds data points. Understanding compounding (new insights that reframe previous ones) is a stronger progress signal than evidence accumulation.
Principle 14 — The User Is Part of the Architecture
Source
Emerges from Experiments 9, 10, 15.
Statement
The user is not an external actor who feeds data into the system. The user's cognitive state (confidence, confusion, engagement, insight) is a first-class architectural input that affects every subsequent turn. The architecture must model and respond to the user as an active investigation participant.
Derived From
- Experiments consistently showed that user psychology drives investigation outcomes more than graph mechanics do.
- A technically perfect graph on confused or disengaged data produces worthless results.
Implication
Every layer should ask: "How does this affect the user's ability and willingness to continue investigating?" If a layer improves graph accuracy but degrades user engagement, it has traded investigation quality for internal elegance — and lost.
Recording Note
These principles emerged from the investigation's own evolution through 17 experiments. They are not imported from external sources. They will be validated or contradicted by future implementations. Record which principle is challenged first — it will be the most informative.