# Recipe: From idea to PRD via `@briefing`

> **Who this is for:** anyone with a vague idea — phone notes, Notion draft, informal meeting conversation.
> **Time to run:** 30 to 90 min (depends on how much material you already have).
> **What you'll have at the end:** a PRD generated by `@product` based on an enriched briefing — no obvious gaps, risks mapped.

---

## The problem this recipe solves

You went straight to `@product` with a vague idea and heard:

> "Before creating a PRD, I need to understand the problem better. What is the main use case?"

This question loop happens because the idea has no shape yet. `@briefing` exists exactly for this step: it structures what exists before the PRD, so that `@product` arrives at the conversation with a solid foundation.

---

## The trail in one line

```
vague idea / notes
       ↓
   @briefing   →  .aioson/briefings/{slug}/briefings.md
       ↓
aioson briefing:approve
       ↓
   @product   →  prd.md (or prd-{slug}.md)
       ↓
 (optional) @sheldon  →  enrichment + phased plan
```

---

## Variant A — You already have drafts in `plans/`

This is the most common case: you researched, copied text, wrote ideas, and now have loose files.

### Step 1 — Put the material in `plans/`

```bash
# Files at the project root (gitignored by default)
plans/
├── idea-notifications.md     ← idea sketch
├── firebase-research.md      ← technical research you did
└── competitor-benchmark.md   ← analysis you copied from another chat
```

> `plans/` is **read-only for agents** — they read but never modify. Your files stay intact.
> See [External plans for @product](./external-plans-for-product.md) for details on this flow.

### Step 2 — Activate `@briefing`

```
You > @briefing

@briefing > Found 3 files in plans/:
             - plans/idea-notifications.md
             - plans/firebase-research.md
             - plans/competitor-benchmark.md

             Which ones should I use as source? (all or specific list)
You > All.

@briefing > Reading and enriching...
             Validating technical assumptions about Firebase push...

             Briefing generated: .aioson/briefings/push-notifications/briefings.md

             Summary:
             - Problem: users miss important events due to missing push
             - Validated hypotheses: 3/4
             - Gap found: maximum notification frequency not defined
             - Risk: Firebase rate limit on free plan (5,000/day)
             - Next step: approval via CLI → @product

             The briefing is ready. Do you want to adjust anything before approving?
```

**What was saved on disk:**
```
.aioson/briefings/push-notifications/
└── briefings.md    ← problem, hypotheses, gaps, risks, open questions
.aioson/briefings/
└── config.md       ← index of all briefings (status: draft)
```

### Step 3 — Review and approve

Read `.aioson/briefings/push-notifications/briefings.md`. If it looks good:

```bash
aioson briefing:approve
# or specify the slug:
aioson briefing:approve --slug=push-notifications
```

Status changes from `draft` to `approved`. `@product` detects this automatically.

### Step 4 — Activate `@product`

```
You > @product

@product > Detected approved briefing: push-notifications (created today).
            Can I use it as the base for this feature's PRD?
You > Yes.

@product > [reads briefing, asks questions only about what is missing]
            What is the feature slug?
You > push-notifications

@product > Main ACs I will include in the PRD:
            1. User receives push within ≤ 2s after event
            2. Rate limit respected (1 notification/min per user)
            3. Opt-out via settings (GDPR)

            Out of scope: email notifications (briefing flagged for phase 2).

            PRD created: .aioson/context/prd-push-notifications.md
            Next: @sheldon (recommended — there is 1 open technical risk in the briefing).
```

---

## Variant B — The idea is only in your head (conversational mode)

No files. No drafts. Just a desire to build something. When `plans/` is empty, `@briefing` enters **structured conversational mode** — a 6-step interview that builds the briefing question by question.

```
You > @briefing

@briefing > I didn't find any files in plans/. Would you like to plan
            the idea with me conversationally? I'll ask questions and
            build the briefing from your answers.
You > Yes.

─── Step A — Context (the "why now?") ───
@briefing > Tell me about the context: what is the current situation and
            what changed recently that made this surface today? A trigger
            always exists.
You > Customers are complaining they miss order updates.
      We had 3 support tickets last week.

─── Step B — Problem (JTBD framing) ───
@briefing > What specific pain point do you want to solve? For whom?
            What can't they accomplish today without working around it?
You > Customer places an order, closes the app, and has no idea if it was confirmed.

@briefing > Let me reframe as JTBD: "When I place an order and close
            the app, I want to know it was confirmed, so I don't have
            to go back and check." Does that fit?
You > Yes, exactly.

─── Step C — Proposed solution ───
@briefing > What directions are you considering? Multiple is fine —
            this is hypothesis, not commitment.
You > Push notification. Maybe SMS for orders above $500.

─── Step D — Risks (Cagan's four + cost of not acting) ───
@briefing > I'll ask in 4 passes:
            1. Value: will users want it? (or just tolerate it?)
            2. Usability: will they understand and configure it?
            3. Feasibility: can we build it?
            4. Viability: legal/compliance/cost/brand?
            And finally: what is the cost of NOT doing it?
You > [answers each one]

─── Step E — Gaps (current state vs desired state) ───
@briefing > For each undefined thing, let's frame it as:
            "today we have X, we want Y, the delta is Z (measurable when possible)".
            What is still open?
You > Maximum notification frequency per day. Today: undefined. We want: ?

─── Step F — Classify open questions ───
@briefing > I'll tag each question with one of:
            [research-able]      → < 4h of digging resolves it
            [testable]           → 1-2 day experiment
            [decision-required]  → judgment call between alternatives
            [out-of-scope]       → park it, doesn't block

            Result:
            1. Maximum frequency          [decision-required]
            2. Expected real engagement   [research-able]
            3. SMS for high-value orders  [out-of-scope — phase 2]

@briefing > 6 steps complete. Briefing generated:
            .aioson/briefings/order-notifications/briefings.md
```

> **Quality rule:** if more than 3 questions remain as `decision-required` or vague, `@briefing` does another round before writing. A rushed briefing is expensive later.

The rest of the flow is the same: approve via CLI → `@product`.

---

## What `@briefing` catches that `@product` wouldn't

| What it identifies | Example |
|---|---|
| Unvalidated market hypotheses | "Will users use push?" — it researches engagement data |
| Technical risks in the plan | Rate limits, latencies, volume costs |
| Scope gaps | Maximum notification frequency not defined |
| Internal contradictions | Draft says "real-time" but research shows prohibitive cost |
| Open decisions blocking the PRD | "Firebase or native APNS?" needs to be resolved first |

---

## When to skip `@briefing`

- Simple and clear feature: MICRO, no ambiguity — go straight to `@product`.
- You already have an enriched PRD — use `@sheldon` to refine it.
- It is a continuation of an already started feature — use `@deyvin`.

---

## Files created by this recipe

```
plans/                              ← your drafts (untouched)
.aioson/briefings/{slug}/
├── briefings.md                    ← @briefing output
└── {specific-theme}.md             ← (optional) complex themes
.aioson/briefings/config.md         ← briefings index
.aioson/context/prd-{slug}.md       ← @product output
```

---

## Next steps

- [External plans for @product](./external-plans-for-product.md) — how to use ChatGPT/Claude.ai output as source for `plans/`
- [Full feature with @sheldon](./full-feature-with-sheldon.md) — when the PRD is ready and the trail is SMALL/MEDIUM
- [@briefing — agent sheet](../4-agents/briefing.md) — technical reference for the agent
- [@product — agent sheet](../4-agents/product.md) — technical reference for the agent
