The Thoughtware Map and Grammar

Sprint planning opens with model comparisons. Risk asks about approval paths. Design asks about memory UX. Engineering asks about agents and state. Compliance asks for audit. Nobody references the same diagram. Last sprint's framing lived in a Miro board nobody opened. This sprint restarts from features because architectural commitments never became a shared object the whole team could point at.

That restart tax is expensive. Teams re-debate the same boundaries, re-discover the same allergy enforcement gap, re-litigate whether purchase needs approval. The Thoughtware Map holds the architectural view. The Thoughtware Grammar states commitments in reviewable form so Intent Compilation can trace implementation to human-authored judgment.

This page teaches diagram language for parsing book figures and writing specs, not every cognitive unit name, but how layers relate. Full system assembly lives in the Thoughtware system. Workshop sequence lives in start from decisions, not from models.

Reading the map

When reading a map figure, or drawing one for the household dinner planner, the movement is outer to inner. Outcome and boundary define the domain result and explicit exclusions. Judgment chains trace the links in the work with terrain character. Leadership allocation assigns code, cognitive unit, agent, or human per link. Named cognitive units and Skills point to artifacts with owners. Memory forms specify what persists, typed rather than one box labelled "context." Authority names grants, approval paths, and escalation. Evaluation routes tie suites, graders, gates, and regression targets to cognitive unit versions. Deterministic shell marks the exact layer boundary and enforcement points.

The map holds framing at every layer without prescribing database vendor or cloud shape. Implementation choices remain choices. Commitments become visible.

Using Weekly Meal Companion grounding vocabulary, a minimal map records: the outcome as an accepted weekly dinner plan with shopping list, the boundary as no medical diagnosis and no unsupervised purchase, the agent as the Meal Planning Agent owning goal loop and working state, cognitive units as named judges and generators from domain and judge libraries, a Skill composing the weekly plan where procedure shape is settled, the shell enforcing allergies, plan versioning, shopping list, and purchase gate, memory as separate nodes for context, knowledge, working state, and expertise rather than one blob, authority as household approval for plan version and purchase with bridging for sensitive merge, and eval as exact checks plus grader routes on named cognitive units with a busy-week regression set.

This is notation, not implementation. The value is that risk, design, and engineering argue about the same nodes.

Grammar statements and contracts

Map nodes gain force when the grammar expresses them as reviewable statements. An outcome statement reads: "Household receives accepted plan reflecting current week constraints." A behaviour statement reads: "Challenge impractical weeks, preserve accepted meals during local repair." A memory statement reads: "Cashew allergy is endorsed knowledge, 'avoid pasta this week' is context." An authority statement reads: "Purchase requires explicit approval event." An evaluation statement reads: "Release blocked if busy-week regression suite fails."

Making the specification executable compiles map plus grammar into runnable structure: named cognitive units, agent boundaries, memory schemas, evaluation hooks, with traceability from code to map node. The compilation sequence moves from capturing outcome and boundary on the map, through drawing judgment chains and allocating leadership per link, to naming cognitive units, agents, memory forms, and authority, then attaching evaluation and learning routes, and finally compiling into contracts and runnable structure.

Framing workshops produce heat and posters. Without compilation to contracts, suites, and enforcement points, the map decays into wallpaper. Teams revert to feature lists and model bake-offs within two sprints. The grammar prevents decorative diagrams. If a node cannot be stated as a commitment testable by eval or code, it is not ready for the map, or it belongs in a parking lot until judgment is named.

The difference between weak and strong grammar statements is observability. "The agent is helpful" cannot be tested. "When two busy evenings collide with a twenty-minute rule violation, the agent challenges the combination before presenting a plan" can be tested. "Memory is smart" cannot be tested. "Cashew allergy is endorsed knowledge with household approver ID, enforced in shell before plan display" can be tested. "We will evaluate quality" cannot be tested. "Release blocked if busy-week regression suite fails or if JudgeWeekdayPracticality semantic version bump lacks substitution verification" can be tested. Strong statements belong in PR templates. If implementation cannot point to the statement it satisfies, the PR is out of map scope.

A shared map keeps construction from restarting at features every cycle.

Introduction to Thoughtware · Ch. 8

Maintaining the map in practice

Redrawing a second domain in the same notation verifies that the grammar travels. Enterprise invoice processing fits the same layers: posting outcome, field-level cognitive units, extraction Skill, ledger-backed system sources, posting approval, posting regression eval. Different terrain, same reading order. If the notation works for only one demo product, it is illustration, not grammar. See four kinds of source for provenance labels at cognitive unit inputs and outcomes, not features when scope creep arrives as assistant ideas.

The Thoughtware architect role, or equivalent cross-functional owner, curates map freshness weekly rather than quarterly. Changes to authority, memory promotion, or library substitution update the map before merge, or traceability breaks. See the Thoughtware architect. Product managers anchor prioritisation to outcome nodes. Engineers anchor refactors to judgment chains. Designers anchor memory UX to form labels on the map. Eval owners anchor release gates to routes drawn on the map.

Every eval route on the map names: suite owner, dataset or generator, pass threshold, release gate yes or no, and which cognitive unit or shell check it binds to. Anonymous "quality review" nodes are not eval routes. An example route traces busy-week-regression to JudgeWeekdayPracticality v1.4, to a household fixture set from week 14 failure, blocking library publish on fail, and notifying the quality owner. Drawing routes on the map prevents eval from becoming a parallel universe disconnected from shipping decisions.

Maps fail when workshops become unconstrained brainstorming. Constraints produce useful maps: starting at the outcome node, forbidding model names for the first twenty minutes, adding judgment chains before UI mockups, requiring leadership allocation per chain link before discussing frameworks, and ending with three grammar statements and one eval route rather than fifty sticky notes. Photographing the map, committing a redacted version to the repo, and linking from the epic keeps maps alive past the workshop day. Maps that live only in workshop photos die within one sprint.

Reviews in pull requests catch map drift when changes touch authority, memory promotion, or library substitution. If the PR cannot cite the node it updates, scope is ambiguous. Inviting legal and compliance to one map session per quarter often exposes missing grammar statements engineering assumed were obvious. Storing map sources in git when possible gives version history on outcomes and authority that beats static slides silently diverging from production.

Common mistakes

The most common map failure is feature nodes instead of outcome and judgment chains, because features are familiar while outcomes require commitment. One memory bubble hiding governance differences produces the same undifferentiated-store mistake at diagram level that six forms of memory addresses at schema level. Agent splat, where a single agent node absorbs every judgment, prevents the ownership splits that keep cognitive units evaluable. Eval footnote, where suites are listed without connection to named cognitive units, makes quality evidence decorative. Map in slide deck only, never linked from specs, tickets, or catalogs, means the map cannot prevent the restart tax it was built to avoid.

What to do next

One map on the wall for the primary outcome, updated weekly, gives every sprint kickoff a shared anchor. Sprint kickoffs that cannot point at the outcome node first lack architectural grounding. Rewriting three grammar statements from the current epic into testable commitments reveals which nodes are decorative and which carry force. Tracing one production bug to a missing or wrong map node confirms the map's diagnostic value. Compiling one chain from map to cognitive unit contract this sprint closes the gap between framing and implementation.

See framing, the Thoughtware system, and Thoughtware in practice for how teams keep maps alive.

Read next: When AI stops being visible.