From e9bdf85f0e05d7f2e57943f6498ed56bd8958a58 Mon Sep 17 00:00:00 2001 From: GeorgeB Date: Tue, 9 Jun 2026 16:39:51 -0400 Subject: [PATCH] Add optional customer-facing report to app-audit skill Adds a customer-report-guideline.md reference and a generate-customer-report.md procedure that translate technical audit findings into a plain-language, shareable document organized by speed, complexity, and reliability (or by reported symptoms). Wires an optional post-audit offer into SKILL.md and the command, and ignores root-level audit screenshots. Co-Authored-By: Claude Opus 4.8 --- .gitignore | 6 +- glide/commands/app-audit.md | 26 +++- glide/skills/app-audit/SKILL.md | 23 +++ .../app-audit/customer-report-guideline.md | 118 +++++++++++++++ .../procedures/generate-customer-report.md | 134 ++++++++++++++++++ 5 files changed, 305 insertions(+), 2 deletions(-) create mode 100644 glide/skills/app-audit/customer-report-guideline.md create mode 100644 glide/skills/app-audit/procedures/generate-customer-report.md diff --git a/.gitignore b/.gitignore index fe98bac..5c048fa 100644 --- a/.gitignore +++ b/.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 diff --git a/glide/commands/app-audit.md b/glide/commands/app-audit.md index c0cf884..5801cf6 100644 --- a/glide/commands/app-audit.md +++ b/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). diff --git a/glide/skills/app-audit/SKILL.md b/glide/skills/app-audit/SKILL.md index fa63cb2..d4fccf7 100644 --- a/glide/skills/app-audit/SKILL.md +++ b/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 diff --git a/glide/skills/app-audit/customer-report-guideline.md b/glide/skills/app-audit/customer-report-guideline.md new file mode 100644 index 0000000..10b93c6 --- /dev/null +++ b/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. diff --git a/glide/skills/app-audit/procedures/generate-customer-report.md b/glide/skills/app-audit/procedures/generate-customer-report.md new file mode 100644 index 0000000..15d2641 --- /dev/null +++ b/glide/skills/app-audit/procedures/generate-customer-report.md @@ -0,0 +1,134 @@ +# Generate Customer Report Procedure + +Translate a completed app-audit into a plain-language, shareable document for the customer who reported the issue. + +## Overview + +This procedure produces an **additional, optional** artifact. It does **not** replace the technical report from [generate-report.md](generate-report.md) — it re-presents the same findings for a non-technical reader, focused on helping them optimize their app for **speed, complexity, and reliability**. + +It performs **no new analysis**. It consumes the analysis object already produced by the audit and reframes it according to [../customer-report-guideline.md](../customer-report-guideline.md). + +**Read [../customer-report-guideline.md](../customer-report-guideline.md) first** — it defines the tone, the omit-list, and the jargon→plain-language table this procedure depends on. + +## Input + +The same combined analysis object consumed by [generate-report.md](generate-report.md): + +```javascript +{ + appId, appName, auditDate, + dataAnalysis: { issues: [...], tableAnalysis: [...], summary: {...}, scores: {...} }, + layoutAnalysis: { issues: [...], screenAnalysis: [...], scores: {...} } +} +``` + +Each issue keeps its existing shape: `{ severity, category, type, location, description, details, impact, recommendation }`. + +**Plus** one optional input: + +```javascript +reportedSymptoms: ["the second tab is slow", "the list is blank until I reopen the app"] +// or free text; or omitted entirely +``` + +If `reportedSymptoms` is not supplied and a customer report is requested, ask once: +> "Any specific symptoms the customer reported? Otherwise I'll organize the report by Speed, Complexity, and Reliability." + +## Output + +A standalone markdown document, presented **after** the technical report. Do not overwrite or merge into the technical report. + +## Mode Selection + +- **`reportedSymptoms` present →** use the **symptom-led** structure. +- **Absent →** use the **theme-led** structure (Speed / Complexity / Reliability). + +Both structures are defined in [../customer-report-guideline.md](../customer-report-guideline.md#document-structures). + +## Issue → Theme Mapping (theme-led mode) + +Group the existing issues into the three customer themes. Map by `issue.type` / `issue.category`: + +| Theme | Issue types that belong here | +|-------|------------------------------| +| **Speed** | deep-column-chain, rollup-without-relation, heavy-ai-usage, large-collection / item-count, inline-collection-overload, component-overload, heavy first screen, large images | +| **Complexity** | many relations, nested computed chains, query-columns (could be relations), high computed-column percentage, duplicate/leftover tabs and screens | +| **Reliability** | computed-value-not-ready / "blank until reopen" timing, row-limit (approaching/exceeded), missing access control (no Row Owners), external data source / sync lag | + +An issue may legitimately appear under more than one theme (e.g., Query columns affect both Speed and Complexity) — place it where it most helps the customer act, and don't repeat it. + +## Symptom → Likely-Cause Mapping (symptom-led mode) + +For each reported symptom, find the detected issue(s) that most plausibly explain it. Examples: + +| Reported symptom | Likely causes to look for in the findings | +|------------------|-------------------------------------------| +| A tab/screen is slow to load | Heavy first-screen weight; multiple Maps on one screen; collection item count over ~24; expensive computed columns (AI, Query, rollups) shown in a collection on that screen | +| A list/collection is blank until reopen | A filter that compares a **computed value** not ready at first paint; external data source still syncing; an experimental column type feeding the filter | +| App is slow overall | Missing Row Owners (whole dataset synced to every device); external data source; high computed-column load | +| Data looks wrong / out of date | External data source sync lag; rollup operating on a table instead of a relation | + +State the connection tentatively ("a likely contributor is…"). **If no detected issue plausibly explains a symptom, say so honestly** ("we didn't find an obvious cause for X in our review; here's what we'd check") rather than forcing a fit. + +## Translating Findings + +For every issue you include: +1. Rewrite the **description/impact** using the jargon→plain-language table in the guideline. +2. Pull the **fix steps** from [../recommendations.md](../recommendations.md) for that issue type, and **reframe them in plain language** — do not copy phrasing that names internal tools. +3. Apply the tone rules: tentative ("changes to try / should help"), observational ("in our review we observed…"), honest about uncertainty. +4. Pull the **Effort** value for the priority table from the Fix Priority Matrix in [../recommendations.md](../recommendations.md) ("Time to Fix"). + +## Document Template + +```markdown +# {App Name} — Performance Review & Recommendations + +{Intro: thank them; note what was reviewed (data, calculations, the screens mentioned); +set expectations that performance is usually several factors and these are changes to try.} + +## {Symptom-led: one section per reported symptom} / {Theme-led: Speed / Complexity / Reliability} + +{Per section: what they're seeing or the theme → likely cause(s) in plain language → +"Changes to try" as numbered steps ordered by expected impact.} + +## Broader recommendations + +{Architecture items — access control, data source, complexity — kept separate from the quick fixes above.} + +## Suggested order of work + +| # | Change | Effort | What it targets | +|---|--------|--------|-----------------| +| 1 | … | Low | … | + +## A few things worth checking on your side + +- {open questions the customer can confirm} + +{Offer to help / pair on the quick fixes first.} +``` + +## Guardrails + +- **Omit** everything on the guideline's [What to Omit](../customer-report-guideline.md#what-to-omit) list: 0–100 scores, severity emoji/labels, internal-tool names (Dev Tools, Performance Analysis tool, API token, support session), internal process notes, raw internal IDs. +- **Tone:** never "this will fix it" / "root cause." Always "should help" / "likely" / "worth trying." +- **No over-promising:** detected issues correlate with symptoms but don't prove causation — keep it tentative and suggest testing one change at a time. +- **Read-only:** this is a pure text transform over existing audit data. It introduces **no** browser actions and **no** API calls — do not add any. The audit's read-only guarantee is preserved. + +## Output Delivery + +Return the customer report as a separate markdown string, presented after the technical report (and, if the operator wants, saved to a file for sending). Example wrapper: + +```javascript +return { + customerReport: generatedMarkdown, + mode: reportedSymptoms ? "symptom-led" : "theme-led" +}; +``` + +## References + +- [../customer-report-guideline.md](../customer-report-guideline.md) — tone, omit-list, translation table, structures, worked example. +- [../recommendations.md](../recommendations.md) — source of fix steps and the Effort/priority matrix. +- [../analysis-patterns.md](../analysis-patterns.md) — source of the plain-language "why." +- [generate-report.md](generate-report.md) — the technical report this one accompanies.