From 7c6df27778fa9bda6b98b2ee1d3ff3faa12ee479 Mon Sep 17 00:00:00 2001 From: lorentz Date: Sun, 3 May 2026 12:43:26 -0400 Subject: [PATCH] docs: define v1 requirements --- .planning/REQUIREMENTS.md | 148 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 148 insertions(+) create mode 100644 .planning/REQUIREMENTS.md diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md new file mode 100644 index 0000000..a1494a6 --- /dev/null +++ b/.planning/REQUIREMENTS.md @@ -0,0 +1,148 @@ +# Requirements: Pulse Mobile Shell Redesign + +**Defined:** 2026-05-03 +**Core Value:** A manager can open Pulse on their phone and, in under 30 seconds, see the state of the business and triage tickets — without ever needing to switch to desktop for read-only awareness. +**Source spec:** `docs/superpowers/specs/2026-05-03-mobile-shell-design.md` + +## v1 Requirements + +Requirements for this milestone. Each maps to a spec section and a roadmap phase. + +### PWA — Progressive Web App scaffolding (spec §4) + +- [ ] **PWA-01**: `public/manifest.json` exists with name "Pulse", short_name "Pulse", `display: "standalone"`, `start_url: "/mobile"`, theme/background colors matching dark and light shells +- [ ] **PWA-02**: Manifest is referenced from `app/layout.tsx` via `` +- [ ] **PWA-03**: Viewport meta in `app/layout.tsx` includes `viewport-fit=cover` +- [ ] **PWA-04**: Header and bottom tab bar respect `env(safe-area-inset-top)` and `env(safe-area-inset-bottom)` (Tailwind arbitrary values or shared utility class) + +### Shell — `/mobile` layout (spec §5) + +- [ ] **SHELL-01**: New `app/mobile/layout.tsx` replaces the current layout (rebuild in place — no parallel `/mobile-v2`) +- [ ] **SHELL-02**: Sticky top header: `bg-background/95 backdrop-blur` + bottom border; left = Wulf mark + "Pulse" wordmark linked to `/mobile/dashboard`; no page title in header +- [ ] **SHELL-03**: Header right slot — `Bell` icon button (placeholder, no menu/badge, `aria-label="Notifications"`, empty `onClick`, keyboard-accessible) +- [ ] **SHELL-04**: Header right slot — compact user avatar (`h-7 w-7`); tapping opens the More drawer +- [ ] **SHELL-05**: `
` content area is scrollable with bottom padding equal to bottom-nav height + safe-area inset +- [ ] **SHELL-06**: Fixed bottom nav: `border-t bg-background`, `max-w-lg mx-auto` wrapper, 5 cells (4 tabs + More) + +### NAV — Bottom tab bar (spec §3.1) + +- [ ] **NAV-01**: Four equal-width primary tabs: Dashboard (`LayoutDashboard`), Tickets (`Ticket`), Finance (`DollarSign`), Analyzer (`Sparkles`) +- [ ] **NAV-02**: Tabs route to `/mobile/dashboard`, `/mobile/tickets`, `/mobile/finance`, `/mobile/analyzer` +- [ ] **NAV-03**: Active state uses `text-primary`, inactive uses `text-muted-foreground`; active detection via `pathname.startsWith(href)` + +### DRAWER — More Sheet drawer (spec §3.2) + +- [ ] **DRAWER-01**: Fifth bottom-bar control labeled "More" with `Menu` icon opens a shadcn `Sheet` +- [ ] **DRAWER-02**: Sheet uses a single consistent side (`right` or `bottom`) — pick one and stay consistent +- [ ] **DRAWER-03**: Drawer top section "Mobile sections" lists Engagement (`/mobile/engagement`) +- [ ] **DRAWER-04**: Drawer middle section "Full site" lists desktop-only pages (Quotes, Configuration Items, Backup Status, Ticket Digest, Admin / Sync) each with `ExternalLink` icon +- [ ] **DRAWER-05**: Drawer bottom section "Account" shows current user (avatar + email, read-only) and a Sign out action that calls `signOut()` then `router.push('/auth/sign-in')` +- [ ] **DRAWER-06**: `app/mobile/nav/page.tsx` is deleted in the same change that ships the drawer + +### DASH — Mobile Dashboard (spec §6.1) + +- [ ] **DASH-01**: 2×2 KPI grid with four primary metric cards drawn from desktop dashboard hero stats +- [ ] **DASH-02**: "Needs Attention" horizontal-scroll strip of compact cards (overdue tickets, failed backups, stalled workflows); tapping a card opens its detail view +- [ ] **DASH-03**: Compact backup/worker status row showing analyzer worker, RMM worker, and backup-success-rate; read-only; tap opens desktop admin page +- [ ] **DASH-04**: No charts/recharts on the mobile Dashboard + +### TICK — Mobile Tickets list (spec §6.2) + +- [ ] **TICK-01**: Collapsible filter strip at top (`Collapsible` from shadcn), default collapsed; expanded shows status, priority, queue, assigned-to-me toggle +- [ ] **TICK-02**: Filter state syncs to URL query string for deep-linking +- [ ] **TICK-03**: List rows have left-edge color stripe by priority (Critical/High/Medium/Low → red/orange/amber/slate); body shows ticket #, title, company, age, assignee +- [ ] **TICK-04**: Single-tap on a row opens detail page +- [ ] **TICK-05**: Cursor-based infinite scroll (~25 per page) replaces pagination; next page triggers when last row enters viewport via IntersectionObserver +- [ ] **TICK-06**: "Load more" fallback button present for accessibility +- [ ] **TICK-07**: Detail page (`/mobile/tickets/[id]`) header reskinned to match new shell (Wulf mark, breadcrumb back); body kept largely as-is + +### FIN — Mobile Finance (spec §6.3) + +- [ ] **FIN-01**: Page restyled with new Card and typography scale; spacing fixed for small phones +- [ ] **FIN-02**: Wide tables on mobile widths replaced with stacked lists; no new data, no new sections + +### ANL — Mobile Analyzer feed (spec §6.4) — NEW PAGE + +- [ ] **ANL-01**: `/mobile/analyzer` route exists (read-only feed, most-recent-first stream of AI ticket analyses) +- [ ] **ANL-02**: Each list row shows ticket #, title, analyzer one-line summary, confidence badge, stage indicator (Triage → Analyze → Deep Review) +- [ ] **ANL-03**: Tapping a row opens a mobile summary view rendering Summary, Next Step, Next Step Rationale (all already produced by the analyzer pipeline) +- [ ] **ANL-04**: Summary view includes "View full analysis" link out to the desktop analyzer page +- [ ] **ANL-05**: No editing, no re-run, no prompt tuning on mobile +- [ ] **ANL-06**: Source data via `/api/mobile/analyzer/feed` (or reuse an existing list endpoint if it returns the right shape) reading from `analyzer_analyses` + +### ENG — Mobile Engagement (spec §6.5) — NEW PAGES + +- [ ] **ENG-01**: `/mobile/engagement` overview page (real refactor, not a thin adaptation of the ~1300-line desktop page) +- [ ] **ENG-02**: Period selector chip row (today / 7d / 30d) sticky just below the page H1 +- [ ] **ENG-03**: Summary cards stacked single-column (active users, total Graph hours, total Autotask hours, hours-per-active-user) — no 4-up grid on phone widths +- [ ] **ENG-04**: Per-employee list as stacked rows (avatar/initials, name, role, hours bar) with sort control above (sort by hours, name, utilization) and search input +- [ ] **ENG-05**: Top of list shows compact "hours trend" sparkline scoped to the selected period; no multi-series chart on mobile +- [ ] **ENG-06**: User profile is `/mobile/engagement/[userId]` (segment form preferred for shareable URLs); single-column layout: identity header → period selector → key metrics (compact) → activity breakdown list → recent items +- [ ] **ENG-07**: User profile is a real page, not a modal — replaces desktop user-detail modal pattern on mobile so back gesture works +- [ ] **ENG-08**: Profile reuses existing engagement profile data endpoints; no new data +- [ ] **ENG-09**: Engagement is reachable from the More drawer, NOT the bottom bar + +## v2 Requirements + +Acknowledged but deferred. Not in this milestone's roadmap. + +### NOTIF — Notifications + +- **NOTIF-01**: Real notification list behind the Bell icon (replaces SHELL-03 placeholder) +- **NOTIF-02**: Notification badge logic on the Bell icon + +### TABLET — Tablet breakpoint + +- **TABLET-01**: `md:max-w-2xl mx-auto` wrapper for tablet widths + +### OFFLINE — Offline support + +- **OFFLINE-01**: Service worker for offline cache +- **OFFLINE-02**: Push notifications (requires SW) + +### EDIT — Mobile editing + +- **EDIT-01**: Mobile editing on Engagement user detail +- **EDIT-02**: Mobile re-run / prompt edits on Analyzer + +## Out of Scope + +Explicitly excluded for v1. Documented to prevent scope creep. + +| Feature | Reason | +|---------|--------| +| Service worker / offline cache / push notifications | No clear offline use-case yet — defer until one lands (spec §4, §7) | +| Tablet breakpoint (`md:max-w-2xl`) | Noted as follow-up; keep `max-w-lg` for v1 (spec §4, §7) | +| Real notification list behind the Bell | Placeholder only this iteration; future phase wires it (spec §5.1, §7) | +| Mobile editing on Engagement user detail | Read-only on mobile by design (spec §6.5, §7) | +| Mobile re-run / prompt tuning on Analyzer | Read-only on mobile by design (spec §6.4, §7) | +| Charts / recharts on mobile Dashboard | Not earning their weight on small widths (spec §6.1, §7) | +| Restyling/replacing desktop pages reachable from More drawer | Desktop pages stay as-is (spec §7) | +| Multi-series chart on mobile Engagement overview | Replaced by single sparkline (spec §6.5) | +| Modal-based user detail on mobile | Replaced by real page so back gesture works (spec §6.5) | +| `/mobile-v2` parallel directory | Rebuild `/mobile` in place — keep canonical URLs (spec §2) | + +## Traceability + +Updated during roadmap creation. + +| Requirement | Phase | Status | +|-------------|-------|--------| +| PWA-01 to PWA-04 | TBD | Pending | +| SHELL-01 to SHELL-06 | TBD | Pending | +| NAV-01 to NAV-03 | TBD | Pending | +| DRAWER-01 to DRAWER-06 | TBD | Pending | +| DASH-01 to DASH-04 | TBD | Pending | +| TICK-01 to TICK-07 | TBD | Pending | +| FIN-01 to FIN-02 | TBD | Pending | +| ANL-01 to ANL-06 | TBD | Pending | +| ENG-01 to ENG-09 | TBD | Pending | + +**Coverage:** +- v1 requirements: 47 total +- Mapped to phases: 0 (pending roadmap) +- Unmapped: 47 ⚠️ (resolved by roadmapper) + +--- +*Requirements defined: 2026-05-03* +*Last updated: 2026-05-03 after initial definition*