ss-tools/specs/033-gradio-agent-chat/checklists/requirements.md

Requirements Quality Checklist: Gradio Agent Chat

Purpose: Validate spec.md against the constitution, ADRs, and ss-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

• CHK001 Spec describes WHAT the user needs — not Python module names, file paths, or Svelte component internals.
• CHK002 No Pydantic schema names, SQLAlchemy table names, or internal function signatures appear in spec.
• CHK003 Architecture diagram is conceptual (shows systems, not classes) — appropriate for spec level.
• CHK004 Functional requirements use domain language: "agent", "tool", "streaming", "conversation" — not "WebSocket handler", "SSE endpoint", "gr.ChatInterface".

2. ss-tools Stack Compatibility

• CHK005 Gradio integration reuses existing @assistant_tool registry (ADR-0008) — no duplicate tool registration.
• CHK006 Svelte frontend remains the primary application shell (ADR-0006: Svelte 5 runes mandate).
• CHK007 @gradio/client npm package is the bridge between Svelte and Python Gradio — documented and feasible.
• CHK008 Authentication model reuses existing JWT tokens (ADR-0005: RBAC).
• CHK009 Gradio backend runs within same Docker network — no new external dependencies exposed publicly.
• CHK010 Existing assistant REST endpoints (/api/assistant/*) preserved during transition (FR-020).

3. Measurable Success Criteria

• CHK011 SC-001: Tool selection accuracy ≥85% — measurable via acceptance test suite.
• CHK012 SC-002: First token latency ≤1.5s for 90% of queries — measurable via client-side timing.
• CHK013 SC-003: Dangerous ops confirmation rate 100% — measurable via audit log verification.
• CHK014 SC-004: Permission bypass rate 0% — measurable via security test suite.
• CHK015 SC-005: Conversation persistence across restart — measurable via integration test.
• CHK016 SC-006: Speed improvement ≥30% vs manual UI — measurable via usability benchmark.
• CHK017 SC-007: File upload ≤10MB without responsiveness degradation — measurable via load test.
• CHK018 SC-008: Existing UX patterns preserved — measurable via regression test suite.

4. Edge Cases & Recovery

• CHK019 Gradio backend unreachable → connection error with retry (FR-014).
• CHK020 Malformed LLM tool-call JSON → retry + clarification fallback (Edge Cases).
• CHK021 Message exceeds token limit → truncation + warning (Edge Cases).
• CHK022 Tool execution timeout → async progress indicator (FR-012, Edge Cases).
• CHK023 Rapid-fire messages → sequential queue with position display (Edge Cases).
• CHK024 Gradio restart mid-conversation → persisted history survives, streaming session lost (Edge Cases).
• CHK025 Confirmation token expiry → inform user, offer re-issue (Edge Cases).
• CHK026 Multiple browser tabs with same conversation → reject concurrent writes (Edge Cases).
• CHK027 Network loss during streaming → detect disconnection, offer reconnect (Edge Cases).

5. Decision-Memory Readiness

• CHK028 @RATIONALE in spec documents why Gradio was chosen over custom SSE/WebSocket implementation.
• CHK029 @REJECTED documents why full Svelte replacement was rejected (ADR-0006 violation).
• CHK030 @REJECTED documents why building streaming from scratch was rejected.
• CHK031 Phase 1 research.md will need to resolve: Gradio gr.ChatInterface vs gr.Blocks + gr.Chatbot choice.
• CHK032 Phase 1 research.md will need to resolve: @gradio/client streaming event API surface for Svelte 5 runes integration.
• CHK033 Phase 1 research.md will need to resolve: Agent framework choice (LangChain agent executor vs custom loop vs smolagents).

6. Completeness

• CHK034 All 6 user stories are independently testable (each has an "Independent Test" sentence).
• CHK035 P1 stories cover the MVP: streaming chat + autonomous tool use.
• CHK036 P2 stories cover UX quality: tool visibility + conversation context.
• CHK037 P3 stories cover polish: persistence + file upload.
• CHK038 Key entities defined: AgentConversation, AgentMessage, AgentToolCall, AgentStreamingSession, AgentMemory.
• CHK039 20 functional requirements cover: streaming, tool use, RBAC, persistence, UX preservation, backward compatibility.
• CHK040 Dependencies section names specific existing artifacts to integrate with.

7. Constitution Alignment

• CHK041 Principle I (Semantic Contract First): Spec uses #region/#endregion anchors with complexity tiers.
• CHK042 Principle II (Decision Memory): @RATIONALE and @REJECTED annotations present for architectural choices.
• CHK043 Principle III (External Orchestrator): Gradio backend calls existing APIs — does not embed in Superset.
• CHK044 Principle IV (Module Discipline): New Gradio code placed in clear module structure (planning phase will define).
• CHK045 Principle V (RBAC): FR-005, FR-006, SC-004 enforce existing RBAC on all agent tool calls.
• CHK046 Principle VI (Svelte 5 Runes): Frontend changes use Svelte 5 runes; Gradio is backend-only.
• CHK047 Principle VIII (Attention-Optimized): Spec uses hierarchical IDs (AgentChat.Spec), one-line anchors with @SEMANTICS tags, ATTN_2 domain prefixes.

8. Unresolved Markers

• CHK048 No [NEEDS CLARIFICATION] markers remain in spec.md. All ambiguities resolved with informed defaults.
• 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.