01 / Definition Term

DEFINE: Human Readabilitycore

=Human Readability — the degree to which text is understood without effort =NOT the same as legibility (font clarity) or comprehension (intelligence) =determined by: structure, typing, density, scan path !prose is readable to a human who reads it — not to one who scans it!! →CLN maximises readability at scan speed, not read speed

INFO-VIZ: Readability spectrumscan vs read

Time-to-meaning by format

Prose~30s to scan

Markdown (rendered)~15s to scan

CLN (operator column)~3s to scan

Scan path: left column first

=

↓

.

↓

!

↓

→

eye path

02 / Operator Set — 12 semantic types Core

DEFINE: All 12 operators — live demoCLN v2.3

// Tier 1 — Signal & Action =definition / essence — "what is it?" .action / step — "what to do?" →result / output — consequence, next state !risk / warning — "what can go wrong?"!! ~tension / paradox — unresolved trade-off // Tier 2 — Evaluation +pro / advantage — what's for it✓ confirmed -con / disadvantage — what's against it ?unknown / hypothesis — open question☐ open

// Tier 3 — Context @metadata / status — who · when · where |resource / tool — "with what?" *note / context — "by the way" // Tier 4 — Completion .migrate to new auth service#infra✔ done .write integration tests#backend☐ wip !DB migration blocked — no rollback plan!! // Start with 4 →begin with: = . ! ? — add others as needed

03 / Line Anatomy — 5 slots Structure

Slot 1 Operator = . ! ? → ~ + - required

Slot 2 Content the fact text required

Slot 3 Tags #backend #urgent optional

Slot 4 Anchor ##redis-deploy ★ v2.1

Slot 5 Marker ✔ ☐ !! optional

EXAMPLE: Full line anatomyall 5 slots

.Deploy Redis cache layer #infra ##redis-deploy☐ plan |kubectl apply -f redis-cluster.yaml #k8s !needs »[addressing system] merged first @owner: ops-team · deadline: 2026-03-14 *parser reads right-to-left: strip Marker → Anchor → Tags → Content

04 / Block Accent Stripes Visual Grouping

DECISION: Choose caching strategyblock-demo

// 01 Context =need caching for 200k req/min read-heavy API @constraint: ops team of 2 · no Kubernetes yet // 02 For Redis +sub-millisecond latency · battle-tested✓ verified +pub/sub built-in — future websocket use // 03 Against Redis -cluster mode adds ops overhead -memory-only — expensive at scale // 04 Tension ~performance ceiling vs operational simplicity // 05 Open ?is Memcached simpler at current scale?☐ spike // 06 Verdict →Redis standalone now · cluster at >500k req/min✓ decided

INCIDENT: Post-mortem INC-2026-041nested-blocks

// Timeline @09:14 — alerts: 5xx spike on /api/search @09:22 — on-call paged · root cause found @09:38 — hotfix deployed · 100% recovery // Root cause !Elasticsearch index mapping mismatch after deploy!! *migration script ran but index not rebuilt -no smoke test for search after deploy -staging uses smaller index — didn't catch it // Actions .add post-deploy smoke test for /api/search☐ .staging index must match prod size >10k docs☐ @owner: Elena · due: 2026-02-28

05 / Addressing System v2.1 ##id · »link

PROJECT: CLN Parser — dependency chainlive addressing

// ##a-nav Navigation .»[Context]##a-ctx .»[Risks]##a-risks .»[Tasks]##a-tasks // ##a-ctx 01 · Context =Python reference parser for CLN v2.3 @stack: Python 3.12 · pytest · no external deps // ##a-risks 02 · Risks !table parser not yet integrated##r-tables!! @mitigation: stub returning raw text☐ next ?spoiler tokens: regex or state machine?☐ open // ##a-tasks 03 · Tasks .tokenizer core##t-tok✔ done .addressing system##t-addr☐ wip !needs »[table risk]##r-tables resolved .table parser☐ next *depends on »[addressing]##t-addr passing

DEFINE: 3 primitivesv2.1

=// labels → name the Block (Room) =## anchors → name the Line (Spot) =» links → navigate between (Path) =ID rules: [a-z0-9-_]+ · no spaces · unique !duplicate IDs break link resolution

06 / Parallel Blocks v2.2 ( ) syntax

COMPARE: Three approaches to state managementparallel ( ) demo

= Redux

=single global store +predictable · time-travel debug -boilerplate-heavy !overkill for small apps

. Zustand

=minimal store · hooks-native +tiny API · no context wrapping -less DevTools support →best for mid-size apps

~ Jotai

=atomic state · bottom-up +granular re-renders ~atoms can become implicit dependencies ?scales to large teams?☐

→Zustand for this project · revisit at 50k DAU✓ decided

*consecutive ( ) blocks at the same indent → flex-row rendering. Single block = plain group.

07 / Tables v2.3 — ((( ))) / (( )) NEW

COMPARE: CLN features by version((( ))) live table

Feature	v2.1	v2.2	v2.3
Operators (12)	✓	✓	✓
##id anchors + »links	✓	✓	✓
Parallel blocks ( )	—	✓	✓
Inline spoilers ‖ ‖	—	✓	✓
Tables ((( )))	—	—	✓ NEW

*use tables when cells are scalar · one value each · would draw in Excel

ANALYSIS: Format selection heuristictable vs blocks

// Use ((( ))) tables when +fixed column schema across all rows +cells are scalar — one value each +reader scans vertically (compare columns) // Use ( ) blocks when .content is hierarchical with CLN operators .cells need multi-line + nested operators .items are conceptually equal but not tabular ?Would you draw it in Excel? →Yes → table · No → blocks

08 / Inline Spoilers v2.2 — ‖ text ‖ Self-Test

GUIDE: Human readability — self-test|| || demo — click to reveal

*Q: What is the most important cognitive act in note-taking? Classification. Operator = type before content. *Q: Which CLN operator marks a risk? ! (bang) — red, always flagged *Q: What does ~ signal? Tilde = unresolved tension / trade-off without verdict *Q: When should you use a table vs parallel blocks? Table: scalar cells, fixed schema. Blocks: hierarchical, multi-operator content. =Rule: one fact per line violating this creates cognitive debt — reader can't classify the line !if you can't assign an operator, you didn't understand the fact this is the hardest rule to follow — and the most valuable

09 / Code Fences — ─── Data Embedding

TASK: Configure observability stackfence demo

Phase 1 — Config

=set up structured logging for all services |logging.config.json · type: json { "level": "info", "format": "json", "fields": ["timestamp", "service", "!trace_id"], "outputs": ["stdout", "=loki"] } !symbols inside fence (! = -) are NOT CLN operators✓ by design

Phase 2 — Deploy

.deploy Grafana + Loki stack☐ |helm upgrade --install loki grafana/loki-stack →dashboards auto-provisioned from ConfigMap .validate log ingestion☐ |curl -X POST http://loki:3100/loki/api/v1/push

10 / CLN vs Prose vs Markdown Summary

COMPARE: Format properties — full spectrum((( table )))

Property	Prose	Markdown	CLN v2.3
Human readability (raw)	✓ narrative	⚠ raw noise	✓ always
Scannability	✗ must read all	⚠ headers help	✓ operator col
Semantic typing	✗ implicit	✗ visual only	✓ operator = type
Portability	✓ everywhere	⚠ renderer needed	✓ everywhere
Data embedding	✗ messy	⚠ code blocks	✓ ─── fencing
Internal linking	✗ prose ref	⚠ md anchors	✓ ##id + »link
Parallel structures	✗ lists only	✗ lists only	✓ ( ) blocks
Tabular data	✗ awkward	⚠ rendered only	✓ ((( ))) tables
Self-test / deferred reveal	✗	✗	✓ ‖ spoilers ‖
AI parsability	⚠ medium	⚠ medium	✓ high

→use CLN for: summaries, analysis, specs, notes, AI prompts, agent protocols

*use prose for: storytelling, essays, emotional content

*use Markdown for: docs, READMEs, rendered web content

---