The Thoughtware specification

A product requirements document asks what the system should do for users. A Thoughtware specification asks something harder: which judgments exist, who owns them, what may be believed, how conduct is evaluated, and where exact work stays in code. The difference matters because intelligence-age systems fail architecturally more often than they fail syntactically. Fluency without a spec is a demo. A spec without executable hooks is theatre.

Helpful context: Making the specification executable describes derivation and traceability. The Thoughtware architect owns the document when generation fills the repository. The Thoughtware Map and Grammar is the workshop artifact. This page is template-forward: what sections belong in a Thoughtware spec, what each section answers, and how the Meal Companion outline teaches the structure.

What belongs in the spec

A feature list asks which screens and integrations to build. A Thoughtware specification asks which open decisions must exist, which must remain human, what memory may influence them, and how behaviour will be proven before authority rises. The White Paper (section 09) and Introduction to Thoughtware (Chapter 31) converge on a template where each section answers a question a PRD cannot.

Section	Question it answers
Outcome and boundary	What domain result, and what will the system refuse?
Goal and agent ownership	Who pursues the result through changing state?
Decision map / Judgment Chain	Which open judgments exist, in what order?
cognitive units, skills, agents	Named judgments versus procedures versus goals
Deterministic shell	Exact operations, guards, permissions, audit
Memory forms	What may influence which decision, with what endorsement?
Authority and escalation	What may be done, proposed, approved, reversed?
Behavioural standards	Posture, questions, challenge, refusal, recovery
Evaluation hooks	Suites, gates, promotion rules, rollback

Skills enter when procedures coordinate multiple calls without owning a single open judgment. Agents enter when a goal persists across changing working state and requires loop strategy. The spec names them separately so decision locality stays visible.

Meal Companion outline as teaching device

The following outline teaches the structure using one bounded product slice. The outcome reads: help a household create a practical weekly dinner plan that reflects the current week, respects confirmed constraints, uses ingredients sensibly, supports local correction, and prepares an accurate shopping list. The boundary names refusals: plans dinners, does not diagnose, does not create dietary policy, does not purchase without approval.

The goal belongs to the Meal Planning Agent, which owns accepted weekly plan through minimum sufficient loop. The Judgment Chain names interpretation, candidate generation, practicality assessment, composition, critique, and local repair. Named cognitive units include InterpretWeek, GenerateCandidates, AssessMealPracticality, ComposeWeek, CritiquePlan, RecommendMealSubstitution, AskTargetedQuestion, and judge-library entries for variety and schedule fit.

The deterministic shell holds allergy enforcement, portion math, schema validation, purchase approval, plan versioning, and audit trail. Memory sections name context for this week's request, endorsed knowledge for allergies and effort ceilings, working state for current plan version and accepted meals, and temporary corrections that must not become durable without approval. Authority states: may propose plans and purchases, may not override allergies, diagnose, or complete purchase independently. Behaviour requires proactivity when reversible, targeted questions when material, challenge of impractical combinations, and preservation of accepted meals during correction. Evaluation attaches suite per named cognitive units, trajectory gates before authority rises, promotion rules for library versions, and conduct cases alongside answer cases.

Each section traces to something a person authored or explicitly approved. Gaps are acceptable when labelled. Invented policy is not.

1. 01Outcome and boundaryHuman-authored framing
2. 02Decision mapNamed judgments and leadership
3. 03cognitive unit, shell, memoryExecutable structure
4. 04Authority and evaluationTrust and evidence hooks

The spec holds meaning. Generation derives structure. Evaluation proves alignment.

Executable where possible

A specification that never becomes contracts, suites, and gates remains theatre. Executable means given this working state, named judgments return declared results and deterministic gates enforce exact rules. CI can fail when they do not.

Example hooks from the Meal Companion spec illustrate the standard concretely. Given busy Tuesday flagged in working state, AssessMealPracticality returns fail for a sixty-minute active-effort candidate. Given cashew in endorsed allergy knowledge, no cashew candidate reaches composition. Given missing effort metadata, the cognitive unit abstains rather than guessing. Not every line compiles mechanically. Contested values return to domain owners. Ambiguous conduct standards stay unresolved until someone with authority clarifies them. The spec is honest about both executable hooks and open returns. That honesty distinguishes the spec from an aspirational roadmap. When a hook cannot fire because working state is incomplete, the gap becomes a visible test failure rather than a silent runtime assumption.

How the spec relates to framing and construction

The starting point is framing. Outcome and boundary come from the workshop. Judgment Chain and terrain come from the map. The specification captures what the team agreed so construction does not depend on workshop attendance. Construction derives executable architecture from the spec through Intent Compilation, and evaluation proves alignment between specification intent and runtime behaviour.

Living document discipline

Specifications fail when treated as launch artifacts. Model tiers change. Library versions promote. Authority rises when suites pass. Endorsed knowledge updates when households approve preference changes. The spec needs owners, a change log, and explicit links to executable pieces. When AssessMealPracticality v2 promotes, the spec section records new gaps, new suites, and any authority ceiling change. Without that discipline, the spec drifts from the running system within weeks. Teams discover the drift only when a contested judgment produces an outcome no one can trace back to an authorized decision.

Version the spec with the same seriousness as library semantic versioning. Teams that version code while leaving spec prose unversioned rediscover the same arguments every quarter. A spec diff answers which judgments changed, which grants changed, and which evaluation hooks moved.

Sections that resist compression

Some sections resist short prose because they carry contested values. Boundary and authority often need workshop time. Behavioural standards need conduct cases, not adjectives. Evaluation hooks need named owners. Open returns marked unresolved preserve abstraction and responsibility. Generated filler destroys both.

The spec hands off to Intent Compilation with traceability requirements explicit. See making the specification executable. When teams migrate legacy prompts, adopting cognitive units in existing code describes shadow eval and cutover patterns that preserve spec intent.

The enterprise parallel

Invoice intake specifications name field interpretation cognitive units, extraction Skills, exception classification, and clerk authority nodes separately. The outcome sentence names throughput and auditability, not "use LLM on PDFs." Boundary refuses autonomous payment without approval. Evaluation hooks attach per field judgment and per procedure Skill. The template structure matches Meal Companion even when domain vocabulary differs. The artifact is learnable independent of any single product story.

A Thoughtware specification records outcomes, decision maps, cognitive units, memory, authority, and evaluation, not implementation choices alone.

Thoughtware White Paper . section 09

Common mistakes

Writing a longer PRD. More words do not create a different artifact. Sections must name judgments and authority, not user stories alone.

Hiding decisions inside agent prose. "The agent handles practicality" is not a spec. AssessMealPracticality with inputs, outputs, and suite pointers is.

Treating evaluation as a late appendix. Hooks belong per judgment from the first draft, not as a final sign-off column added under deadline pressure.

Letting the spec drift from the map. When the map changes, the spec changes. One source of truth prevents quiet divergence between workshop memory and documented intent.

What to do next

Copying the section headings into a draft spec for one bounded product slice and attaching at least one evaluation hook per named cognitive units is how the template becomes concrete. Identifying one contested value that must return to a human owner rather than being filled by generation preserves responsibility. Spec review accompanies library semantic versioning review: when library versions promote, when authority rises, when conduct cases fail, and when the map changes. A fifteen-minute spec diff review prevents quarter-long arguments about whether behaviour drift was authorised.

See making the specification executable for the derivation discipline, the Thoughtware architect for ownership, and from experimenting to governing for when the document becomes organisational policy.

Read next: From experimenting to governing.