Capture as intent.md

The intent.md, which kicks off the software development process, can enter through different routes. A person has an idea, a ticket is filed, or an incident is surfaced via an alert (see Stage 6: Maintain).

When a person has an idea, they brainstorm with Claude and produce a Markdown proto-spec. In the traditional SDLC, the same person must then convince a member of the product team to write the idea up with them or on their behalf.

The proto-spec generated by Claude is human readable, version controlled, and immediately consumable by the next stage. The proto-spec is saved as an intent.md.

Regardless of whether the intent originates from an event trigger or a person, the same steps apply: the product owner reviews and corrects the agent-written intent.md before it is committed.

What changes

Getting started

• Prerequisites: None.
• Infrastructure: Claude access for people who are not engineers (claude.ai or Cowork); an agreed intent.md template; a shared, version-controlled home for intent that the product owner watches. For a single product the simplest home is an intent/ folder in the product repo. This setup keeps the artifact chain next to the code derived from it. A dedicated intent repo is only worth the overhead when intent spans many repositories, and in a monorepo it is a directory. The Legacy systems section in Stage 3: Build covers how this home relates to a Jira or requirements tool that already holds the record.

Setting this up is a one-time task for the platform or engineering team. A technical team member needs to stand up the intent home and decide who can write to it, since many contributors will come from across the organization.

Once the repository exists, contributors without Git experience don't need to use Git directly. Instead a connector to the version-control system (e.g., GitHub) lets Claude commit Markdown files on their behalf from claude.ai or Cowork.

How to execute it

1. The originator describes the problem to Claude in their own words. The originator may describe what they cannot do today, who is affected by the idea, what better looks like, or what is out of scope. No formal language is required.
2. Brainstorm until the idea is concrete. Claude asks the questions an analyst would ask: scope, users, constraints, and what success looks like.
3. Ask Claude to write the result as intent.md using the organization's template, which can be encoded as a skill set up by a technical team member and signed off by a lead. This can cover the problem, proposed outcome, affected users and systems, constraints, and open questions.
4. The originator corrects anything Claude misunderstood.
5. Commit intent.md to the shared home. Author and timestamp join the record, and the product owner picks the idea up from there.

What it looks like

intent.md:

# Intent: claims status self-service
Author: J. Ortiz (claims operations). Status: draft.
## Problem
Customers phone the contact center to ask where their claim is.
Handlers spend roughly a third of call time on status-only queries.
## Proposed outcome
Customers see claim status, next step and expected date in the portal.
## Affected users and systems
Claims handlers, portal team, claims-core API.
## Constraints
No new PII in the portal session. Existing authentication only.
## Open questions
Do third-party loss adjusters need access too?

Governance considerations

The evidence is the committed intent.md, which lists the author, the timestamp, and the full revision history. It's logged in the Git history of the intent home. The product owner approves, and the accept or reject decision that sends the intent into Stage 2: Design is recorded as the merge or the closing review.

How to measure it

• Leading indicator: Time from first conversation to a committed intent.md, read from Git history on the intent home, which records author and timestamp. The expectation is for this to fall from a multi-week elicitation and refinement cycle to hours.
• Lagging indicator: The survival rate, or the share of intent.md files that the product owner accepts into Stage 2: Design rather than closes. The accept or reject decision is recorded as the merge of the artifact or the closed review. Additionally, count the changes to intent.md made after the first spec.md commit for the same change.