Add optional customer-facing report to app-audit skill

.gitignore

@@ -2,5 +2,9 @@
 .DS_Store
 .glide/
 
-# Audit reports contain sensitive client data
+# Audit reports and screenshots contain sensitive client data
 audit-reports/
+# Root-level audit screenshots (e.g. captured during /app-audit)
+/*.jpeg
+/*.jpg
+/*.png

glide/commands/app-audit.md

@@ -95,6 +95,29 @@ Include:
 4. **Dependency diagram** - Mermaid showing computed column chains
 5. **Recommendations** - Based on Glide best practices
 
+### Phase 5b: Customer-Facing Report (optional)
+
+After delivering the technical report above, **offer** a plain-language version that can
+be shared directly with the customer:
+
+> "Want a customer-facing version of this you can send to the customer?"
+
+Also produce one whenever it's requested in natural language (a "customer-facing,"
+"shareable," or "plain-language" report). It is **additive** — never a replacement for the
+technical report, and built from the same findings (no re-analysis).
+
+- **Capture reported symptoms.** If the customer reported specific symptoms (e.g. "the
+  second tab is slow," "the list is blank until I reopen the app") — whether given in
+  `$ARGUMENTS` or in conversation — pass them through as `reportedSymptoms` so the report
+  leads with them (symptom → likely cause → steps). If a customer report is requested with
+  no symptoms given, ask once: *"Any specific symptoms the customer reported? Otherwise I'll
+  organize by Speed, Complexity, and Reliability."*
+- Follow `glide/skills/app-audit/procedures/generate-customer-report.md`, which applies
+  `glide/skills/app-audit/customer-report-guideline.md`.
+- **Omit** scores, severity labels, jargon, and any mention of internal-only tooling
+  (Dev Tools, the Performance Analysis tool, API tokens, support sessions). Keep the tone
+  tentative ("changes to try / should help").
+
 ## Dependency Diagram
 
 Generate a Mermaid diagram showing column relationships:
@@ -139,4 +162,5 @@ Generate a markdown report with:
 - Dependency diagram
 - Recommendations citing Glide documentation
 
-Display the report to the user after analysis is complete.
+Display the report to the user after analysis is complete, then offer the optional
+customer-facing report (Phase 5b).

glide/skills/app-audit/SKILL.md

@@ -6,6 +6,8 @@ description: |
   or providing recommendations for improving app speed and user experience.
   Automatically triggered when user provides a Glide app URL for audit, including
   read-only support-mode URLs of the form https://go.glideapps.com/support/{uuid}.
+  Can also produce an optional plain-language, customer-facing version of the report
+  on request, for sharing directly with the customer who reported the issue.
 ---
 
 # Glide App Audit
@@ -125,6 +127,11 @@ A report identifying:
 - **Computed column dependencies** - Chains that may cause cascading delays
 - **Layout issues** - Collections, images, screen weight
 
+**Optional customer-facing report:** After the technical report, you can also get a
+plain-language version to share directly with the customer (see Phase 5b). If the
+customer reported specific symptoms (e.g. "the second tab is slow," "the list is blank
+until I reopen"), provide them and the customer report will lead with those.
+
 ## Audit Workflow
 
 ### Phase 1: Connect to App
@@ -168,6 +175,20 @@ A report identifying:
 4. Note Query → Relation optimization opportunities
 5. Include recommendations based on Glide best practices
 
+### Phase 5b (optional): Customer-Facing Report
+After delivering the technical report, **offer** a plain-language version the operator
+can share directly with the customer — and produce one whenever it's requested in
+natural language ("a customer-facing / shareable / plain-language report").
+
+- It is **additive**: it never replaces the technical report, and it uses the same
+  findings (no re-analysis).
+- It **omits** scores, severity labels, jargon, and any mention of internal-only tools.
+- If the customer reported symptoms, capture them and the report leads with them
+  (symptom → likely cause → steps); otherwise it organizes by **Speed / Complexity /
+  Reliability**.
+- Follow [procedures/generate-customer-report.md](procedures/generate-customer-report.md),
+  which applies [customer-report-guideline.md](customer-report-guideline.md).
+
 ## Known Performance Issues
 
 ### From Glide Documentation
@@ -222,6 +243,8 @@ This helps visualize:
 **Plugin procedures:**
 - `procedures/fetch-app-data.md` - Data extraction
 - `procedures/analyze-layout.md` - UI inspection
+- `procedures/generate-customer-report.md` - Optional plain-language customer report
+- `customer-report-guideline.md` - How to translate findings for a customer audience
 
 ## Limitations
 

glide/skills/app-audit/customer-report-guideline.md

@@ -0,0 +1,118 @@
+# Customer-Facing Report Guideline
+
+How to translate a technical app-audit into a plain-language document you can share directly with a customer. This is the reference used by [procedures/generate-customer-report.md](procedures/generate-customer-report.md).
+
+The technical audit (see [procedures/generate-report.md](procedures/generate-report.md)) is written for a builder: scores, severities, and Glide internals. The **customer report** is a *re-presentation* of those same findings for the person who reported the problem — focused on what they can do to make their app faster, simpler, and more reliable.
+
+## When to Use
+
+Produce a customer report **only** when it's requested or when the post-audit offer is accepted. It is **additive** — it never replaces the technical report, and it is generated from the same audit findings (no new analysis).
+
+## Core Principles
+
+1. **Lead with the customer's reported symptoms.** If they said "the second tab is slow" or "the list is blank until I reopen the app," those become the top sections — each mapped to a likely cause and concrete steps. What the customer *feels* is the spine of the document, not the audit's internal ordering.
+2. **Explain the "why" in plain language.** Give the mechanism in everyday terms ("maps are the heaviest thing Glide draws on a phone," "a calculated value isn't ready the instant the screen opens, so the list looks empty until it loads"). Use the translation table below.
+3. **Stay tentative.** App performance is usually a combination of factors. Write "changes to try," "this should help," "likely contributor," "worth testing." Never "we found the root cause" or "this will fix it." Recommend changing one thing at a time and re-testing on a real phone.
+4. **Frame findings as observations.** "In our review we observed/measured…" — not "the Performance Analysis tool showed…" or "Dev Tools reports…". The customer didn't run those tools and shouldn't be told to.
+5. **Be honest about uncertainty.** If a fix's effect isn't guaranteed, say so ("worth testing rather than assuming"). If a reported symptom has no obvious cause in the findings, say that too — don't force a fit.
+6. **Separate quick wins from bigger projects.** Put "fixes for what you reported" (usually low-effort, do-first) ahead of "broader recommendations" (architecture: access control, data source, complexity).
+7. **Frame sensitive issues constructively.** A missing access-control or data-protection gap is "worth addressing," explained matter-of-factly with the risk and the fix — not an alarm.
+
+## What to Omit
+
+Do **not** include any of these in a customer report:
+
+- **The 0–100 performance score** or its category breakdown.
+- **Severity emoji as labels** (🔴 / 🟡 / 🟢) and words like "Critical/Warning/Optimization" used as severity tags.
+- **Internal-only tooling references:** "Dev Tools," "Performance Analysis tool," "API token," "Show API," "support session/support-mode URL," browser-automation/Playwright details.
+- **Internal process notes** ("the audit was data-layer-biased," "we missed this initially," self-corrections).
+- **Raw internal IDs** (App ID, native table IDs) unless the customer needs them to act.
+
+Replace any of the above with a neutral "in our review we observed…" framing. When pulling fix steps from [recommendations.md](recommendations.md), **reframe** them in plain language — do not copy phrasing that names internal tools.
+
+## Jargon → Plain-Language Translation Table
+
+| Technical term | Plain-language translation |
+|---|---|
+| Query column | a lookup that searches the whole table every time, which is slow |
+| Relation | a direct link between two tables, so Glide doesn't have to search |
+| Rollup | a running total or count calculated across many rows |
+| Computed column | a value Glide calculates rather than one you type in |
+| Deep / nested computed chain | calculations stacked many layers deep that recompute constantly |
+| Row Owners | row-level access control so each user only loads their own data |
+| Big Tables / 25,000-row limit | your table is near the size where Glide needs a different storage mode |
+| Column exceeds 100ms (Performance Analysis) | in our review we measured some values taking a noticeable moment to calculate |
+| Inline collection | a list embedded inside a detail screen |
+| Collection item count over ~24 | a long list loading all at once instead of in pages |
+| Map component | maps are the heaviest thing Glide draws on a phone |
+| Cached / not yet computed | a calculated value isn't ready the instant the screen opens, so the list looks empty until it loads |
+| First-screen weight | how much the very first screen has to load before it feels ready |
+| AI column | a field generated by AI, which adds processing time per row |
+| External data source (e.g. Google Sheets) | data synced from outside Glide, which can lag behind real-time |
+
+## Document Structures
+
+Pick one of two shapes depending on whether the customer gave you specific symptoms.
+
+### Symptom-led (preferred when symptoms are known)
+1. Short intro ("In our review of your app we looked at the data, the calculations, and the screens you mentioned…").
+2. **One section per reported symptom**, each with: what they're seeing → **likely cause** (plain language) → **changes to try** (numbered steps, ordered by expected impact).
+3. **Broader recommendations** — the architecture items, clearly separated from the quick fixes.
+4. **Priority table** (see below).
+5. **Things to check on your side** + an offer to help.
+
+### Theme-led (default when no symptoms were given)
+Same intro / priority table / closing, but the middle is organized into three themes:
+- **Speed** — what makes screens load and respond faster.
+- **Complexity** — simplifying calculations and structure so the app is easier to maintain and recompute.
+- **Reliability** — data correctness, access control, and avoiding "blank until reopen" style timing issues.
+
+### Priority table (both structures)
+A simple table the customer can act from. Pull the **Effort** estimate from the Fix Priority Matrix in [recommendations.md](recommendations.md) ("Time to Fix"). Do **not** include a Severity column.
+
+| # | Change | Effort | What it targets |
+|---|--------|--------|-----------------|
+| 1 | Plain-language change | Low / Medium / High | The symptom or theme it helps |
+
+Put the "fixes for what you reported" rows first.
+
+## Tone Conversion Examples
+
+| Technical (audit) | Customer-facing |
+|---|---|
+| "🔴 Critical: 3 Query columns exceed 100ms (2,478ms) on an 11,350-row table." | "In our review we measured a few calculations that each take a couple of seconds on your largest table — enough to slow the screen that uses them." |
+| "Replace Query columns with a Relation + Lookups (60–80% faster)." | "Switching these lookups to a direct link between the tables should make them much faster — it's Glide's recommended approach." |
+| "No Row Owners configured; full dataset synced to every client." | "Right now every user's app loads the whole database. Adding row-level access — so each person only loads their own records — should make the app faster and keeps each user's data private." |
+| "Deep computed chain (depth 14) tied to a live 'now' column." | "Some values are calculated through many stacked steps that recompute constantly because they're tied to the current time. Simplifying this should reduce the load." |
+
+## Constructive Framing of Sensitive Issues
+
+When the audit surfaces something like missing access control or personal data fully exposed:
+- State it plainly and briefly, with the concrete risk ("every signed-in user can see all records, including other people's").
+- Note any compliance angle factually ("worth reviewing from a data-protection standpoint"), not as alarm.
+- Immediately pair it with the fix and the upside ("adding Row Owners also makes the app faster, because each device loads less data").
+
+## Worked Example (symptom-led)
+
+> **Intro.** Thanks for flagging the slow screens. We looked through your app's data, calculations, and the two tabs you mentioned. Below is what we observed and some changes that should help — we'd suggest trying them one at a time and re-testing on a phone.
+>
+> **1. The second tab is slow to load.** This screen shows two maps of the same locations at once. Maps are the heaviest thing Glide draws on a phone, so two together is a likely cause of the slowness. *Changes to try:* (1) use a single map with different pin colors instead of two; (2) check the map plots from stored latitude/longitude rather than addresses, so it doesn't look up each location on every load.
+>
+> **2. A list is blank until I close and reopen the app.** That list filters on a value Glide has to calculate, and on a cold open it isn't ready yet — so the list briefly matches nothing and looks empty until it finishes (a reopen serves it from cache). *Changes to try:* (1) filter on the plain date field instead of the calculated one; (2) add an empty-state message so it's clear when a list is genuinely empty versus still loading.
+>
+> **Broader recommendations.** Your main data lives in an external source that syncs on a delay; moving the core tables into Glide should make values available faster and more reliably.
+>
+> | # | Change | Effort | What it targets |
+> |---|--------|--------|-----------------|
+> | 1 | Use one map instead of two; plot from stored coordinates | Low | Slow second tab |
+> | 2 | Filter the list on the plain date field; add an empty message | Low | Blank-until-reopen list |
+> | 3 | Move core tables into Glide | Medium–High | Reliability and speed overall |
+>
+> **A few things to check on your side:** does the location table store latitude/longitude, or just addresses? Is the date picker defaulting to today before the list draws? Happy to pair on the two quick fixes first.
+
+## References
+
+- [recommendations.md](recommendations.md) — source of the underlying fix steps (reframe in plain language).
+- [analysis-patterns.md](analysis-patterns.md) — source of the plain-language "why" behind each issue.
+- [procedures/generate-customer-report.md](procedures/generate-customer-report.md) — the procedure that applies this guideline.
+- [SKILL.md](SKILL.md) — main audit documentation.