# 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

- [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. ss-tools Stack Compatibility

- [x] CHK005 Gradio integration reuses existing `@assistant_tool` registry (ADR-0008) — no duplicate tool registration.
- [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 ≥85% — measurable via acceptance test suite.
- [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: Existing UX patterns preserved — measurable via regression test suite.

## 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 20 functional requirements cover: streaming, tool use, 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`.
