Human Draw

/human-draw

A figure is a material. It is characters on a monospace grid, read by a person scanning rather than parsing. Everything here is about what that material can actually hold.

Two facts set every rule below.

1. The grid is about 80 columns wide and one character deep. Cross it and

the terminal wraps the line, shearing the figure into unreadable halves.

1. The reader stops wherever they stop — the family's stopping-point

doctrine, references/human-contract.md §2. So a figure must be correct at a glance and still correct on a second look.

Placement: the rule that matters most

Three parts, always in this order.

  verdict sentence  ->  figure  ->  caption stating the finding

A reader who never looks at the picture must still be correct. That is the whole test, and it is the stopping-point doctrine applied to a figure. A figure is evidence for a claim someone else already made in words; it is never the claim itself.

The verdict above and the caption below are prose. Use human-output when it is installed; otherwise use the portable style floor in [references/human-contract.md](references/human-contract.md), including what a caption must name (the finding, not the subject). This file owns only what is inside the fence.

The default is to draw

Draw when the reader must hold two or more things in mind and relate them. One fact is a sentence. A causal argument is prose. Position, proportion, sequence, containment, and adjacency are figures.

There are exactly two refusals, and both are refusals because the picture would lie:

• Dishonest encoding. Any visual property asserting something you did not

measure. Equal-width boxes claiming equal durations. Node size claiming an importance nobody ranked. A smooth curve through four points claiming continuity. Decimal precision on an estimate. Redesign until every visible property maps to a measured quantity, or state the numbers in text instead.

• Crossing lines. A crossing means the structure is not flat and the layout

is lying about it. Re-order to remove it. If it will not go, hand back an adjacency table (from / to), which holds arbitrary tangle without deceiving anyone.

Everything else downgrades to a simpler shape. A refusal hands a text-fatigued reader back the wall of text that caused the problem.

| What is wrong | Do this, do not refuse | |---|---| | More than 7 nodes | Aggregate first, then overview plus one detail frame | | A table sits beside it saying the same thing | Delete the table, keep the picture | | It needs a legend to be read at all | Label in place; a legend is a promise the reader will look away and come back, and they will not | | Items share one attribute set | That material is a table — draw the part that is proportional, tabulate the rest | | Values are missing | Draw the gap at low resolution and mark it; see below | | The shape is a straight line of three steps | Say it in a sentence, keep the figure for the branching part |

Show what is absent

A blank space reads as "nothing there", which is usually false. Absent and unreadable are different claims, and the reader must be able to tell them apart.

• [?] — territory that exists and has not been surveyed. Annotate why.
• [~] — territory deliberately not taken: parked, deferred, rejected. It

stays visible because the reader may want to go back to it, and because a route drawn without its alternatives looks inevitable when it was chosen.

Never silently omit either. A leg you skipped drawing is a leg the reader will never ask about. Never place a node or a bar to make a layout balance.

Materials: printable ASCII only

Every glyph inside a figure must be printable ASCII, 0x20 to 0x7E.

The reason is specific, and it is not aesthetic conservatism. Box-drawing characters, block elements, Unicode arrows and emoji are classified by Unicode as East Asian Ambiguous. Under a Chinese, Japanese or Korean (CJK) locale, and under many default terminal fonts, they render double-width. One such glyph shifts every character after it on that line, and only that line, so every column below it shears. It looks perfect in your terminal and arrives broken in theirs.

| Job | Glyphs | |---|---| | Horizontal run, connector | - = . | | Vertical run | \| | | Corner, junction | + | | Branch end, last child | ` ` | | Arrowhead | > not a single-glyph arrow, OK / no not tick and cross, deg` not a degree sign, and a spelled currency code not a symbol. Spaces only, never tabs — tab width varies by terminal.

One exemption. A skill that ships its own machine-checked glyph contract governs its own figures; the orient family's bundled glyph contract is the example. Absent such a contract, stay in ASCII.

Materials: the grid

• Hard limit 80 columns. Target 64. The spare 16 absorb a quoted reply

(> prefixes), a narrow pane, or an indent.

• Nothing load-bearing past column 72. If the line wraps, columns 0 to 72

are what survives intact.

• Prefer vertical growth. A tall figure scrolls; a wide figure wraps.

Wrapping destroys, scrolling does not.

• Whitespace is structure. Fix a label width once — 15 is a good default —

and pad every label to it. Alignment is what lets the eye scan a column without reading it.

• Fence the figure, and leave one blank line above and below. Outside a

fence, markdown collapses runs of spaces and the alignment is gone before it reaches the eye.

• Trim trailing spaces. Invisible now, ugly on paste.

Materials: line weight

The cheapest extra channel a text figure has. Declare the key inside the figure whenever more than one weight appears.

| Weight | Means | Written | |---|---|---| | heavy | confirmed, actual, recommended path | A ==> B | | medium | ordinary, expected | A --> B | | light | inferred, proposed, uncertain | A ..> B |

Leader dots (....) connecting a label to its number are the same light channel doing a second job; context separates them and readers do not confuse the two.

Materials: proportion arithmetic

Do not eyeball a bar. Compute it.

  cells = round( value / max_value * track_width )

• Fix track_width once per figure. Then pick a scale that divides

cleanly. A round number of units per cell — 2 L, 20 mm, 5 days — keeps every bar exactly proportional. Ragged rounding at short bars is the commonest way a figure contradicts its own labels.

• Print the number beside its bar, always. The bar carries the shape, the

number carries the fact. Never make the reader measure, and never make them look elsewhere.

• Round percentages by largest remainder so the column sums to 100. Take

the floor of each share, then give the spare points to the largest remainders in order. A column summing to 101 costs the reader's trust in everything else in the figure.

• A value under one cell prints as a single ., never as nothing.

The seven shapes

Compose from these. Do not invent an eighth unless none of them holds the information.

| Shape | Holds | Reach for it when | |---|---|---| | bar | magnitude, proportion, share | "how much of each" | | spine | ordered sequence, stages | "what happens in what order" | | tree | containment, decomposition | "what is made of what" | | lane | parallel tracks on one shared axis | "who or what, when" | | fork | branching outcomes, contingency | "if this, then what" | | matrix | two axes at once, positional | "where does each option sit" | | small-multiple | one frame repeated across cases | "how does each one behave" |

---

bar — magnitude and share

The shower is half the household's water; every fix below it is noise.

  Household water use             142 L per person per day

  Shower         ########################   48 L   34%
  Toilet         #################          34 L   24%
  Laundry        #############              26 L   18%
  Kitchen tap    ##########                 20 L   14%
  Outdoor        #######                    14 L   10%
                 |         |         |
                 0         20        40 L

  [fig bar | 5 rows | 58 cols | ascii | parts sum 142 L | pct 100]

Caption: A low-flow head saves more than every other change combined.

Craft notes:

• Label field is 15 wide, so every bar starts on the same column. Bars that

start on different columns read as noise.

• Track width 24 at 2 L per cell. 48 L is 24 cells, 34 L is 17, 26 L is 13,

20 L is 10, 14 L is 7. Every ratio is exactly 0.5 cells per litre because the scale was chosen to divide the values cleanly.

• Ticks sit at track cells 0, 10 and 20, which is 0, 20 and 40 L. Tick labels

are left-aligned on their tick so they stay inside the track's own span.

• Largest-remainder working: raw shares are 33.80, 23.94, 18.31, 14.08, 9.86.

Floors are 33, 23, 18, 14, 9 and sum to 97. The three largest remainders are toilet, outdoor and shower, so each gains one point. The column sums to 100.

• Sort descending. An unsorted bar chart makes the reader do the sorting.

---

spine — ordered sequence

Two thirds of the season is waiting; all the labour is at the two ends.

  Spring barley, one hectare     168 d sowing to store, 29 h work

  o-- Seedbed and sowing ........   4 d    9 h
  |
  o-- Emergence and tillering ...  49 d    3 h  *
  |
  o-- Stem extension ............  30 d    4 h
  |
  o-- Ear emergence .............  21 d    2 h
  |
  o-- Grain fill ................  52 d    0 h
  |
  X-- Harvest and dry ...........  12 d   11 h

  * a wet April moves tillering, and every stage below it, by 10 d

  [fig spine | 6 stages | 66 cols | ascii | parts sum 168 d and 29 h]

Caption: Hire the combine against the harvest window, not the sowing date — the one stage that moves is upstream of it.

Craft notes:

• Vertical, not horizontal. Six stages laid left to right need roughly 90

columns and wrap into rubble. Vertical spines grow in the direction that costs nothing.

• o for a waypoint, X for the terminal state. The reader sees where the

sequence ends without reading a word.

• Two numeric columns, both right-aligned: elapsed time and attention cost.

Right-alignment is what makes 4 d and 49 d comparable at a glance.

• The * marks the one stage carrying variance and its footnote sits **inside

the figure**. A caveat that changes how the figure is read belongs in it.

---

tree — containment and decomposition

Schools take 38 pence of every euro, and four fifths of that is salary.

  Riverton town budget 2026    EUR 48.2 M
  |
  +-- Schools .................... 18.4 M   38%
  |   +-- Staff .................. 13.1 M
  |   `-- Sites and transport ....  5.3 M
  +-- Roads and water ............ 11.9 M   25%
  +-- Health and social care .....  9.6 M   20%
  +-- Administration .............  5.1 M   10%
  `-- Reserve ....................  3.2 M    7%

  [fig tree | 7 nodes | 47 cols | ascii | parts sum 48.2 M | pct 100]

Caption: No non-staff cut inside schools can reach one percent of the budget.

Craft notes:

• +-- for every child, ` -- `` for the last child at a level. The backtick

corner is what stops the eye; without it the reader cannot see where a subtree ends.

• The | continuation column under Schools is mandatory while a sibling

follows. Drop it and the sub-items appear to belong to the root.

• Children sum to their parent (13.1 + 5.3 = 18.4) and the top level sums to

the header (48.2). State the total in the header. A decomposition whose parts do not visibly sum is one the reader has to audit.

• Two levels is comfortable, three is the maximum before the indent eats the

label field. At four, split into overview plus detail.

---

lane — parallel tracks on one axis

The grill is at capacity for ninety minutes while the kitchen prep station is idle.

  Saturday dinner service        three stations, 18:00-22:00

  Kitchen prep  |####====................|
  Grill         |..==########====###=....|
  Front of house|....========#######==...|
                 |     |     |     |     |
               18:00 19:00 20:00 21:00 22:00

  . quiet        = steady        # at capacity

  [fig lane | 3 tracks | 60 cols | ascii | 24 cells each, 10 min per cell]

Caption: Move one prep hand to the grill at 19:30 and the capacity band disappears.

Craft notes:

• This is the shape most likely to break, because **three lines have to agree

on the same columns**: the track, the tick row, and the label row. Build it from fixed numbers, never by nudging spaces.

• Label field is columns 2 to 15, opening | at 16, track at 17 to 40,

closing | at 41.

• A tick at column c marks the left edge of column c. Ticks fall every 6

columns — 17, 23, 29, 35, 41 — so each marks one hour. The last sits on the closing pipe because a tick marks a boundary, not a cell.

• Each time label is 5 characters, started 2 columns left of its tick to

centre it. The single spaces between labels then fall out on their own.

• Every track must be exactly the same character count. Count them. One

short track silently tells the reader that station finished early.

• Three density levels is the limit. Nobody can rank five shades of #.
• Lanes stay narrow by choosing a coarse time resolution, never by shrinking

the label field.

---

fork — branching outcomes

Replace the roof: repairing costs more over ten years and carries the uncertainty as well.

  Slate roof, 38 years old              recommendation: replace

                +--> repair ........ EUR 4 k now
                |      |
                |      +--> holds 6 yr ...... 50% .. then EUR 22 k
                |      `--> fails in 2 yr ... 50% .. then EUR 24 k
  38-year-old --+
  slate roof    |
                `==> replace ....... EUR 19 k now
                       |
                       +--> holds 40 yr ..... 95% .. EUR 0 further
                       `--> flashing rework .  5% .. EUR 2 k

  10-year expected cost:  repair EUR 27 k   replace EUR 19.1 k

  [fig fork | 6 nodes | 66 cols | ascii | expected costs computed below]

Caption: Repair is dearer in expectation and it is the branch that can still surprise you.

Craft notes:

• The recommended branch is ==> and the alternatives are -->. The reader

sees the recommendation before reading a word of it. This is where weight as an encoding earns its keep hardest.

• Both branches are drawn to the same depth. An undrawn branch reads as the

wrong one, which silently makes the decision for the reader.

• Probability and consequence sit on the same line as their outcome. Never a

legend of probabilities underneath.

• The bottom line is a sentence, not a shape. Repair is

4 + 0.5(22) + 0.5(24) = EUR 27 k. Replace is 19 + 0.05(2) = EUR 19.1 k. A fork makes branches comparable; the comparison itself is one line of arithmetic. Do not try to draw the expected-value calculation.

---

matrix — two axes at once

Only the terrace is both cheap and reversible; everything else buys capacity by locking the business in.

  Cafe capacity, four options       cost against reversibility

                              high cost
                                  |
   Build an extension             |   Buy the unit next door
   EUR 140 k, 18 months           |   EUR 210 k, lease to 2041
                                  |
  hard to reverse ----------------+---------------- easy to reverse
                                  |
   Longer opening hours           |   Outdoor terrace licence
   EUR 9 k a year, staff churn    |   EUR 3 k, renew each year
                                  |
                              low cost

  [fig matrix | 4 options | 67 cols | ascii | axes: cost x reversibility]

Caption: *Try the terrace for one season; it is the only o

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: allemaar
• Source: allemaar/open-skills
• License: Apache-2.0
• Homepage: https://allemaar.com

Install and usage instructions live in the source repository linked above.