From c1eef01a664d9c50fb74c2feac5abd57c3b3df04 Mon Sep 17 00:00:00 2001 From: Satyam Rastogi Date: Fri, 29 May 2026 05:07:42 +0530 Subject: [PATCH] docs: master scope & rationale for the demo build (all phases + why) --- docs/superpowers/2026-05-29-MASTER-PLAN.md | 82 ++++++++++++++++++++++ 1 file changed, 82 insertions(+) create mode 100644 docs/superpowers/2026-05-29-MASTER-PLAN.md diff --git a/docs/superpowers/2026-05-29-MASTER-PLAN.md b/docs/superpowers/2026-05-29-MASTER-PLAN.md new file mode 100644 index 0000000..45245ec --- /dev/null +++ b/docs/superpowers/2026-05-29-MASTER-PLAN.md @@ -0,0 +1,82 @@ +# LynkedUp Pro Roofing — Demo Build: Master Scope & Rationale + +**Date:** 2026-05-29 · **Branch:** `revamp` +**This doc = the single "what we're doing and why."** Detailed specs live in `docs/superpowers/specs/`, step-by-step plans in `docs/superpowers/plans/`, and the subagent rules in the execution protocol. This is the map above all of them. + +--- + +## 1. Vision + +Turn the CRM's mock data and screens into **one coherent fake roofing company** ("LynkedUp Pro Roofing", Plano TX) that works as BOTH: +- a **live sales demo** to roofing-company prospects — believable, no empty/broken views, numbers that feel real at a glance, a continuous story you can walk; and +- an **investor pitch** — breadth, depth, and analytics that impress. + +**Guiding principle — coherence is the wow.** When a prospect drills from a dashboard KPI into the exact records that compose it, and from a project into the lead that created it and the subcontractor working it, and every name/number/date ties out — that is what sells. So we optimize for end-to-end internal consistency over surface polish, and we **compute analytics from the data** (not hardcode them) so they can never drift. + +**Audiences → implications:** dual sales+investor means everything must be coherent AND deep. No tab may be empty; every entity must trace to the others. + +--- + +## 2. Status snapshot + +- ✅ **Phase 1 — Data Foundation (DONE, reviewed APPROVED):** canonical identity (one id scheme), realistic **Texan roster** with unified `LUP-####` employee ids, reconciling project financials, seeded Leads page, reachable subcontractor logins, address-matched tasks, kanban lead values, and a per-role login picker. 14 commits, build clean. +- ⏳ Phases 2–7 below are planned/in-design. + +--- + +## 3. The work — phase by phase (What · Why · Key decisions) + +### Phase 2 — Unify lead↔project + routing/naming +**What:** A *won* kanban lead (stages Signed/In-Progress/Complete) becomes a first-class **project** sharing the SAME rich detail page as owner projects. Clean routes: everything won lives at `/owner/projects/:id` (and `/admin/projects`, `/emp/fa/projects`); pre-sale leads stay at `/…/leads/:id` (a lighter view). Unified human-meaningful ids (e.g. `PRJ-2026-014`). Kanban cards/links and the project list point at the unified route. +**Why:** Today there are **two parallel data models and two detail pages** for the same concept (a job): the `projects` array + `OwnerProjectDetail` (2,086 lines, 10 tabs, owner-only) vs `KANBAN_PROJECT_DATA` + `LeadProjectPage` (1,159 lines, thinner). That's why "lead pages don't match project pages" and routes feel inconsistent. Unifying makes the rich detail page, lifecycle, estimates, and analytics apply to won leads **for free** — one entity, one UI, no duplication to keep coherent. +**Key obstacles (from code exploration):** no join key exists between `kl_*` and `proj_*` (no shared id/address/FK); field-name mismatches (`estimatedAmount`↔`budget`, `completionPct`↔`completionPercentage`, `workTimeline`↔`activityTimeline`, invoice/RFI/CO date-field names differ); won leads lack `teamMembers`/`riskLog`/`issueLog`/`paymentSchedule`/`contractorId`/commission config; the commission engine needs `contractorId`/`salesRepId`+orgMembers; projects UI is owner-only so admin/field-agent need a projects route too; 4 navigation call-sites to update (LeadInfoDrawer, OwnerProjectList ×3). Id blast-radius is contained to `mockStore.jsx` but `proj_*` has inbound FKs from tasks/schedule/subcontractor data that must migrate together. +**Decisions made:** Unify (won lead IS a project). `/owner/projects/:id` + `PRJ-####`. Pre-sale leads show a lighter subset of the same page. + +### Phase 3 — Kanban/pipeline depth + analytics +**What:** All four kanban-data priorities — (1) realistic lead details (names, $ values, notes, dates), (2) rich per-lead project data matching the project detail, (3) coherent stage distribution + working pipeline $ total & conversion funnel, (4) storm attribution on leads. Plus the **10 threaded demo-case projects** (storm-win, insurance-backed up-scope→approved, up-scope→declined, down-scoped, multi-revision, over-budget, commercial, near-complete, completed, disputed) and a computed **`selectors.js`** analytics layer wired into owner/admin dashboards so KPIs tie out with detail screens. +**Why:** The pipeline must look like a busy real company (investor breadth), and a salesperson must be able to demo any scenario (sales). Computed analytics guarantee the dashboard never contradicts the records a prospect drills into. + +### Phase 4 — Project lifecycle + inspections + estimates +**What:** Make the existing **PROJECT PROGRESSION** bar interactive: a state machine (Lead → Damage Inspection Scheduled → Damage Verified → Scope Approved → Contract Signed → Work In Progress → Work Complete · Awaiting Inspection → Final Inspection → [Issues→Rework loop] → Completed → Final Payment Received) with **progress % correctly tied to the stage**. Two inspection touchpoints recorded with who did them: pre-sale **Damage Verification** (internal, name+role per project) and post-work **Final Inspection** by an **external examiner** (we store name + contact so they can be re-contacted, feedback, and `issues[]` each with description/note/photos/status; re-inspection keeps every round). A **claimed-vs-verified scope-variance** model with a visible badge (e.g. "Reported ~$200 → Verified $15,400"). An **estimate-versions** section per project (v1 from claim → v2 verified → signed), each opening the full rendered estimate document. +**Why:** The screenshot of `proj_003` shows the progression bar exists but its stage and the 42% completion don't agree — exactly the "progress % tied to stages" gap. Interactivity + the inspection loop + the scope-variance story are the core sales narrative (professional inspection turns a $200 self-report into an insurance-backed job). Uploads persist for the session (client-side), seeded with starting data. + +### Phase 5 — Subcontractor task stage machine +**What:** Replace the flat task statuses with: Not Assigned → Assigned → Pre-Work Inspection → Work In Progress → (On Hold ↔) → Post-Work Review → [Pass→Completed / Fail→Rework Needed (issue: what's wrong + note + photo) → back to Work In Progress]. Every transition carries an **optional note + timestamp + who set it**. Pre-Work Inspection and Post-Work Review record who performed them. Owner `/owner/subcontractor-tasks` table gains **Task Category** and **Assigned Date** columns; the task detail modal gets a richer progress timeline + issues list with photos. +**Why:** Mirrors the real field workflow and gives the subcontractor an interactive inbox; the review/rework loop is a credible operational story. + +### Phase 6 — Subcontractor portal data + project parity (`/subcontractor/`) +**What:** The subcontractor-facing pages (`/subcontractor/dashboard`, projects, task detail) get **realistic data** and, where they show a job, **the same project details as the owner sees** (a permitted subset of the unified project) — so a sub viewing their task sees the real project (address, scope, schedule, their slice of budget/payments) consistent with the owner's view. +**Why:** Coherence across logins is the demo's credibility test — the same job must look like the same job whether the owner or the subcontractor is looking. The Phase-2 unify makes this possible (one project entity); this phase wires the subcontractor views to it with appropriate visibility. + +### Phase 7 — Profiles, skill catalog & AI dispatch context +**What:** Every employee & subcontractor gets a two-layer `profile`: **self section** (preferred name, photo, contact, optional nickname/pronouns/gender/sex, bio, experience, languages, self-declared specialties + **equipment carried** e.g. "tarp/ladder rack"; subs: company/license/insurance) editable on a self-service **User Details** page (all roles incl. owners); and a **company section** (private to owner/admin): internal notes, status/tags, **skill scores** (a shared org **skill catalog** — name+description, each person 0–100 or N/A), pay terms. Employee **achievements & levels** (from ProCanvas gamification) surface read-only. An owner **Employee/Subcontractor Details** view shows the full profile. These feed **LynkDispatch**: `DISPATCH_REPS` map to canonical people and each recommendation's `skillMatch`/`reasons`/`aiInsight` **cite real profile facts** (equipment + skill scores), so "the AI read their profile" is demonstrably true on screen. +**Why:** Richer context = better, more believable AI dispatch recommendations (the investor "wow"), and the profile pages add depth a prospect expects from a mature CRM. + +--- + +## 4. Cross-cutting coherency requirements (the throughline) +- One canonical person per id, one name everywhere (done in Phase 1; every later phase must preserve it). +- A job is one entity (Phase 2) — lead→project→subcontractor task→invoices→commission all reference it and tie out. +- Dashboard KPIs == sums of the underlying records (Phase 3 computed selectors). +- The same job looks the same across owner / pipeline / subcontractor logins (Phases 2 & 6). +- Profiles/skills/equipment are cited by dispatch (Phase 7). +- No empty tabs, no "Unknown" labels, no future-dated mock data (anchor: `DEMO_TODAY` = 2026-05-29). + +--- + +## 5. Execution model +- **Subagent-driven:** controller extracts each task's full text + context, dispatches a fresh implementer per task, then spec + code-quality review; build gate (`npm run build` must be green) + targeted reconciliation checks per task; commit per task. +- **Parallelism (now allowed, with guardrails):** tasks that touch **disjoint files** may run in parallel. Tasks that share a file (especially `mockStore.jsx`) run **sequentially**. Each plan ships a **lane/ownership map** assigning every task an exclusive file set; the controller only parallelizes tasks whose lanes don't intersect, and never lets two in-flight agents write the same file. Commit between dependent tasks. (This generalizes the original strictly-sequential rule: sequential is the fallback when lanes overlap; parallel is allowed when they don't.) +- **No test framework exists** → verification is build + grep/reconciliation + dev-run, not unit tests. +- **Invariants every task preserves:** canonical ids + roster names; coherency requirements in §4. + +## 6. Plan / spec index +- Spec: `docs/superpowers/specs/2026-05-29-demo-data-coherence-design.md` +- Plan 1 (done): `docs/superpowers/plans/2026-05-29-demo-data-foundation.md` +- Execution protocol: `docs/superpowers/plans/2026-05-29-execution-protocol.md` +- Plans 2–7: to be authored from this master doc (Phase 2 next). + +## 7. Open decisions / deferred +- Stage-name wording tweaks (user said "I'll tweak a few" — proposed names stand until provided). +- Exact `PRJ-####` id format + whether pre-sale leads also get PRJ ids on conversion only. +- Per-plan lane maps (authored with each plan) to enable safe parallel execution.