support_backend/specs/004-product-knowledge/spec.md

# Feature Specification: Product Knowledge Management & Retrieval

**Feature Branch**: `004-product-knowledge`

**Created**: 2026-09-02

**Status**: Draft

**Input**: User description: "Phase 3 of docs/10-implementation-roadmap.md: Knowledge/KnownIssue/
ErrorCode/Runbook models, admin CRUD, versioning + publish state, retrieval (RAG) layer. Per
docs/03-ai-support-architecture.md section 2-3 and docs/06-database-schema.md."

## User Scenarios & Testing *(mandatory)*

### User Story 1 - An admin authors, versions, and publishes knowledge entries (Priority: P1)

An administrator creates a knowledge entry for a product (a known issue, FAQ, resolution
procedure, or operations note), scoped to the right product/feature/category. The entry starts
as a draft, invisible to retrieval. When the admin publishes it, it becomes eligible for
retrieval from its effective date onward. Editing a published entry creates a new version rather
than silently rewriting history, and the admin can mark an entry as validated once it's been
confirmed to actually work.

**Why this priority**: Nothing else in this feature (or the future AI-support feature that
depends on it) has anything to retrieve until knowledge exists, is scoped correctly, and has a
trustworthy draft/published/validated lifecycle — retrieving an unreviewed draft as if it were
trustworthy guidance would be worse than retrieving nothing.

**Independent Test**: Create a draft knowledge entry, confirm it's not retrievable; publish it,
confirm it becomes retrievable from its effective date; edit it, confirm the edit produces a new
version and the prior version remains inspectable.

**Acceptance Scenarios**:

1. **Given** an admin creates a knowledge entry, **When** it's saved without being published,
   **Then** it exists with `status: draft` and is never returned by any retrieval query.
2. **Given** a draft entry, **When** an admin publishes it with an effective date, **Then** it
   becomes eligible for retrieval starting at that date — not before.
3. **Given** a published entry, **When** an admin edits its content, **Then** the edit is
   recorded as a new version (incrementing `version`), and the entry's prior content remains
   retrievable by version rather than being overwritten.
4. **Given** a published entry, **When** an admin marks it `validationStatus: validated`,
   **Then** that status is visible on every retrieval result that includes it.
5. **Given** a published entry, **When** an admin unpublishes it, **Then** it immediately stops
   being returned by retrieval, without being deleted.

---

### User Story 2 - Known issues, error codes, and runbooks are modeled as first-class, product-scoped records (Priority: P2)

Beyond general knowledge entries, an admin can catalog specific known issues (linked to a
structured error code) and author runbooks — ordered, versioned step sequences for a specific
problem type. These are distinct from freeform knowledge entries because they're referenced
structurally (by error code, by runbook key) rather than only found through search.

**Why this priority**: Knowledge entries alone (User Story 1) already deliver standalone value —
this story adds the structured lookup paths (a specific error code, a specific runbook key) doc
03's example ("searches: feature documentation → error catalog → known issues → troubleshooting →
runbooks") depends on, but a knowledge base without them is still useful.

**Independent Test**: Create an error code and a known issue referencing it; look the known issue
up by error code and confirm it resolves; create a runbook with an ordered step sequence for a
product; look it up by its key and confirm the exact step order is preserved.

**Acceptance Scenarios**:

1. **Given** an admin creates an error code for a product, **When** it's saved, **Then** it has a
   unique, product-scoped code (e.g. `LAYOUT_PARSE_042`) and a description.
2. **Given** an existing error code, **When** an admin creates a known issue referencing it,
   **Then** the known issue can be looked up directly by that error code.
3. **Given** an admin creates a runbook for a product with an ordered list of steps, **When** it's
   saved, **Then** the step order is preserved exactly as authored — never reordered or
   deduplicated by the system.
4. **Given** an existing runbook, **When** an admin edits its steps, **Then** the edit is recorded
   as a new version, matching User Story 1's versioning behavior for knowledge entries.
5. **Given** a runbook, **When** an admin deactivates it, **Then** it's excluded from lookup
   without being deleted — the same active/inactive convention as User Story 1's publish state.

---

### User Story 3 - Retrieval returns only relevant, filtered, validation-aware knowledge for a given context (Priority: P3)

Given a product, and optionally a feature/category/problem-type context, a retrieval query
returns only the knowledge entries that are published, past their effective date, and scoped to
that context — never an unfiltered dump of everything in the knowledge base. When both a
validated and an unvalidated entry are otherwise equally relevant, the validated one is
preferred.

**Why this priority**: This is what makes the knowledge base actually usable by a future
caller (the AI-support feature) instead of just an admin content library — but it depends on
User Stories 1 and 2 existing first, and doc 03 itself frames full semantic retrieval as a later
design decision (see Assumptions), so this story delivers the retrieval *contract* now without
requiring a vector/embedding pipeline to exist yet.

**Independent Test**: Seed knowledge entries across two different products, query retrieval
scoped to one product, and confirm only that product's published, effective entries are
returned — never the other product's, never drafts, never entries not yet effective; seed one
validated and one unvalidated entry that are otherwise equally relevant, and confirm the
validated one is ranked first.

**Acceptance Scenarios**:

1. **Given** knowledge entries across multiple products, **When** a retrieval query is scoped to
   one product, **Then** only that product's entries are ever returned.
2. **Given** a mix of draft and published entries, **When** a retrieval query runs, **Then**
   drafts are never returned, regardless of how well they'd otherwise match.
3. **Given** a published entry whose effective date is in the future, **When** a retrieval query
   runs before that date, **Then** the entry is not returned.
4. **Given** a validated and an unvalidated entry that both match a query, **When** results are
   returned, **Then** the validated entry is ranked ahead of the unvalidated one.
5. **Given** a retrieval query with no matches, **When** it runs, **Then** it returns an empty
   result — never an error, and never a fallback to unrelated knowledge.

---

### Edge Cases

- What happens when an admin tries to publish a knowledge entry with no content (empty
  problem/solution fields)? Out of scope for strict validation here — this feature stores what's
  given; a content-quality review workflow is not part of this phase.
- What happens when two knowledge entries could both plausibly answer the same query (e.g. a
  known issue and a general FAQ)? Both are returned if both match the filters — ranking beyond
  validation-status preference (User Story 3 Scenario 4) is explicitly not solved here; true
  relevance ranking is the future semantic-retrieval work in Assumptions.
- What happens when a runbook is looked up by a key that doesn't exist, or exists but is
  inactive? It's treated as not found either way — an inactive runbook is not distinguishable
  from a nonexistent one to a retrieval caller, only to an admin managing it directly.
- What happens when an error code is deleted while a known issue still references it? Out of
  scope — this feature doesn't implement deletion of error codes that have active references;
  only unpublish/deactivate operations are defined (Scenarios above), matching the rest of the
  system's "never hard-delete support-domain records" convention.

## Requirements *(mandatory)*

### Functional Requirements

- **FR-001**: The system MUST let an admin create a knowledge entry scoped to a product, and
  optionally to a feature and one or more categories.
- **FR-002**: A knowledge entry MUST have a `status` of `draft`, `published`, or `unpublished`,
  and MUST default to `draft` on creation.
- **FR-003**: A knowledge entry MUST only be returned by retrieval when its status is
  `published` AND its effective date is at or before the current time.
- **FR-004**: Editing a published knowledge entry's content MUST create a new version
  (incrementing a version counter) rather than overwriting the existing version in place; prior
  versions MUST remain retrievable by their own identity.
- **FR-005**: A knowledge entry MUST carry a `validationStatus` (`unvalidated` or `validated`),
  independently settable by an admin from its publish status.
- **FR-006**: The system MUST let an admin create an error code scoped to a product, unique
  within that product.
- **FR-007**: The system MUST let an admin create a known issue referencing an error code, and
  retrieve a known issue directly by its error code.
- **FR-008**: The system MUST let an admin create a runbook for a product as an ordered list of
  steps, preserving the authored order exactly.
- **FR-009**: Editing a runbook's steps MUST create a new version, matching FR-004's behavior for
  knowledge entries.
- **FR-010**: A runbook MUST have an active/inactive state; lookup by key MUST NOT return an
  inactive runbook, and MUST NOT distinguish "inactive" from "does not exist" in its response.
- **FR-011**: A retrieval query MUST be scoped to at least a product, and MAY be further filtered
  by feature and/or category; it MUST NEVER return entries outside the specified product scope.
- **FR-012**: A retrieval query MUST NEVER return a `draft` or `unpublished` entry, or an entry
  whose effective date has not yet arrived.
- **FR-013**: When multiple retrieved entries are otherwise equally relevant to a query, entries
  with `validationStatus: validated` MUST be ranked ahead of unvalidated ones.
- **FR-014**: Every knowledge entry MUST carry `owner` and `lastReview` fields an admin can set,
  supporting future staleness detection — this feature does not implement staleness detection
  itself, only the fields it depends on.

### Key Entities

- **Knowledge Entry**: A versioned, product-scoped piece of guidance (known issue, FAQ,
  resolution procedure, or operations note) with a draft/published/unpublished lifecycle, a
  validation status, and retrieval-filtering scope (product/feature/category).
- **Error Code**: A structured, product-scoped error identifier (e.g. `LAYOUT_PARSE_042`) with a
  description, referenced by known issues.
- **Known Issue**: A product-scoped problem record, optionally linked to an Error Code,
  describing a recognized issue and its status.
- **Runbook**: A versioned, ordered sequence of troubleshooting steps for a product, looked up by
  a stable key, with an active/inactive state — the step *sequence itself* is data owned by this
  feature; *executing* a runbook against a live conversation is the future AI-support feature's
  job, not this one's.

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-001**: 100% of draft knowledge entries are absent from every retrieval query result,
  verified across every entry type.
- **SC-002**: 100% of retrieval queries scoped to one product return zero entries belonging to
  any other product.
- **SC-003**: An admin can publish a knowledge entry and have it appear in retrieval results
  within the same request cycle — no propagation delay.
- **SC-004**: Editing a published entry never loses the prior version's content — it remains
  retrievable by an admin after the edit, 100% of the time.
- **SC-005**: A validated entry is ranked ahead of an equally-matching unvalidated one in 100% of
  retrieval results that include both.
- **SC-006**: A known issue is resolvable by its error code in a single lookup, without a
  separate search step.

## Assumptions

- **Full semantic (embedding/vector) retrieval is explicitly out of scope for this feature** —
  per `docs/11-architect-additions-gaps-and-recommendations.md` §B1, the embedding model,
  chunking strategy, and re-ranking approach are technical decisions for the future AI-support
  feature (Phase 4) to make, not this one. This feature implements retrieval as structured,
  deterministic filtering (product/feature/category scope, status, effective date,
  validation-status preference) — a real, usable retrieval contract, not a placeholder — that a
  future semantic layer can sit in front of without changing the underlying data model or the
  guarantee that filters apply before any ranking (doc 11 §B1's explicit ordering requirement).
- Runbook *execution* (the workflow engine that controls which step is permitted next during a
  live AI conversation, per `docs/03-ai-support-architecture.md` §6) is explicitly out of scope —
  this feature only stores and versions the step data; the future AI-support feature interprets
  and executes it.
- Content-quality validation (e.g. requiring non-empty fields before publish) is not enforced by
  this feature — an admin can publish sparse content; a content-review workflow is not part of
  this phase.
- Deletion of knowledge entries, error codes, known issues, or runbooks is out of scope — only
  publish/unpublish and active/inactive state changes are defined, consistent with this system's
  broader convention of never silently losing support-domain history.