Problem Tree syntax - Request For Comments

raymyers commented 1 year ago

Problem Tree (AKA Current Reality Tree) syntax RFC

The purpose of this issue is to gather feedback and counterproposals for TOC-Lang's Problem Tree syntax. We are currently in a prototyping phase where it is safe to break compatibility, so this is the best time to shape our notation for the future.

Please comment your thoughts, thanks!

Entities

Condition == A condition, potentially changeable, that may be in a causal relationship with other nodes
Undesirable Effect (UDE) == a condition we don't like
Desirable Effect (DE) == a condition we like
Fact Of Life (FOL) == a condition we do not believe we can change

Nodes are Condition (C) by default, other types are marked with class: as shown below

Relationships

There are causal relationship between conditions, which can take these forms

Single Cause == Simply something like "A causes result"
Joint Cause == An AND relationship like "result <- A && B"
Disjoint Cause == An OR relationship, implicitly represented with two statements "A -> result" "B -> result"

Currently there is an asymmetry on how AND and OR relationships are represented. That could be resolved by introducing an OR operator, but it would open the door for more complex statements "(A and B) or A1 cause result" - grouping and operator precedence would be needed.

Example Tree

bad: Bad user experience {
  class: UDE
}
cluttered: Cluttered interface
bad <- cluttered

ux: Low investment in UX design
features: Many features added
cluttered <- ux && features

salesPressure: "Pressure to increase sales"

enterpriseRequests: "Enterprise contracts are easier to close by promising new features" {
  class: FOL
}
features <- salesPressure && enterpriseRequests

increasedSales: Increased sales {
  class: DE
}

increasedSales <- features && enterpriseRequests

Check src/assets/grammars/toc-lang.peggy for the grammar specification.

raymyers commented 6 months ago

Historical note. The RC1 syntax shown below is now abandoned in favor of RC2 patterned after d2lang.

UDE bad is "Bad user experience"
C cluttered is "Cluttered interface"

cluttered causes bad
C ux is "Low investment in UX design"
C features is "Many features added"
ux and features cause cluttered

C salesPressure is "Pressure to increase sales"
FOL enterpriseRequests is "Enterprise contracts are easier to close by promising new features"
salesPressure and enterpriseRequests cause features

DE increasedSales is "Increased sales"
features and enterpriseRequests cause increasedSales

raymyers commented 6 months ago

Should update:

[x] Allow arrow in either direction

raymyers / toc-lang