Files

T

saqib mirandClaude Sonnet 5 e947ac44b8 docs: plan and design artifacts for product knowledge feature

/speckit-plan output for 004-product-knowledge: technical context and
constitution gate check (all PASS), Phase 0 research (6 decisions:
new-row-per-version instead of in-place overwrite to satisfy history
retention, conditional-update-then-insert concurrency reusing
003-ticketing's optimistic-locking pattern, structured (non-semantic)
filtered retrieval per doc 11 gap B1, known-issue lookup by error
code, creating the ai-support module group for the first time with
only its knowledge submodule populated, and admin auth consistent
with prior features), Phase 1 data model (KnowledgeEntry/ErrorCode/
KnownIssue/Runbook, refining doc 06's conceptual schema with an
explicit version-history mechanism), the admin CRUD + retrieval
contract, and a 6-scenario quickstart.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

2026-09-02 15:30:46 +05:30

2.5 KiB

Raw Blame History

Quickstart: Validating Product Knowledge Management & Retrieval

Prerequisites: a registered Product (from 002-saas-integration's admin endpoints or seeded directly), migrations applied.

Scenario 1 — draft is invisible, publish makes it retrievable (User Story 1)

Create a knowledge entry for a product. Expected: status: draft.
Query /knowledge/retrieve?productId=.... Expected: entry absent.
Publish it. Expected: status: published.
Query retrieval again. Expected: entry present.

Scenario 2 — editing preserves history (User Story 1)

Edit the published entry's content with the correct expectedVersion.
Expected: a new version is created (version: 2); GET .../versions shows both version 1 (with its original content) and version 2 (current).
Query retrieval. Expected: only version 2's content appears — version 1 is not retrievable live, only through the admin history view.

Scenario 3 — a stale edit is rejected (Edge Cases / concurrency)

Read the entry's current version.
Attempt two edits using the same expectedVersion.
Expected: exactly one succeeds; the other receives 409 CONFLICT.

Scenario 4 — known issue resolves by error code (User Story 2)

Create an error code (e.g. LAYOUT_PARSE_042).
Create a known issue referencing it.
GET .../known-issues/by-error-code/LAYOUT_PARSE_042. Expected: the known issue is returned directly, no search step needed.

Scenario 5 — a runbook's step order is preserved exactly (User Story 2)

Create a runbook with an explicit ordered step list.
Look it up by key. Expected: steps are returned in the exact authored order.
Deactivate it. Expected: lookup by key no longer returns it (treated the same as nonexistent).

Scenario 6 — retrieval never crosses product scope, and validated ranks first (User Story 3)

Seed a published entry for Product A and a published entry for Product B with similar content.
Query retrieval scoped to Product A. Expected: only Product A's entry appears.
Seed two otherwise-equal entries for the same product, one validated, one unvalidated.
Query retrieval. Expected: the validated entry appears first in the result order.

What "done" looks like

All six scenarios pass, and together they demonstrate every functional requirement and success criterion in spec.md without needing to read the implementation to know what "correct" means.

2.5 KiB Raw Blame History