support_frontend/specs/001-agent-admin-ui/checklists/requirements.md

Specification Quality Checklist: Agent and Admin UI

Purpose: Validate specification completeness and quality before proceeding to planning Created: 2026-09-07 Feature: spec.md

Content Quality

• No implementation details (languages, frameworks, APIs)
• Focused on user value and business needs
• Written for non-technical stakeholders
• All mandatory sections completed

Requirement Completeness

• No [NEEDS CLARIFICATION] markers remain
• Requirements are testable and unambiguous
• Success criteria are measurable
• Success criteria are technology-agnostic (no implementation details)
• All acceptance scenarios are defined
• Edge cases are identified
• Scope is clearly bounded
• Dependencies and assumptions identified

Feature Readiness

• All functional requirements have clear acceptance criteria
• User scenarios cover primary flows
• Feature meets measurable outcomes defined in Success Criteria
• No implementation details leak into specification

Notes

• Scope is Phase 10 per supporthub-api's docs/10-implementation-roadmap.md, translated into this project's own first feature: the agent workspace and the admin configuration surfaces for support organization, SLA/business-calendars, and escalation — the subsystems an agent's own day-to-day workflow (User Stories 1-2) most directly depends on existing and being configurable first.
• Deliberately excludes the (public)/(customer) portals, real-time push sync, analytics/ reporting, audit-log viewing, platform settings, and AI-confidence-policy administration — each flagged explicitly in Assumptions as follow-up scope, not an oversight, to keep this first feature reviewable rather than attempting all of Phase 10's roadmap line in one spec.
• FR-012 and Edge Cases both restate this project's own Constitution Principle II (the backend is the sole source of business logic) as testable requirements, not just governance — every acceptance scenario that touches a business-rule rejection (US2 scenario 2, US3 scenario 3, US5 scenario 3) exists specifically to keep that principle enforced, not merely aspirational.
• All items pass; no revision iterations were needed.
• Post-approval amendment: this spec originally assumed agent/admin identity arrived the same pre-authenticated way customer identity does (delegated from the parent SaaS host), with no frontend-owned login screen needed — FR-011 and an Edge Case both said "SaaS-provided role." supporthub-api's 010-identity-auth (built after this spec's initial approval) established that agent/admin login is supporthub-api's own, separate authentication, never SaaS-delegated — the same correction already made to both projects' constitutions. Added User Story 0 (sign-in, P1, more foundational than US1), FR-000, SC-006, a new Edge Case, and reworded FR-011/the existing Edge Case/the closing Assumption to say "supporthub-api session role" instead of "SaaS-provided role." This is a correction of a wrong premise, not new scope creep — nothing else in User Stories 1-7 changes.
• Implementation-time finding: two structural issues with this project's existing scaffold only surfaced by actually running the app, not by inspection — (1) with this project's src/ directory layout, Next.js requires middleware.ts to live at src/middleware.ts, not the repo root; the pre-existing empty middleware.ts had been scaffolded in the wrong location. (2) next.config.mjs's output: 'export' (static HTML export) is fundamentally incompatible with Next.js Middleware — the dev server refused to run it outright. Removing static export is a deployment-mode change (this app now needs next build && next start, not a static file host), flagged to and confirmed by the user before making it, since it has real infrastructure implications beyond this feature's own code.
• A second discovered blocker, upstream of this feature entirely: supporthub-api had no endpoint to list "tickets currently assigned to agent X" at all, and no way to resolve a logged-in session to its own agent roster row — User Story 1 had no data source without it. Resolved by a new supporthub-api feature, 011-agent-ticket-queue, built and merged into this feature's own data-model.md/contracts before Setup began.
• Implementation-time findings, User Stories 1-3: a research agent asked to verify exact backend request/response shapes was run in an isolated git worktree and reported supporthub- api's entire problem-management module as unimplemented stubs — false, an artifact of the worktree being based on main, which doesn't include the unmerged 009-problem-resolution branch this session's own backend work already completed and verified. Re-checked directly against the actual working branch instead; the real schemas were all present. Lesson for this project specifically: don't use worktree isolation for a pure read-only lookup against a feature branch — it silently serves a stale, wrong branch state with no warning.
• That same direct re-check caught two real contract mismatches in this feature's own lib/api/tickets.ts, both fixed before they shipped: getTicketMessages was calling the customer-safe GET /tickets/:id/messages (excludes internal notes) instead of the agent-facing GET /agent/tickets/:id/messages FR-002 actually needs; and postMessage's body was {body, visibleToCustomer} instead of the real {type, body} — visibleToCustomer is always server-derived from type, never client-supplied (003-ticketing's own visibility mapping).
• Solution/SolutionVerification have no GET endpoint in supporthub-api (only Investigation/ RootCause/Resolution do) — ProblemResolutionPanel tracks those two stages' progress in local session state rather than a persisted read-back, an explicit, documented scope decision (data-model.md), not an oversight; Investigation/RootCause gating uses the real GET endpoints instead, so those two stages stay correct across a page reload.
• All Setup/Foundational/User Story 0-3 work (T001-T041) verified with real, locally-running supporthub-api + supporthub-web servers — 8 Playwright E2E scenarios passing against live data, not mocks, in addition to the mocked unit/integration suite.
• Implementation-time findings, User Stories 4-7 (tasks-p2-p3.md): planning for these four stories surfaced three more of the same "existing domain, never exposed as a read query" gaps 011-agent-ticket-queue's own kind — a business calendar's holidays could be added/removed but never read back at all; GET /admin/escalation-policies returned bare policies with no way to see which rules already existed under one; and knowledge-governance needed a way to list entries including drafts, which GET /knowledge/retrieve (published-only) can't provide. All three were fixed as small follow-up commits to supporthub-api's own 012-admin-list-views rather than new spec-kit cycles, given how narrow and mechanical each one was (one Prisma include or one new query method) — this pattern (backend gaps discovered mid-frontend-work) recurred often enough this session to be worth naming explicitly for future work on this pair of projects: build the consuming screen's contract first, verify each read against the actual schema, and expect roughly one small backend gap per admin-configuration domain touched.
• A second, unrelated implementation-time bug, caught only by submitting a real form against a live backend (not by any mocked test): CalendarEditor's default timezone value was "UTC", which Intl.supportedValuesOf('timeZone') — what supporthub-api validates against — does not contain at all (no bare "UTC", no "Etc/UTC") — only full region-based IANA names like "America/New_York" are valid. Every mocked integration test for this screen passed anyway, since the mock never exercised the backend's own validation — a reminder that this feature's own "verify against a real backend" discipline (not just mocked tests) is what this class of bug needs to be caught by.
• All User Story 4-7 work (T042-T071) verified the same way as US0-3: real, locally-running supporthub-api + supporthub-web servers, 3 additional Playwright E2E scenarios passing against live data (creating a real calendar/holiday/SLA-policy, a real escalation policy/rule against a real hierarchy node, and reading the real product catalog), alongside the mocked unit/integration suite (26 tests total across both task lists).