Prd Writing

PRD Writing

When to use

Triggered by: "write a PRD", "draft a design doc", "spec out this feature", "create a PRD for X". Reserve this for changes where getting the design wrong is expensive to unwind — new cross-cutting mechanisms, schema changes, anything touching multiple subsystems. A one-file bug fix doesn't need this process.

Core principle: a PRD is a claim-verification exercise, not a writing exercise

Every sentence that asserts something about how the code currently works must be checked against the actual code before it goes in — not written from memory, not inferred from a plugin's name or reputation, not assumed because it sounds plausible. Two failure patterns to watch for:

• Calling a plugin "the cleanest case" for some behavior based on its category alone. Read the actual script — it may already report a live per-row signal and compute an equivalent value internally that was never wired up.
• Claiming "no changes needed" for a query based on one sub-case (e.g. a device that starts absent) without checking the transition sub-case (a device going from online to newly-suppressed) — the two sub-cases can use different existence checks, so a fix covering one can silently miss the other.

Both are plausible, well-written, and wrong. Reading the code first catches both.

Process

1. Understand the current mechanism by reading the actual code before writing anything. Cite file:line for every claim about current behavior. Delegate to an Explore/general-purpose agent for breadth if the surface area is large, but treat its findings as a starting point to spot-check, not a finished citation — verify anything load-bearing yourself before it goes in the PRD. The same applies to a prior audit or PRD this one continues from: re-read its full detail section for the specific finding, not just a one-line summary-table row, before citing or extending it — a summary row can omit a caveat ("already indexed," "already fixed elsewhere") that only the detail text states, and citing the row alone can reintroduce a claim the detail text already corrected.
2. Challenge the idea before designing it. If the user proposes a solution, ask: is this solving the right problem? Does it conflate unrelated concerns (see axis-separation, next)? Does a similar or previously-rejected mechanism already exist that this would collide with semantically? A naming near-collision with an existing field/concept that has different, incompatible semantics is a signal to stop and check precedence rules, not a coincidence to wave off.
3. Identify the independent axes. A feature request that arrives as "option A and option B" is often two or three orthogonal concerns bundled together — e.g. "should this exist at all," "should it notify," and "should it assert presence" are three separate questions, not one. Cramming them into a single enum/flag produces combinations you can't express later (what if a plugin wants A+C but not B?). Give each axis its own mechanism.
4. For every mechanism, trace every downstream consumer — not just the first one you find. The single highest-value question before calling a design complete: "where else does this exact same check or logic get independently re-derived?" In a codebase without one source of truth for a concept (e.g. "is this record currently active" computed by three different queries in three different files), patching the first occurrence and stopping is the most common way a design ships with a hidden, silent gap. Grep for the pattern, not just the function you already know about.
5. Record rejected alternatives with the reasoning, not just the chosen design. Give it its own subsection (### Rejected: X). Without this, a future reader — or your own future self — re-proposes the rejected idea because the "why not" only ever existed in a conversation, not in the document.
6. Force every open question to an explicit decision, even if the decision is "accept as-is for v1, revisit if feedback says otherwise." An open question left unresolved in a PRD gets silently decided by whoever implements it — usually differently than anyone actually intended.
7. Write the test plan as part of the PRD, not after. Concrete test cases — naming real functions/queries, not "add tests for X" — force you to notice design gaps you'd otherwise miss; the moment you try to write "assert Y happens" and realize the current design can't produce Y is often the first time the gap becomes visible. Check the repo for an existing test pattern for this shape of change before inventing a new one (e.g. a prior presence-logic bug fixed via test/db_test_helpers.py fixtures is the template for the next one, not a reason to build new test infrastructure).
8. Ask explicitly whether validating this needs real end-to-end infrastructure (a new or modified plugin, a UI click-through) or whether synthetic unit-level fixtures suffice — don't assume either way. Check whether the functions under test take a DB connection/dict/list as a parameter (testable in isolation, no real plugin needed) or require a real file on disk (harder to fake, may need one).
9. Check performance against the real schema and real scale, not assumptions. For every new or changed query: does it use an existing index, or add an unindexed lookup, a new join, or a correlated subquery? Grep CREATE INDEX for every index on the tables involved, not just the first one you find — a column can have both a plain index and a separate expression index (e.g. idx_eve_mac_date_type ON Events(eveMac, ...) alongside idx_eve_lower_mac_date_type ON Events(LOWER(eveMac), ...)), and missing the second one produces a wrong verdict. Then weigh cost by how often the query runs (once is nothing; every few minutes forever is a standing cost) and by real scale — production users run 10,000+ devices, not a homelab handful. A CurrentScan with 2-5 rows per device (one per contributing plugin) is routinely 20,000-50,000+ rows in one cycle; reason about that number, not a smaller hopeful one. A correlated EXISTS/subquery re-evaluated per outer row is fine if the correlated column is indexed — e.g. current_scan_presence_condition() (server/scan/presence.py) is exactly this shape against CurrentScan.scanMac, covered by idx_currentscan_scanmac. The real risk is an unindexed correlated lookup: an accidental self-join scanning the full inner table per outer row, which looks fine and passes tests at small scale but isn't at production scale. Check with EXPLAIN QUERY PLAN at a realistic row count, built against the complete real index set (copy every CREATE INDEX for the table, or run it against an actual app.db) rather than a hand-picked subset — a partial index set produces a misleading plan in either direction, not just "looks worse than it is." If it comes back unindexed for real, a GROUP BY aggregate is the usual fix.
10. Do a dedicated final-check pass, out loud, before calling it done. Re-read the whole document end to end and specifically check:
    • Did a correction made mid-document actually propagate everywhere it needed to (the Design subsection and Affected Files and Tests and any execution-plan summary)? A correction landing in one place and not its siblings is worse than never catching it, because now the document silently contradicts itself.
    • Does every "this is the cleanest/simplest real case" claim still hold up if you actually re-read that specific piece of code right now, or was it asserted by pattern-matching a name/category? Re-verify, don't re-assert.
    • Does anything render incorrectly as markdown — an unfenced ASCII diagram or code block will collapse into one line under lazy-paragraph-continuation, the same class of bug as a list missing its preceding blank line.
    • Do any internal anchor links' slugs actually match their headings?
    • Does the design still cleanly separate its axes, or did a later addition quietly re-conflate two concerns inside what's supposed to be a single-purpose mechanism (the same mistake step 3 exists to catch at the top level can reappear one level down inside an individual mechanism's own value set — e.g. a 3-value enum where two of the values are secretly independent booleans in a trenchcoat).
11. Leave a visible trail of corrections instead of silently rewriting. When a review pass — yours or someone else's — finds something wrong, write "Correction (caught in review): ..." inline rather than quietly fixing the earlier text and moving on. This is what makes a PRD trustworthy to a second reader: they can see what was checked and what changed, not just receive a polished final answer with no visible seams.

Structure to follow

• Problem — grounded in specific, cited current behavior, not a general complaint.
• Goals / Non-goals — non-goals should name specific things that sound in-scope but aren't, each with a one-line reason.
• Design — one subsection per independent axis/mechanism (step 3). Include a ### Rejected: X subsection for any alternative seriously considered (step 5).
• Open issues — each with an explicit recorded decision (step 6), not left dangling.
• Affected files — concrete file:function:line references, not bare filenames.
• Backward compatibility — explicit default values and why they preserve current behavior for existing consumers.
• Performance impact — the baseline (what's unindexed/slow today, independent of this change), what the change adds that's negligible, what's genuinely new and worth mitigating, and concrete mitigations rather than a vague "should be fine" (step 9).
• Docs/skills to update — anywhere this needs to be reflected outside the code itself (external docs, paired skill files, template files new authors copy from).
• Tests — organized by mechanism, each case naming the real function/query it exercises and the concrete assertion (step 7), plus a manual verification checklist for anything that can't be unit-tested (including an EXPLAIN QUERY PLAN check at realistic scale if the Performance impact section found a genuine risk).
• (Optional) Execution plan — phased, referencing the same file/function names used above rather than restating the design in vaguer terms.

Before starting: check for an existing architecture-reference skill

If a skill already documents the subsystem the feature touches, load it before researching from scratch — don't re-derive call graphs or mechanism details that are already written down. If the feature touches a subsystem with no such skill, and understanding it required significant re-derivation from raw code, that's a signal to write one afterward so the next PRD in that area doesn't start from zero.

Where to save

.gemini/internal-docs/PRDs/<kebab-case-name>.md, unless the user specifies otherwise. Mark the status line (**Status:** Draft — pending review) so it's clear this hasn't been approved yet, and keep the author line accurate about who actually made the calls (a design discussion with an assistant is not sole assistant authorship).