Deep Interview

User: "It should sync in real-time."

You: "Before we go further — when you say real-time, I want to make sure
we mean the same thing.

Are you describing sub-second updates (like a live cursor in Google Docs),
or near-real-time (updates within 5-10 seconds, like a dashboard refresh)?"

Round 3 answer: "It should work on mobile"
Round 7 answer: "We need complex drag-and-drop reordering"

You: "I noticed a potential tension: mobile-first AND complex drag-and-drop
are difficult to do well together on small screens.

Which is the higher priority — mobile-first UX, or the drag-and-drop capability?"

User: "I think we need a message queue, but I'm not sure which one."

You: "Before I continue — would it help if I looked at your current infrastructure
and compared your options? I can give you a specific recommendation
based on what you already have, rather than a generic answer."

tldr structure .
# then check package.json / docker-compose / infra files

"Before I write the spec, let me confirm what I've understood:

You're building [feature name] for [persona] to solve [problem].

The core journey: [user does X, system does Y, user sees Z].

Key decisions made:
- [Decision 1]: [what was chosen and why]
- [Decision 2]: [what was chosen and why]
- [Decision 3]: [what was chosen and why]

Explicitly out of scope:
- [Item 1]
- [Item 2]

Current ambiguity score: [X]%

Is this accurate, or did I misunderstand anything?"

# PRD: [Feature Name]
**Date**: YYYY-MM-DD
**Ambiguity Score**: X% (at time of writing)
**Interview Rounds**: N questions across N rounds

---

## Problem Statement

[2-3 sentences: the problem, who has it, why it matters now]

---

## User Stories

### Core Story (P0)
As a [persona], I want to [action], so that [benefit].

**Acceptance Criteria**:
- [ ] Given [context], when [action], then [observable outcome]
- [ ] Given [error condition], when [action], then [error is handled by showing X]
- [ ] Given [edge case], when [action], then [correct behavior]

### Secondary Stories (P1)
[Same format, lower priority]

### Deferred Stories (P2 — out of scope for this version)
[Listed but explicitly not in scope]

---

## Technical Requirements

### Stack Constraints
- [Framework / language / runtime requirements]
- [Must integrate with: X, Y, Z]
- [Must NOT use: X (reason)]

### Performance Requirements
- [Latency: < Xms at P99]
- [Throughput: N requests/second]
- [Concurrent users: N]

### Data Requirements
- [What is stored, where, how long]
- [Privacy / compliance requirements if any]

---

## Out of Scope

Explicitly excluded from this version:
- [Item 1]: [reason — deferred to v2 / handled elsewhere / out of product scope]
- [Item 2]: [reason]
- [Item 3]: [reason]

---

## Edge Cases

| Scenario | Expected Behavior |
|----------|-------------------|
| [User does X twice] | [System does Y] |
| [Empty state] | [Shows Z] |
| [Dependent service down] | [Graceful degradation: shows A, retries after B] |
| [Invalid input] | [Validation message: C] |
| [Rate limit exceeded] | [429 response with retry-after header] |

---

## Success Metrics

How to verify this feature works:
- [ ] [Metric 1: measurable, testable]
- [ ] [Metric 2]
- [ ] [Acceptance test that can be run manually]

---

## Ambiguity Score Breakdown

| Dimension | Score | Open Questions |
|-----------|-------|----------------|
| Functional requirements | X% | [any remaining open items] |
| Technical constraints | X% | [any remaining open items] |
| Edge case coverage | X% | [any remaining open items] |
| Success criteria | X% | [any remaining open items] |
| Scope boundaries | X% | [any remaining open items] |
| Integration points | X% | [any remaining open items] |
| **Weighted total** | **X%** | |

---

## Decisions Log

Decisions made during the interview that are non-obvious:

| Decision | What was chosen | Why | Alternative rejected |
|----------|-----------------|-----|----------------------|
| [Topic] | [Choice] | [Reason] | [What we didn't pick and why] |

---

## Implementation Notes

Observations for the developer that came out of the interview:

- [Technical detail that will matter during implementation]
- [Known risk or dependency that needs to be handled upfront]
- [Suggested starting point based on existing patterns in the codebase]

"Spec written at [path]. How would you like to proceed?

1. Start planning: I'll break this into implementation tasks with estimates
2. Implement now: I'll begin building, following the spec
3. Review first: Take time to read the spec, implement later
4. Get a second opinion: I'll run a pre-mortem on the spec for risks"

"To implement: use '/implement [feature-name] spec' or hand this to your
implementation agent with the spec path as context.

The spec includes acceptance criteria that can be used for drift prevention
— check alignment every 5 edits."

Spawn plan-agent or invoke /create_plan with the spec path.

INTERVIEW STATE
  feature: [working name]
  persona: [who uses it]
  codebase_type: [greenfield|brownfield]
  rounds_completed: N
  ambiguity: {
    functional: X%,
    technical: X%,
    edge_cases: X%,
    success: X%,
    scope: X%,
    integration: X%,
    weighted: X%
  }
  decisions: [list of decisions made]
  open_conflicts: [list of unresolved tensions]
  confirmed_out_of_scope: [explicit exclusions]

You: "What problem are you solving? Tell me about the person who has this problem."

User: "I want to add notifications to the app."

You: [Detected: user described a solution, not a problem]
    "Before we dig into notifications — what's happening right now that
    notifications would fix? What does a user miss because they don't get notified?"

User: "Users miss when someone comments on their post. They have to check manually."

You: [Ambiguity updated: functional 60%, persona partially clear]
    "Got it — users who post content miss engagement. Walk me through the moment
    a notification should fire: someone posts, someone else comments... at what
    exact point does the poster need to know?"

User: "When the comment is submitted."

You: [Brownfield check: let me look at the existing comment system]
    [Runs: tldr structure . → finds POST /api/comments endpoint in routes/comments.ts]
    "I can see the comment submission endpoint in routes/comments.ts.
    Should the notification trigger inside that endpoint, or as an event
    after the comment is saved to the database?"

[... interview continues ...]

Round 8 — Edge Cases:
You: "What should happen if the notification system is down — should comment
submission still succeed, or should it fail if the notification can't be sent?"

User: "It should still succeed. Notifications are nice-to-have."

You: [Key decision logged: notification failure = non-blocking]
    "Confirmed — comments succeed regardless of notification outcome.
    One more edge case: if a user comments on their own post, should they
    receive a notification about it?"

[... completion at round 11, ambiguity = 17%]

You: "Before I write the spec, let me confirm...
    [summary]
    Current ambiguity: 17%. Ready to generate the PRD."