Conversational YAML — version 1

Write schema_version: 1. This format is independent of the Reason Commons app. Keep one working file plus generated snapshots; omit unused trees and optional fields. Do not copy example participants or claims into a new project. Preserve existing content when updating an unversioned draft; do not silently reinterpret an unfamiliar schema version. Nodes lacking status in an earlier draft are proposed, never implicitly accepted; add their explicit status when editing them.

Shape

schema_version: 1
project: Quote turnaround
driver: alice
participants:
  alice: Alice
  bob: Bob
active_tree: current_reality
trees:
  current_reality:
    nodes:
      - id: n1
        kind: undesirable_effect
        text: Customers often wait more than three days for quotes.
        status: proposed
        contributions:
          - {by: bob, attribution: explicit, mode: text}
      - id: n2
        kind: cause
        text: Sales often waits for pricing approval.
        status: proposed
        contributions:
          - {by: alice, attribution: driver_default, mode: text}
    links:
      - id: l1
        from: [n2]
        to: n1
        relation: contributes_to
        status: proposed
        contributions:
          - {by: bob, attribution: explicit, mode: text}
    backlog:
      - ref: n1
        work: connect_or_explain
      - ref: l1
        work: test_causality

driver names a configured participant; active_tree names a tree present in the file. Each tree has nodes, links, and backlog lists, which may be empty. Give nodes and links stable IDs unique across the whole file. All ID references must resolve.

Node kinds

Use these exact tree keys and kinds. observation is also allowed in every tree for relevant material whose role is not yet clear; revisit it when useful rather than forcing a classification.

In a conflict cloud, prerequisite represents either of the incompatible actions or positions believed necessary to meet the respective needs. In future reality, injection is the proposed change; predicted_effect is an intermediate consequence, and undesirable_effect describes a potential harmful consequence. These kinds describe roles, not truth or acceptance.

Each node has id, kind, text, status, and contributions. Node capture records a contribution, not a verified fact.

Links and attribution

Each link has id, from (a list of node IDs), to (one node ID), relation, status, and contributions. Link endpoints belong to that tree. Multiple IDs in from mean conditions operating together (AND); alternative paths use separate links.

Use a clear relation such as necessary_for, causes, contributes_to, conflicts_with, overcomes, produces, or precedes. Read it from source to target: a condition is necessary for an objective, an intermediate objective overcomes an obstacle, an action produces an effect. A precedes link states order, not causation.

New nodes and links are proposed. Explicit endorsement makes them accepted, with accepted_by: [alice] recording human participant IDs. A clearly identified fragment may be accepted together. A substantive objection makes the item disputed. An accepted link requires all its endpoints to be accepted; when a node loses acceptance, return its accepted incident links to proposed. Follow the skill's conversational acceptance rules. Existing accepted_by may remain on a disputed item as a record of prior endorsement; only status: accepted determines inclusion in accepted views.

Each contribution has by (a participant ID or reserved value assistant), attribution (explicit, speaker_label, driver_default, or assistant), and mode (text, voice, or unknown). by identifies the originator of the idea, not whoever serialized it. The example link therefore belongs to Bob. Keep all contributors when combining genuine duplicates.

Nodes and links may have assumptions: [{text: ..., by: ...}] and challenges: [{text: ..., by: ...}]. Here too, by identifies the participant or assistant who supplied the content. A challenged node can carry status: disputed. Keep authorship separate from endorsement.

Backlog is reasoning work

Each entry has ref (a node or link ID in this tree) and work (a short description of the remaining work). Useful labels include connect_or_explain, test_causality, resolve_challenge, and examine_assumption; these are examples, not an exhaustive vocabulary. Multiple tasks may reference the same item.

Assumptions and challenges stay on their owning node or link. Reference that owner in the backlog and add an optional note identifying the particular assumption or objection when needed. They do not need separate IDs.

For example, an unresolved objection to l1 would add {ref: l1, work: resolve_challenge}. Keep work visible while it remains unresolved, even when the tree already has many links. Remove items from the backlog when their relevant reasoning has been addressed; drawing an arrow alone does not finish an item.

Backlog is independent of acceptance: accepted items with remaining work stay visible in accepted diagrams. Proposed and disputed items are excluded even if the backlog contains no task for them.

Cross-tree traces

Nodes may optionally contain lists of node IDs from any tree:

Use only existing IDs and meaningful traces supported by the discussion. These fields express intended relationships, not proof that a solution works or that a causal claim has been accepted. Test substantive reasoning through proposed links, assumptions, and challenges. No cross-tree link is required merely to fill out the model.

Snapshots

The helper copies the complete working state, including WIP, into each immutable snapshot triggered by an accepted change. It adds revision, previous_revision (null for the first), and change containing at, driver, summary, and affected trees. These fields belong to snapshots; the working file does not need to maintain them. History preserves previous wording and removed items without superseded_by or embedded history fields. See views.md for generation and comparison rules.