name: source-driven-development description: > Cite HexDocs before writing framework code. Use when implementing unfamiliar Phoenix/LiveView/Ecto API or when user asks "is this the right way to X".

Source-Driven Development

Every framework decision must be backed by official docs. Don't implement from memory — verify, cite, flag unverified.

Process

DETECT → FETCH → IMPLEMENT → CITE

Step 1: Detect Stack and Versions

Read mix.exs for exact versions:

STACK DETECTED:
- Phoenix 1.8.x (from mix.exs)
- LiveView 1.0.x
- Ecto 3.12.x
- Tailwind CSS 4.x
→ Fetching relevant HexDocs.

Step 2: Fetch Official Docs

Source hierarchy (order of authority):

Not authoritative: Stack Overflow, blog posts, tutorials, training data.

Be precise:

BAD:  Fetch the Phoenix homepage
GOOD: Fetch hexdocs.pm/phoenix_live_view/Phoenix.LiveView.html#stream/4

Step 3: Implement Following Documented Patterns

• Use API signatures from docs, not memory
• Docs show new way → use new way
• Docs deprecate pattern → don't use it

When docs conflict with existing code:

CONFLICT:
Existing code uses `live_redirect` but Phoenix 1.8 docs say
use `push_navigate` instead (deprecated in 1.7).
Source: hexdocs.pm/phoenix_live_view/Phoenix.LiveView.html

Options:
A) Use modern pattern (push_navigate)
B) Match existing code for consistency
→ Which approach?

Step 4: Cite Sources

# Phoenix LiveView stream with reset for filtering
# Source: hexdocs.pm/phoenix_live_view/Phoenix.LiveView.html#stream/4
socket
|> stream(:messages, messages, reset: true)

In conversation:

Using stream/4 with reset: true for filtering, per LiveView docs.
Source: hexdocs.pm/phoenix_live_view/Phoenix.LiveView.html#stream/4

If docs not found:

UNVERIFIED: Could not find official docs for this pattern.
Based on training data — verify before using in production.

Rationalizations vs Reality

Red Flags

• Writing Phoenix/Ecto code without checking HexDocs for that version
• Using "I believe" about API instead of citing source
• Using deprecated APIs (live_redirect, form_for, etc.)
• Not reading mix.exs before implementing