---
name: loom-domain-language-and-decisions
description: "Use when work is blocked by ambiguous project/domain vocabulary, conflicting terms, code-vs-operator language mismatch, cross-domain ownership questions, or an architectural tradeoff that may need durable precedent."
---

# loom-domain-language-and-decisions

Domain language and decisions is a shaping playbook.

It challenges a proposed change against the project's current vocabulary,
behavior, and decisions, then routes resolved language to knowledge and durable
tradeoffs to constitution decisions.

## Core Dependency

Use `loom-core` first. This playbook composes `loom-knowledge`,
`loom-constitution`, `loom-research`, `loom-specs`, `loom-plans`,
`loom-tickets`, and `loom-evidence`.

It does not create a separate glossary or decision-record surface. Core records
carry the durable results.

## Use This Playbook When

Use this playbook when:

- a plan or spec uses vague, overloaded, or conflicting terminology
- a domain concept needs a canonical name before implementation
- code and operator language appear to disagree
- an architecture choice may deserve durable precedent
- a feature spans domain boundaries or context ownership
- a future agent would likely misunderstand the work without shared language

Skip it for generic implementation terms that do not help future agents understand
this project.

## Route

Use this route:

```text
load language -> challenge terms -> test scenarios -> resolve -> record -> route
```

## Load Language

Before asking the operator questions, inspect existing Loom records and nearby
source context.

Read what is relevant:

- knowledge concepts, atlases, references, and entities for the area
- constitution decisions and principles
- specs, plans, and tickets that already define terms or behavior
- code names, public interfaces, tests, and user-facing labels
- evidence or research that explains prior behavior

If a question can be answered by inspecting records or code, inspect instead of
asking.

## Challenge Terms

When language is ambiguous, ask one focused question at a time.

Challenge:

- one word being used for two concepts
- two words being used for one concept
- terms that conflict with code or accepted knowledge
- names that imply a broader behavior than the change actually supports
- domain words that hide policy, ownership, lifecycle, or permission decisions

Offer a recommended canonical term when useful. Name aliases to avoid when they
would cause future confusion.

## Test Scenarios

Stress-test language with concrete scenarios.

Use scenarios to clarify:

- lifecycle transitions
- cardinality and relationships
- ownership of data or behavior
- error and edge states
- permission or actor differences
- cross-context integration
- what is explicitly out of scope

If scenarios reveal intended behavior, route to `loom-specs`. If they reveal
unknown source facts, route to `loom-research`.

## Resolve

For each resolved concept, decide where it belongs:

- knowledge concept or reference for accepted language and relationships
- knowledge atlas when a code area map is part of the understanding
- spec when the language defines behavior or interface semantics
- constitution decision when the choice is hard to reverse, surprising without
  context, and based on a real tradeoff
- ticket when the language change creates executable follow-up

Do not write a constitution decision for every preference. A decision record is for
precedent future agents should inherit.

## Record

Capture language while it is resolved rather than batching it at the end.

Good knowledge language records include:

- canonical term
- tight definition
- aliases or terms to avoid
- relationships to nearby concepts
- example dialogue or scenario when it prevents misuse
- where the concept applies and where it does not

Good constitution decisions include:

- context
- chosen path
- rejected alternatives
- consequences
- accepted risks
- revisit conditions

## Route

After the language and decisions are stable, route the work:

- `loom-idea-refine` for rough ideas that still need shaping
- `loom-specs` for intended behavior
- `loom-plans` for multi-ticket sequencing
- `loom-tickets` for executable work
- `loom-architecture-deepening` when language points at architectural friction
- `loom-prototype-and-spike` when a prototype is needed before commitment

## Done Means

The language pass is done when:

- key terms are no longer overloaded or vague
- code, records, and operator language agree or the disagreement is explicit
- durable language is in knowledge, not trapped in chat
- real precedent is in constitution decisions when warranted
- the next record move is clear