From Raw Idea to PRD

The Gap Between Idea and Spec

A raw idea is not a spec. The gap between "we should add Discord notifications to the academy" and a buildable PRD is the research phase — a deliberate process of surfacing constraints before writing a single acceptance criterion.

Most practitioners skip this phase. They move from idea directly to requirements, missing two critical categories of information: what already exists in the system, and what callers will break if you change the output shape. Both are discovered in research, never in implementation.

The Four Stages

The journey from raw idea to structured PRD runs through four stages, each producing a more concrete artifact:

The critical observation is Stage 2: research surfaces the Agent Framework and Discord MCP as existing infrastructure. This changes the PRD entirely — instead of specifying "build a Discord webhook handler," the PRD specifies "integrate with the announce-lessons cron via the existing Discord MCP." That is 60% less implementation work discovered in 20 minutes of research.

Semantic Memory Layer-First Is the Protocol

Before writing a single line of any PRD, run memory_query("topic") in Semantic Memory Layer. The knowledge OS indexes 2,968 chunks across 43 repos — if something relevant exists in Knox's ecosystem, it surfaces here.

For the Discord notification example:

• memory_query("discord announce lessons") → surfaces announce-lessons cron, existing format
• memory_query("discord mcp production server") → surfaces Agent Framework integration, port, auth
• memory_query("discord notifications failure") → surfaces prior failure mode: Discord API rate limiting

Three queries, three pieces of information that improve the PRD before you write it. This is not optional overhead — it is how you avoid building in the dark.

The Six Questions

Once research is complete, the PRD structure falls out of answering six questions:

The order matters. You cannot answer "How do we measure success?" before you know "Who is the primary user?" — because success means different things to different users. A Discord channel announcement is successful if it reaches learners within 5 minutes; it is not successful if it only reaches the bot account.

The non-goals question is the one most often skipped. The discipline is to write at least three: one thing you won't build in this iteration, one system you won't touch, one capability to defer. These three lines prevent three classes of agentic scope creep.

The /prd-writer Skill

Knox's /prd-writer --from-doc skill takes a working document (research notes, conversation transcript, GitHub issue) and produces a structured PRD with all five required sections. It does not replace the six-questions thinking — it automates the structure around it.

The --decompose flag additionally splits the master PRD into per-phase PRDs in a docs/prd/ folder. This is covered in the “Decomposing a Master PRD” lesson, but understanding the decompose step starts here: only a well-structured master PRD with clear acceptance criteria can be decomposed successfully. A research-skipped PRD cannot be decomposed — its acceptance criteria are too vague to split.

Consumer Contract: The Hidden Research Step

There is a seventh research step that is easy to miss: grep existing callers before finalizing output shape.

If your PRD involves changing how a function returns data, you need to know who calls that function before you specify the new shape. The announce-lessons cron reads MDX frontmatter — specifically title, excerpt, and lesson fields. If your PRD specifies adding a notification_text field without checking whether the cron already handles it, you either break the cron or ship dead code.

# Run before writing any PRD that changes existing output shapes
grep -rn "getAllAcademyArticles" $(git ls-files)
grep -rn "frontmatter.title" $(git ls-files)

This grep belongs in the research phase, not the implementation phase. A consumer contract discovered post-implementation is a breaking change. Discovered pre-PRD, it is a constraint that improves the spec.

What the PRD Must Contain

After research, you have everything needed to write the PRD. The structure required (detailed in the next lesson):

• Context: Problem statement, affected users, why-now justification
• Goals and success criteria: Numeric thresholds, binary pass/fail
• Non-goals: Three or more explicit exclusions
• Consumer contracts: Callers identified by grep, output shape specified
• Acceptance criteria: Given/When/Then format, each maps to a test case

A PRD without all five is incomplete. The research phase is how you gather the raw material for all five. Skip research and you will write vague criteria, miss existing callers, and ship to a broken consumer.

What's Next

The next lesson goes inside the PRD itself — the anatomy of a good spec, what each section actually contains, and the concrete difference between vague acceptance criteria and testable ones. Understanding the internal structure is what makes the /prd-writer --from-doc output worth trusting.