CLN · Cognitive Ladder Notation · v2.4
Super Demo
@version 2.3
@operators 12
@markers 4 types
@addressing ★v2.1
@tables ★v2.3
@chapters 9
00PREFACEWhy CLN — the cognitive caseStart Here
<200ms
operator classified
before text is read
12
semantic types —
max pre-attentive set
0
extra tools needed —
any text field works
01 · The problem with prose
Prose input Loose bricks
The migration offers a performance gain of roughly 13%. However, there is a risk that the team lacks AWS experience, which could be an issue. Whether we should use Reserved Instances is still an open question. The recommendation is to adopt for new features only.
CLN input Steel frame
=migration to AWSdefinition
+13% perf gainpro
!team: zero AWS experiencerisk ← eyes go here first
.hire contractor · 90 daysaction
?Reserved Instances vs on-prem TCOunknown
→adopt for new features onlyresult
02 · The schema scaffold
What CLN builds in your brain Construction
=schema — a cognitive framework that organises information in LTM
→new information must attach to an existing schema · if no schema exists, it falls out of memory
*CLN operators build the schema before the information arrives
= topic
→ outcome
! risk
? open
Pre-built structure · information "sticks" because the slot already exists
Without schema — loose bricks Decay
Prose gives you bricks with no mortar. Each sentence is processed in isolation — no pre-built slot to attach to. Working memory holds it temporarily, then it decays.
■ fact about performance
■ something about the team
■ cost question maybe?
■ ...
03 · Encoding depth — Craik & Lockhart 1972
Levels of Processing — what choosing an operator costs you (productively) Craik & Lockhart 1972
Level Prose processing CLN processing Result
Shallow recognise words · decode syntax same · plus: see operator shape surface encoding · fast decay
Intermediate infer sentence meaning · classify manually operator already classifies · skip this step moderate retention
Deep decide: is this a risk? task? fact? — hard you chose ! when writing → deep encoding at authoring time durable memory · 10× better recall
=memory durability depends on the depth of processing at encoding time
!choosing an operator forces deep encoding — that act of deciding is the cognitive value
→CLN is intentional friction · slows you down just enough to think
04 · The 200ms window
0
Photons
Raw signal. No structure yet.
~50ms
Texton fire
V1 cortex: shape · orientation · crossings extracted globally.
~150ms
Op classified
CLN operator: semantic type assigned. Before a word is read.
~300ms
Fixation
Eyes arrive on text. Schema slot already open.
~500ms
Comprehension
Typed fact enters working memory. Load reduced.
★ highlighted zone = the CLN window — operator recognised pre-attentively, before serial reading begins · → textons in CLN
05 · For AI agents
What agents see in prose Untyped
Token stream. No semantic type. Agent must infer whether each sentence is a constraint, a result, an open question, or a recommendation — using context alone. Fails at step 8 of a long loop.
What agents see in CLN Pre-typed
!blocking constraint — do not proceed
→confirmed outcome from step 3
?unresolved — needs human input
.next action to execute
01CHAPTEROperator Set — all 12, every tier
=
Equals
Definition
.
Dot
Action
→
Arrow
Result
!
Bang
Risk
~
Tilde
Tension
?
Question
Unknown
@
At
Metadata
|
Pipe
Resource
*
Star
Note
+
Plus
Pro
-
Minus
Con
#
Hash
Tag
ANALYSIS: Tier 1 + 2 — Signal & Actiontier-1,2
// Definition & Essence =core idea — the essence of this block =sub-definition, still essential =drill-down detail // Action & Steps (4 levels) .primary action to execute .sub-step belonging to parent .detailed sub-sub-step .deepest level — use sparingly // Result & Output →outcome of the above action →secondary positive result // Risk & Tension !critical blocker — stops progress!! !secondary risk to monitor ~speed vs correctness — unresolved tension ~local optimum vs global optimum
CONTEXT: Tier 3 — Context operatorstier-3
// Unknown & Hypothesis ?open question — answer unknown ?sub-hypothesis to investigate // Metadata & Status @owner: team-alpha @deadline: 2026-03-01 @priority: P1 · status: active // Tool & Resource |postgres:14 · redis:7.2 · kafka:3.6 |aws-s3 · cloudfront · route53 // Note & Context *see RFC 2119 for terminology standards *additional context about the above // Pro & Con + Tags +clear advantage of this approach✓ confirmed -known drawback to account for -secondary downside .deploy to staging#devops#urgent☐ |kubectl apply -f deploy.yaml#k8s
02CHAPTERMarkers & Status — Slot 5 of Line Anatomy
✓ donecompleted
☐ pendingwaiting
✕ canceldropped
!! criticalurgent
✓ confirmedvalidated
☐ openresearch
TASK: Sprint backlogsprint-7
// Done .Auth service refactor✓ done .Redis cache layer✓ done .Unit tests 80% coverage✓ done // In progress .API rate limiter☐ wip .Integration tests☐ pending // Blocked / dropped !DB migration blocked!! .Load balancer config✕ drop
RISK: Project risk matrixq1-risks
// High severity !API latency >500ms at peak!! @mitigation: Redis + CDN☐ plan !Single DB node — no replica!! @mitigation: RDS Multi-AZ✓ approved // Medium !Vendor lock-in: AWS SQS☐ monitor // Resolved →Auth token expiry patched✓ closed
REVIEW: Code review findingsPR-447
// Must fix !SQL injection in search endpoint!! !No input validation on upload☐ fix // Should fix .Magic numbers → constants☐ .Add JSDoc to public methods☐ // Looks good +Clean separation of concerns✓ +Error handling thorough✓ +Tests cover edge cases✓
03CHAPTERBlock Accent Stripes — cln-block[ac=*]
DECISION: Kafka vs SQS vs RabbitMQdecision-matrix
// 01 Context =Choose message queue for 50k msg/sec · team: 3 devs @constraint: must not add ops complexity in Y1 // 02 For Kafka +Horizontal scale — handles 1M msg/sec +Message replay — debugging superpower +Ecosystem — connectors for everything // 03 Against Kafka -Ops complexity — ZooKeeper or KRaft -Overkill for 50k/sec at current stage // 04 Tension ~future-proof infra vs current team capacity ~cost of migration later vs over-engineering now // 05 Verdict →SQS now · Kafka when traffic justifies it✓ decided @trigger: sustained >200k msg/sec for 30 days
INCIDENT: Post-mortem — API outageINC-2026-019
// Timeline @14:22 — alerts: 5xx spike on /api/auth @14:28 — on-call engineer paged @14:35 — root cause identified @14:47 — hotfix deployed · 100% recovery // Root cause !JWT secret rotated without updating prod env!! *Manual deploy step skipped in runbook v2.1 // Open questions ?Why did staging not catch this?☐ root ?Secret rotation process needs owner☐ assign // Action items .Automate secret sync via Vault agent☐ .Smoke test: auth endpoint after each deploy☐ .Update runbook with rotation step✓ done
04CHAPTERNested Block Hierarchy — sidebar stripe depth system
PROJECT: Q1 roadmap — nested phasesdepth-3
.Phase 1 — Foundation (weeks 1–4)#P1✓ done =Auth system · DB schema · CI/CD pipeline .Set up monorepo structure✓ .OAuth2 + JWT auth flow✓ .Postgres + Redis setup✓ !Secret management not yet defined☐ *Consider Vault or AWS Secrets Manager ?Which approach fits team skills?☐ open .Phase 2 — Core features (weeks 5–8)#P2☐ wip .REST API v1 — 12 endpoints☐ .Admin dashboard MVP☐ ?GraphQL vs REST for client API?☐ open .Phase 3 — Scale (weeks 9–12)#P3☐ tbd .Load testing + perf optimisation☐ .Observability — traces + metrics☐
SPEC: Nesting rules§4
=Depth 1 — root stripe =Depth 2 — recessed 1px =Depth 3 — dashed, 85% *width: 2px → 1px → 1px dashed *opacity: 100% → 90% → 85% *recommended max: 3 levels !Deep nesting = cognitive overload →Flatten using // block labels instead
05CHAPTERAddressing System — ##anchors · »linksv2.1NEW
SPEC: Line anatomy — 5 slotsslot-4-new
// Slot order =OPERATOR · Content · #tag · ##anchor · marker // Block label + anchor // ##arch 01 · Architecture // Line anchor (Slot 4) .Deploy Redis cache#infra##redis☐ // Cross-reference » !blocked by »[auth task]##api-auth!! →resolves »[root cause]##cause✓ linked *see »[MDA template]##mda for context // Parser order (right-to-left) =1 strip marker → 2 strip ##anchor → 3 strip #tags → 4 strip »links → 5 content
SUMMARY: Navigation map + dependency chainlive-links
// Table of contents (clickable) .»[Operator Set]##ch1 .»[Block Accents]##ch3 .»[Analysis Templates]##ch7 .»[Full Document]##ch9 // Task dependency chain .Write auth API##api-auth✓ done .Write integration tests##int-tests☐ !needs »[auth API]##api-auth merged first .Load testing##load-test☐ next *needs »[int-tests]##int-tests passing // ID rules =charset: [a-z0-9\-\_]+ · no spaces · no uppercase =unique per document · ends at first space
06CHAPTERReal-World Documents — three side by side
MEETING: Retro — Sprint 72026-02-14
@team: 5 · duration: 45 min @facilitator: Maria // What went well +Zero production bugs this sprint✓ notable +Auth refactor landed clean✓ +Standups shortened to 10 min✓ // To improve -PR reviews taking >2 days -Flaky tests in CI#blocker // Actions .48h PR review SLA☐ .Fix flaky tests☐ @owner: Alex · due: Friday
SUMMARY: Thinking Fast & SlowKahneman
=Two systems drive all human thought =System 1: fast, automatic, emotional =System 2: slow, deliberate, logical .Key biases .Anchoring — first number biases all estimates .Loss aversion — losses hurt 2× more .Availability — what comes to mind ≠ frequency +Landmark work — defines the field✓ essential -Replication crisis hit several studies☐ contested !Knowing about bias ≠ eliminating it!! @author: Kahneman · 2011
COMPARE: PKM tools 2026Obsidian·Notion·Logseq
// Obsidian +Local-first, owns your data✓ strong +Graph view reveals knowledge clusters -Mobile sync is a paid add-on // Notion ~Best for teams, worst for solo PKM +Databases + views = powerful structures !Perf degrades on large bases // Verdict →Obsidian solo · Notion for teams✓ decided
07CHAPTERAnalysis Templates — ^mda · ^summarize
MDA: Remote work — depth 3^mda
// ##first 01 · First-Order .Individual: flexibility · no commute · deep focus .Company: lower costs · global talent pool // ##second 02 · Second-Order — what changes ~Collaboration gains friction · serendipity disappears ~Trust replaces visibility · output replaces hours !Junior devs lose mentorship bandwidth // ##third 03 · Third-Order — cascade ?Will remote-first companies have cultural fragility? ?Does async slow innovation cycles? →Hybrid optimal — but culture must be explicit✓ thesis
ANALYSIS: WebAssembly — full spectrumtech-eval
// 01 Definition =Binary instruction format for stack-based VM in browsers =Compile target: C, C++, Rust, Go, AssemblyScript @status: W3C standard · all browsers · 2017+✓ stable // 02 Trade-offs +Near-native perf — within 20% of native C✓ measured +Language agnostic — any compiled language -DOM access via JS glue — not native -Binary debugging harder than JS source maps ~Performance gain ↔ Developer ergonomics loss // 03 Use when →Video codecs · games · CAD · scientific viz !Avoid for CRUD apps — JS is faster to ship
08CHAPTERCode Fences · Separators · Special Syntax
TASK: API config — data embeddingfence-demo
=Configure Redis connection pool for prod |redis.config.ts · type: json { "host": "redis://prod-cache.internal", "port": 6379, "maxRetries": 3, "reconnectOnError": true, "flags": ["!readonly", "=cluster-mode"] } .Validate connection on startup#devops☐ |redis-cli -h prod-cache.internal ping →expect: PONG .Deploy via Helm☐ |helm upgrade --install redis ./charts/redis !Symbols inside fence (! = -) are NOT CLN operators✓ by design
GUIDE: Deploy pipeline — h-rule separatorsseparator-demo
Phase 1 — Build
.Install dependencies✓ |npm ci --frozen-lockfile .Type-check✓ |npx tsc --noEmit .Build production bundle✓ →dist/ ready · 847kb gzipped
Phase 2 — Test
.Unit tests✓ →coverage: 87% lines · 91% branches .Integration tests☐ wip
Phase 3 — Deploy
.Push image to ECR☐ .Deploy to ECS via CodePipeline☐ !Requires integration tests passing first
09CHAPTERFull Document — everything in one CLN blockv2.1
PROJECT: CLN Parser v2.1 — complete project documentfull-demo · all elements
// SUMMARY: Navigation .»[Context]##fd-ctx .»[Risks]##fd-risks .»[Roadmap]##fd-road .»[Verdict]##fd-verdict // ##fd-ctx 01 · Project Context =CLN Parser v2.1 — Python reference implementation =Converts .cln plain-text → AST + HTML + JSON @owner: Vadim · started: 2026-01-15 · solo @stack: Python 3.12 · pytest · no external deps // ##fd-risks 02 · Risks & Unknowns !v2.1 addressing syntax not yet in parser##risk-addr!! @mitigation: implement ##id regex in tokenizer☐ next !Block animation conflicts with print CSS☐ investigate ?Should parser handle Markdown inside CLN text nodes?☐ open // ##fd-road 03 · Roadmap .Sprint 1 — Core tokenizer#S1✓ done .Operator detection (12 operators)✓ .Indentation level parsing✓ .Tag extraction #word✓ .Marker parsing ✓ ☐ !!✓ .Sprint 2 — Block structure + HTML renderer#S2✓ done .Sprint 3 — Addressing system v2.1#S3☐ wip .##id anchor tokenizer☐ .»[text]##id link resolver☐ .Block-level id from // ##id labels☐ !depends on »[risk-addr resolved]##risk-addr!! .Sprint 4 — JSON export + full test suite#S4☐ ~Perfect spec compliance vs pragmatic incremental delivery ~Python readability vs parser performance at scale // ##fd-verdict 04 · Verdict →Ship v2.1 addressing in Sprint 3 · no scope creep✓ decided →Python first · Rust port after test suite green✓ decided @next-review: Sprint 3 demo · 2026-03-07 *full spec at cognitiveladder.com/spec.html