Quick Start

Start with intent. Everything else is choice.

Choose a state

Choose the state that matches reality.

Choose one

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

Tip: Start at seed or exploring. Calling it clarified too early is how you build the wrong thing.

Create INTENT.md

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]

## Learnings

[Empty for now. You'll fill this as you explore.]

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]

## Learnings

- [Date] [What you tried] — [What you learned]

Explore, record, update

Intent is not static. Experiment, then update it.

Record each useful result in Learnings:

## Learnings

- [2026-04-01] Built prototype v1 — users ignored the dashboard, went straight to export
- [2026-04-03] Interviewed 5 SMBs — the real pain is invoice tracking, not analytics
- [2026-04-05] Found existing tool X — covers 80% of what we planned. Pivot to the 20% gap.

Then update Why / What / Not.

Tip: If a learning changes nothing in Why / What / Not, it probably does not matter yet.

Change state

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

State transitions

seed → exploring
  When: You start your first experiment.

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

any state → killed
  When: Evidence shows this isn't worth building,
        or an existing solution covers it.
  Action: Record why in Learnings. This is valuable knowledge.

Hand off to AI

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.

That's it. Keep INTENT.md current. Everything else is choice.