text-flowcharts

Text Decision-Tree Flowcharts

Why this exists

A branching process is far faster to grasp as a picture than as prose. One record enters at the top, falls through conditions, and lands on an outcome — the reader sees every path and every dead end at a glance. Plain text keeps that picture intact, so it survives in a PR comment, a code comment, a Markdown doc, or a terminal with zero tooling and no rendering step.

Reach for this skill whenever a process has more than one branch. If the flow is a straight line with no decisions, a bullet list is fine — don't force a diagram onto something that isn't branching.

The core idea: per-record view

Draw the journey of one item (one row, one request, one address) from entry to outcome. Top = input. Each { condition? } splits the path. Every leaf is a terminal outcome with a graded end-state. This "follow one record down" framing is what makes the diagram click — the reader mentally drops a single item in the top and watches where it falls.

Glyphs

Keep the vocabulary small and consistent — consistency is what makes these scannable across a whole document.

(start) <label>        entry point / the record arriving
[ action ]             a process step — what gets done
{ condition? }         a decision — always end with "?"
  │ ─                  vertical / horizontal flow lines
  ▼ ▲ ▶ ◀             directed flow (down / up / right / left)
  ├── <label> ──▶      a labelled branch off a decision (mid-list)
  └── <label> ──▶      the last branch off a decision
  ┌ ┐ └ ┘             corners — turn a line 90°
  ├ ┤ ┬ ┴ ┼           junctions — split (├┬), merge (┤┴), or cross (┼)
  ~~▶                  async / deferred edge (work handed to a later stage)
  @module.func()       annotate which function/tool performs a step
(end √) <outcome>      terminal: normal success / the wanted output
(end >>|) <outcome>    terminal: skipped on purpose (not an error)
(end ×) <outcome>      terminal: dead end / rejected / unresolvable