liveBook · Manning

Intent articulation

As explained in Spec-Driven Development

Intent articulation is the practice of making a feature's underlying purpose explicit and connecting it to the required approach.

Intent articulation makes the purpose behind a feature explicit and connects it to a concrete approach. Purpose alone says why an outcome matters; a requirement often says only what to build. Articulated intent joins the two so product, technical, and verification decisions can serve the same goal. section 1.1.2 section 1.1.4

A password reset that secures the account

“Build a password reset flow” leaves a consequential question unanswered: is the goal merely to rotate a credential, or to recover an account that may be compromised? State the latter purpose alongside the requested flow. It then becomes relevant to invalidate active sessions, test that every existing session ends, and tell the user the account has been secured. A password-hash update alone could satisfy the narrow request while missing the goal. section 1.1.1 section 1.1.2

Figure 1.2 We begin with intuitions indicating that users are struggling with compromised accounts. Our purpose, which is to help them regain access, focuses these observations, guides us toward approaches that address the issue, and helps us articulate an intent that defines the desired outcome and its success criteria. This intent seeds the context and acts as a filter, selecting relevant details such as the session store design and security policy while excluding unrelated information such as the payments module. This context-construction process gives the agent just enough information to achieve the intended outcome rather than flooding it with everything available.

The diagram traces how purpose shapes an actionable intent, then filters the context needed for implementation and verification. section 1.1.2

Make the intent usable before implementation:

  • State the underlying why and the proposed what together. Identify the outcome that would make the feature successful, not just the operation the code should perform. section 1.1.2
  • Use a conversation to expose assumptions. Review an agent’s plan before coding, but do not expect planning or an interview to recover a purpose never supplied. section 1.1.4
  • Record the decisions in specifications and acceptance tests. In a spec-driven workflow, Discover establishes business context, Design addresses technical choices, and Task prepares execution; revisit these artifacts as implementation reveals gaps. section 2.2.1 section 1.1

When implementation misses the goal, correct the intent artifact rather than relying on another agent given the same incomplete prompt or only patching the code. Revised specifications and tests can guide regeneration and prevent the same omission from recurring. This matters especially when agents produce implementations faster than reviewers can absorb and correct them. section 1.5 section 1.5.2

How Spec-Driven Development covers it

How deep it goes
Defines the practice and works through a password-reset failure, then outlines conversational and specification-based correction rather than a fixed prompt template.
Examples
Uses a compromised-account password reset, including session invalidation and verification tests, to show what a narrow request omits.
What it assumes
Assumes familiarity with feature requests and coding-agent workflows while defining intent and intent articulation explicitly.
What you can do after
Practice/perform it by stating purpose beside the requested approach, recording success criteria, and revising specifications when generated code misses the goal.
How it connects
Connects requirements, coding agents, acceptance tests, specifications, and spec-driven development.

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Spec-Driven Development. The section links point to the parts of the book it draws on.