| name | capturing-artifacts |
| description | Stores truth artifacts in DNA with correct kind, format, metadata, and semantic context. Use when codifying decisions, contracts, intents, or constraints that should persist across code changes, team transitions, and framework evolutions. |
Capturing Artifacts
Truth artifacts preserve system identity. Write them to survive a rewrite.
Before you store
Verify the artifact passes these checks:
- Rewrite test: Would this still be true if the system were rewritten in a different language? If no, you are capturing implementation, not identity.
- Two-agent test: Could two different agents read this and make the same decisions? If no, it is too vague.
- Negative test: Does it state what is NOT acceptable? Negative constraints are often more actionable than positive ones.
- Measurable test: Where applicable, does it include measurable criteria? "Fast" is meaningless. "Under 50ms at p99" is actionable.
- Why test: Does it explain WHY, not just WHAT? The reasoning prevents future agents from "fixing" intentional decisions.
Choosing the right kind
| Kind | Use when | NOT for |
|---|
| intent | Capturing WHY something exists or works this way | Implementation details |
| contract | Defining BOUNDARIES between components | Internal implementation |
| constraint | Setting LIMITS on what is acceptable | Preferences or suggestions |
| algorithm | Describing HOW a computation works (the logic, not the code) | Code snippets |
| evaluation | Defining what SUCCESS means (testable criteria) | Vague quality goals |
| tradeoff | Declaring PRIORITY when concerns clash | Single concerns without conflict |
| escalation | Defining DECISION BOUNDARIES for agent autonomy | Hard system limits (use constraint) |
| monitor | Specifying WHAT to observe and alert on | Tool-specific dashboards |
| glossary | Defining TERMS precisely to prevent ambiguity | Obvious vocabulary |
| integration | Describing HOW external systems connect | Internal service details |
| pace | Declaring CHANGE VELOCITY for an area (fast/medium/slow) | Sprint plans |
| compliance | Capturing REGULATORY requirements with source | General best practices |
| reporting | Defining WHAT must be queryable for business needs | Report layouts |
If unsure between two kinds, choose the one that answers the more fundamental question. "Why" (intent) is more fundamental than "how" (algorithm). "What are the limits" (constraint) is more fundamental than "what to observe" (monitor). "Which concern wins" (tradeoff) is more fundamental than "when to ask a human" (escalation).
Writing the content
Structure
One artifact = one truth. Do not combine multiple decisions into a single artifact. "The billing system uses immutable invoices AND charges tax after discounts" is two artifacts.
Specificity
State observable behavior, not implementation:
# Bad: implementation-specific
Use bcrypt with cost factor 12.
# Good: observable behavior
Passwords must be hashed with a memory-hard algorithm.
Cost parameters must make brute-force infeasible on current hardware
(target: >100ms per hash). Raw passwords must never be logged,
stored in plaintext, or transmitted after initial receipt.
Edge cases
Document edge cases with reasoning:
Shipping is calculated on the pre-discount subtotal.
Reason: prevents gaming via high-discount items where the
discount exceeds the shipping savings.
The "reason" prevents a future agent from "fixing" this to use post-discount subtotal.
Storing the artifact
dna add <kind> "<content>" \
--name "<short descriptive name>" \
--label domain=<domain-area> \
--context "<additional semantic context for search>"
Name
Short, descriptive. Used for human identification. "Immutable invoices after finalization" not "billing-rule-1".
Labels
Label keys must be registered in your project before use. Run dna label list to see available labels, or dna context to view all registered kinds and labels.
Use consistent label keys across the project:
domain=<domain>: billing, auth, onboarding, etc.regulation=<name>: for compliance artifacts (gdpr, hipaa, pci-dss)
Context
The --context flag adds semantic context for search without polluting the artifact content. Use it when the content alone might not surface for relevant queries:
dna add intent "Orders must not ship until payment is confirmed" \
--name "Payment before shipment" \
--label domain=orders \
--context "fulfillment, warehouse, payment verification, shipping hold"
Format
Choose format based on content structure:
--format markdown: Prose with structure (default, good for most artifacts)--format yaml: Structured data with clear fields--format text: Single atomic statement--format openapi: API contracts specifically
