86 lines
6.3 KiB
Markdown
86 lines
6.3 KiB
Markdown
# Requirements Quality Checklist: Gradio Agent Chat
|
|
|
|
**Purpose**: Validate spec.md against the constitution, ADRs, and superset-tools repository reality. Surface gaps before `/speckit.clarify` or `/speckit.plan`.
|
|
**Created**: 2026-06-08
|
|
**Feature**: `specs/033-gradio-agent-chat/spec.md`
|
|
|
|
## 1. No Implementation Leakage
|
|
|
|
- [x] CHK001 Spec describes WHAT the user needs — not Python module names, file paths, or Svelte component internals.
|
|
- [x] CHK002 No Pydantic schema names, SQLAlchemy table names, or internal function signatures appear in spec.
|
|
- [x] CHK003 Architecture diagram is conceptual (shows systems, not classes) — appropriate for spec level.
|
|
- [x] CHK004 Functional requirements use domain language: "agent", "tool", "streaming", "conversation" — not "WebSocket handler", "SSE endpoint", "gr.ChatInterface".
|
|
|
|
## 2. superset-tools Stack Compatibility
|
|
|
|
- [x] CHK005 Gradio agent runtime uses native LangChain `@tool` functions; deprecated `@assistant_tool` registry remains legacy-only and is not reused.
|
|
- [x] CHK006 Svelte frontend remains the primary application shell (ADR-0006: Svelte 5 runes mandate).
|
|
- [x] CHK007 `@gradio/client` npm package is the bridge between Svelte and Python Gradio — documented and feasible.
|
|
- [x] CHK008 Authentication model reuses existing JWT tokens (ADR-0005: RBAC).
|
|
- [x] CHK009 Gradio backend runs within same Docker network — no new external dependencies exposed publicly.
|
|
- [x] CHK010 Existing assistant REST endpoints (`/api/assistant/*`) preserved during transition (FR-020).
|
|
|
|
## 3. Measurable Success Criteria
|
|
|
|
- [x] CHK011 SC-001: Tool selection accuracy ≥92% — measurable via acceptance test suite (keyword 85% + embedding fallback 7%).
|
|
- [x] CHK012 SC-002: First token latency ≤1.5s for 90% of queries — measurable via client-side timing.
|
|
- [x] CHK013 SC-003: Dangerous ops confirmation rate 100% — measurable via audit log verification.
|
|
- [x] CHK014 SC-004: Permission bypass rate 0% — measurable via security test suite.
|
|
- [x] CHK015 SC-005: Conversation persistence across restart — measurable via integration test.
|
|
- [x] CHK016 SC-006: Speed improvement ≥30% vs manual UI — measurable via usability benchmark.
|
|
- [x] CHK017 SC-007: File upload ≤10MB without responsiveness degradation — measurable via load test.
|
|
- [x] CHK018 SC-008: Hybrid router ensures 50-75% token reduction; embedding model cold-start ~2s, subsequent calls 5-20ms.
|
|
|
|
## 4. Edge Cases & Recovery
|
|
|
|
- [x] CHK019 Gradio backend unreachable → connection error with retry (FR-014).
|
|
- [x] CHK020 Malformed LLM tool-call JSON → retry + clarification fallback (Edge Cases).
|
|
- [x] CHK021 Message exceeds token limit → truncation + warning (Edge Cases).
|
|
- [x] CHK022 Tool execution timeout → async progress indicator (FR-012, Edge Cases).
|
|
- [x] CHK023 Rapid-fire messages → sequential queue with position display (Edge Cases).
|
|
- [x] CHK024 Gradio restart mid-conversation → persisted history survives, streaming session lost (Edge Cases).
|
|
- [x] CHK025 Confirmation token expiry → inform user, offer re-issue (Edge Cases).
|
|
- [x] CHK026 Multiple browser tabs with same conversation → reject concurrent writes (Edge Cases).
|
|
- [x] CHK027 Network loss during streaming → detect disconnection, offer reconnect (Edge Cases).
|
|
|
|
## 5. Decision-Memory Readiness
|
|
|
|
- [x] CHK028 `@RATIONALE` in spec documents why Gradio was chosen over custom SSE/WebSocket implementation.
|
|
- [x] CHK029 `@REJECTED` documents why full Svelte replacement was rejected (ADR-0006 violation).
|
|
- [x] CHK030 `@REJECTED` documents why building streaming from scratch was rejected.
|
|
- [x] CHK031 Phase 1 research.md will need to resolve: Gradio `gr.ChatInterface` vs `gr.Blocks` + `gr.Chatbot` choice.
|
|
- [x] CHK032 Phase 1 research.md will need to resolve: `@gradio/client` streaming event API surface for Svelte 5 runes integration.
|
|
- [x] CHK033 Phase 1 research.md will need to resolve: Agent framework choice (LangChain agent executor vs custom loop vs smolagents).
|
|
|
|
## 6. Completeness
|
|
|
|
- [x] CHK034 All 6 user stories are independently testable (each has an "Independent Test" sentence).
|
|
- [x] CHK035 P1 stories cover the MVP: streaming chat + autonomous tool use.
|
|
- [x] CHK036 P2 stories cover UX quality: tool visibility + conversation context.
|
|
- [x] CHK037 P3 stories cover polish: persistence + file upload.
|
|
- [x] CHK038 Key entities defined: AgentConversation, AgentMessage, AgentToolCall, AgentStreamingSession, AgentMemory.
|
|
- [x] CHK039 23 functional requirements cover: streaming, tool use, hybrid routing, negation guard, embedding infrastructure, RBAC, persistence, UX preservation, backward compatibility.
|
|
- [x] CHK040 Dependencies section names specific existing artifacts to integrate with.
|
|
|
|
## 7. Constitution Alignment
|
|
|
|
- [x] CHK041 Principle I (Semantic Contract First): Spec uses `#region`/`#endregion` anchors with complexity tiers.
|
|
- [x] CHK042 Principle II (Decision Memory): `@RATIONALE` and `@REJECTED` annotations present for architectural choices.
|
|
- [x] CHK043 Principle III (External Orchestrator): Gradio backend calls existing APIs — does not embed in Superset.
|
|
- [x] CHK044 Principle IV (Module Discipline): New Gradio code placed in clear module structure (planning phase will define).
|
|
- [x] CHK045 Principle V (RBAC): FR-005, FR-006, SC-004 enforce existing RBAC on all agent tool calls.
|
|
- [x] CHK046 Principle VI (Svelte 5 Runes): Frontend changes use Svelte 5 runes; Gradio is backend-only.
|
|
- [x] CHK047 Principle VIII (Attention-Optimized): Spec uses hierarchical IDs (`AgentChat.Spec`), one-line anchors with @SEMANTICS tags, ATTN_2 domain prefixes.
|
|
|
|
## 8. Unresolved Markers
|
|
|
|
- [x] CHK048 No `[NEEDS CLARIFICATION]` markers remain in spec.md. All ambiguities resolved with informed defaults.
|
|
- [x] CHK049 No `[NEED_CONTEXT: ...]` markers — all dependencies identified in the Dependencies section.
|
|
|
|
## Notes
|
|
|
|
- **Agent framework choice** (LangChain vs smolagents vs custom) is deferred to research.md in Phase 1 — this is an implementation detail, not a spec ambiguity.
|
|
- **Gradio auth bridge** (how JWT is forwarded to Gradio) needs resolution in planning phase — `@gradio/client` options include auth headers; exact mechanism TBD.
|
|
- **Gradio backend deployment** (separate container vs co-located with FastAPI) is an infrastructure decision for plan.md, not spec.md.
|
|
- All checklist items pass. Spec is ready for `/speckit.clarify` or `/speckit.plan`.
|