For decades, software engineering has been obsessed with the concept of the "Single Source of Truth." We believed that if we could only capture the requirements perfectly—in a PRD, a Figma file, or a Swagger doc—the implementation would naturally follow.
But documents are static. Code is fluid. In the gap between the two lies the most expensive part of building software: the maintenance of alignment. We don't need better documents; we need a better way to describe intent through change.
The Artifact of Intent
At ribo.dev, we've moved away from the monolithic specification. Instead, we use what we call "Intent Artifacts." These aren't descriptions of what the system is, but rather instructions for how the system should evolve.
intent UserAuthentication {
delta (v1 -> v2) {
append field "mfa_enabled" boolean default(false);
enforce policy "session_length < 24h";
notify on_failure(security_team, "slack");
}
constraint security {
level: "strict";
provider: @auth0;
}
}
The snippet above doesn't just define a user; it defines the delta. It records the evolution of the system's state. When a developer or an AI looks at this, they aren't just seeing a snapshot; they are seeing the trajectory.
"The value of engineering isn't in the lines of code written, but in the clarity of the decisions preserved."
Killing the Synchronous Workflow
The document-first approach creates a waterfall—even in "agile" teams. Designer hands to Developer. Developer hands to QA. Each handoff is a lossy compression of intent. By focusing on the delta, we treat the evolution of a feature as a continuous stream of verified changes.