Quick Start

Start with intent. Everything else is choice.

Choose the state that matches reality.

seed        "I have an idea but nothing concrete"
exploring   "I have a direction but need to validate"
clarified   "I know exactly what to build"

Put INTENT.md at the project root. Fill the matching template.

For seed or exploring:

# INTENT — [Project Name]

> status: seed

## Why

Problem: [Who is suffering, and how?]
Hypothesis: [What do you think will fix it? It's OK to be wrong.]
Validation: [How will you know if the hypothesis is right?]

## What

[Leave empty if seed. Write what you want to verify if exploring.]

- [ ] [Feature 1 — one line]
- [ ] [Feature 2 — one line]

## Not

[Write whatever comes to mind. Add (?) if unsure.]

- [e.g., No mobile app for now]
- [e.g., Never send user data to third parties]

For clarified:

# INTENT — [Project Name]

> status: clarified

## Why

Problem: [Who is suffering, and how?]
Goal: [What does success look like?]
Metric: [How do you measure it? Use numbers.]
Customer quote: [What would a happy user tell a friend? One sentence.]

## What

- [ ] [Feature 1 — one line]
- [ ] [Feature 2 — one line]
- [ ] [Feature 3 — one line]

User flow:
1. User does [A]
2. System does [B]
3. Result: [C]

Edge cases:
- [Case 1]
- [Case 2]

## Not

- Forbidden: [Hard security/ethical lines]
- Tech constraints: [e.g., no `any` types, TypeScript only]
- Out of scope: [What we're explicitly not building]
- Quality bar: [e.g., response time under 200ms]

Intent is not static. Experiment, then rewrite Why / What / Not so they state what you now believe. Do not append a log of results to INTENT.md; the file should always read as current intent.

Each result becomes an edit. Suppose an interview shows the real pain is invoice tracking, not analytics:

 ## Why

-Problem: SMB owners can't see where their revenue comes from.
+Problem: SMB owners lose track of unpaid invoices.

 ## What

-- [ ] Revenue analytics dashboard
+- [ ] Overdue invoice list with one-click reminder

 ## Not

+- Out of scope: analytics dashboards (interviews: nobody opened them)

Commit the change, and put what you learned in the message. The file holds the present; git log holds the path.

git commit -m "Why: pivot from analytics to invoice tracking

Interviewed 5 SMBs. All five named unpaid invoices as the top pain;
none asked for analytics."

Advance when evidence supports it. Drop when it doesn't.

seed → exploring
  When: You start your first experiment.

exploring → clarified
  When: Why/What/Not are all filled with conviction. No (?) marks remain.

any state → dropped
  When: Evidence shows this isn't worth building,
        or an existing solution covers it.
  Action: Set status to dropped. Say why in the commit message.
          This is valuable knowledge.

Once intent is clarified, INTENT.md is enough context for AI.

If you use Claude Code, move the constraints from Not into CLAUDE.md:

# CLAUDE.md

## Intent Constraints
- TypeScript only, no `any` types
- Never modify user data without explicit confirmation
- Response time under 200ms for all API endpoints

Let AI derive tasks, write code, review, and deploy. Update intent when reality changes.