saqib mirandClaude Sonnet 5
e947ac44b8
/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>
52 lines
2.5 KiB
Markdown
52 lines
2.5 KiB
Markdown
# 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)
|
|
|
|
1. Create a knowledge entry for a product. **Expected**: `status: draft`.
|
|
2. Query `/knowledge/retrieve?productId=...`. **Expected**: entry absent.
|
|
3. Publish it. **Expected**: `status: published`.
|
|
4. Query retrieval again. **Expected**: entry present.
|
|
|
|
## Scenario 2 — editing preserves history (User Story 1)
|
|
|
|
1. Edit the published entry's content with the correct `expectedVersion`.
|
|
2. **Expected**: a new version is created (`version: 2`); `GET .../versions` shows both version 1
|
|
(with its original content) and version 2 (current).
|
|
3. 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)
|
|
|
|
1. Read the entry's current `version`.
|
|
2. Attempt two edits using the same `expectedVersion`.
|
|
3. **Expected**: exactly one succeeds; the other receives `409 CONFLICT`.
|
|
|
|
## Scenario 4 — known issue resolves by error code (User Story 2)
|
|
|
|
1. Create an error code (e.g. `LAYOUT_PARSE_042`).
|
|
2. Create a known issue referencing it.
|
|
3. `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)
|
|
|
|
1. Create a runbook with an explicit ordered step list.
|
|
2. Look it up by key. **Expected**: steps are returned in the exact authored order.
|
|
3. 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)
|
|
|
|
1. Seed a published entry for Product A and a published entry for Product B with similar content.
|
|
2. Query retrieval scoped to Product A. **Expected**: only Product A's entry appears.
|
|
3. Seed two otherwise-equal entries for the same product, one `validated`, one `unvalidated`.
|
|
4. 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.
|