Decision precedence
When applicable guidance conflicts, resolve it in this order:
1. Rule / invariant
2. Explicit implementation requirement
3. Explicit owner or user choice
4. Recommended default
5. Agent judgmentLower-precedence guidance cannot override higher-precedence guidance. Same-level conflicts or unclear scope are unresolved decisions, not invitations for an agent to improvise.
Shared elements and approved reuse
Reusable code and tools are not automatically reusable capability meaning. A shared element may retain assumptions from the capability it was created for.
shared element: customer-identity-validation
created for: customer-onboarding
approved reuse: [request-moving-quote, submit-insurance-claim]Use this optional declaration for components, prompts, schemas, workflows, tools, or tests when origin context and explicit reuse approval matter.
Capability, skill, and tool
| Concept | Meaning | Typical relationship |
|---|---|---|
| Capability MLE | Complete contextual ability that produces an outcome. | Defined by one CRD. |
| Skill | Agentic realization package: instructions, context, tools, and workflow. | May realize one capability or bundle several. |
| Tool | Executable primitive: API operation, MCP tool, function, command, or workflow step. | May support many skills and capabilities. |
A skill is not automatically a capability, and a tool is not automatically a skill. A capability can be the MLE of a skill only when the skill has one coherent outcome.
Related MLEs by Dimension
A CRD may optionally trace itself to lower-level, discipline-specific MLEs — Business/Domain, UX/Experience, Communication, Interaction/Behaviour, Frontend/Interface, Backend/Execution, Data/Information, API/Interoperability, Agentic, Verification, Operations — using relationship types defines, implements, supports, constrains, verifies, exposes, or reused_by (full model: specification §7.4). This is traceability, not coverage: never fill a dimension with no genuine content just to appear complete.
Communication is deliberately first-class here rather than filed under UX, because a message's meaning is usually shaped by business rules, rendered by frontend or delivery infrastructure, and localized independently — no single discipline owns it. A Communication MLE separates canonical meaning from its channel realization and its language realization, so the same intended meaning stays consistent across a toast, an email, a push notification, and a translation of any of those.
One capability-owned Communication MLE and one product-wide Source Context Reference are complementary, not competing: the message itself belongs to the capability that produces it, while a cross-cutting terminology or tone convention many messages should follow belongs in SCR if the product already has one. See the worked trial in Reconcile payments.
Why CRD is not merely a feature or existing artifact
| Artifact | Useful for | What it does not establish alone |
|---|---|---|
| PRD | Product/application rationale and scope. | A reusable, independently bounded capability. |
| User story | A human actor’s desired outcome. | Rules, state transitions, machine contracts, and realization independence. |
| UI screen or Storybook component | An interface representation. | Complete capability purpose, policies, effects, and non-UI use. |
| API/OpenAPI/GraphQL module | Technical interface and data contract. | Whether operations together form one meaningful capability. |
| Skill or MCP tool | Agentic realization or executable interface. | Purpose, boundaries, and approved capability context. |
“Feature” is a useful informal word, but its boundary is often negotiated case by case. A CRD makes the boundary explicit through purpose, outcome, included/excluded concerns, contracts, rules, defaults, and unknowns.
Audience projections
One canonical CRD may be projected for different readers without duplicating or diverging its requirements.
| Projection | Questions it answers |
|---|---|
| Business/domain | Why does it exist? What outcome, rules, and rationale matter? |
| UX | Who acts? What choices, states, and outcomes must be understandable? |
| Frontend | What representations and interaction constraints are needed? |
| Backend | What transitions, invariants, effects, and dependencies must hold? |
| API/MCP/tools | What commands, contracts, inputs, outputs, and authority bounds exist? |
| Agent | What authority, grounding, precedence, approval, and escalation rules apply? |
| Operations | Which realization is active and how is it observed, recovered, and retired? |
A projection is a view of the CRD, not a new source of truth.