planetscale-customer-report-template

Customer report template

Purpose

Produce a clear assessment report for a customer database and optional connected repository. The report should be actionable, evidence-backed, and safe. It should separate recommendations from applied changes.

Tone and framing

The report's purpose is an accurate assessment that helps the customer get full value from the platform they run. Feature adoption follows from evidence, never from framing. The register is technical and declarative — an engineer's assessment, not marketing copy.

• State unused features as capability gaps with quantified impact. Never write "off (good)", "not enabled (safe)", or otherwise present non-adoption as a positive finding. The correct form is: current state, what the feature provides, the measured finding it applies to. Example: "Raw query collection: disabled. Enabling it exposes literal parameter values per execution; applicable to Q1 (38% of total query time), where the pattern-level data is insufficient to isolate the triggering invocation."
• No enthusiasm markers. Do not use phrases like "earning its keep", "paying off", "easy to adopt", "cutting root-cause time from hours to minutes", or exclamation of any kind. State the mechanism and the measurement; let the numbers carry the argument.
• Operational costs are stated inline as facts, not softened: "literal values become visible to the observability pipeline" is a property of the feature, stated once, without reassurance.
• Every recommendation cites the specific finding it addresses — fingerprint, metric, event count, time window. A recommendation without a measurement attached is incomplete.
• Active features are assessed, not praised. If a feature is enabled, report what it is currently doing in measurable terms ("anomaly detection flagged the connection spike 9 times in 7 days; no delivery channel is configured") and whether its configuration is complete.
• Fit is part of the analysis: if the evidence does not support a feature for this customer, state that.
• Recommendations are framed by what the change provides, not by the threat of the current state. Write "a dedicated application role scopes credentials per service and enables rotation without downtime", not "limits the blast radius of credential compromise". Avoid dramatizing vocabulary: "blast radius", "unprotected", "exposed", "public-by-default", "at risk". Real risks are still stated, as facts — "the production branch runs zero replicas; recovery from a primary failure requires a restore" is a finding and belongs in the report. What is excluded is dramatization, not disclosure.
• Platform behavior is reported with verified semantics, not assumptions. When two API surfaces show different values, they are usually distinct settings — check the documentation and report the effective state. Do not label platform behavior inconsistent, contradictory, or buggy on an unverified assumption. If the semantics cannot be verified, state what each surface reports without drawing a conclusion and direct the question to PlanetScale support. If verified platform behavior is actually wrong, report it factually and route it to PlanetScale support — it is a platform issue, not a customer configuration finding.

Run mechanics are separated from findings

Failures of the assessment tooling — HTTP status codes, MCP errors, CLI failures, token scope problems, timeouts, endpoint probes — describe the run, not the database. They belong in the run log, not in the findings.

• Where evidence could not be collected, the report says "not assessed in this run" with no error mechanics attached.
• The evidence appendix contains collected evidence.
• The run log (tool errors, paths tried, access gaps) accompanies the report and is available to whoever ran the assessment — nothing is withheld. The separation exists because tool errors say nothing about the customer's database.
• Never conclude a feature is unconfigured from a failed call. "Not configured" requires a successful call that returned an empty result.

Output surface

The report is plain markdown: headed sections, prose, and pipe tables. This is the baseline and it must always be produced in full — it works in any agent, terminal, or chat surface. If the host agent offers a richer rendering surface (Cursor canvas, HTML preview, a dashboard), it may be used in addition to the markdown report, never instead of it.

Required report format

PlanetScale best-practices assessment

Scope

• Organization:
• Database:
• Branches reviewed:
• Engine:
• Repository reviewed:
• Interfaces used:
• Time window:
• Changes applied: none

Executive summary

Write 3-7 bullets. The first bullet states what the platform is currently doing for this database, factually and with measurements — for example: replica topology and failover posture, backup cadence and last successful backup, Insights collection volume, safety features active. This is not praise; it is the operating baseline the rest of the report builds on. Then:

• Highest-risk safety gaps.
• Highest-value observability improvements.
• Highest-value automation opportunities.
• Engine-specific workflow gaps.
• Repository instrumentation gaps.

Current state

Database and branch topology

Include evidence.

Safety workflow

For Vitess:

• Safe migrations.
• Deploy requests.
• Approval requirements.
• Gated deployment usage.
• Schema revert runbook.

For Postgres:

• Branch migration workflow.
• Roles.
• pg_strict.
• Traffic Control.
• Backups/PITR.
• Connection pooling.
• Private connectivity and IP restrictions.

Observability

• Query Insights state.
• Anomalies.
• Query tags.
• Raw query collection posture.
• Schema recommendations.

Automation

• Webhooks.
• Agent loops.
• CI/PR workflows.
• Incident routing.

Repository instrumentation

• Frameworks and ORMs detected.
• Current SQL comments or tracing.
• Recommended SQLCommenter package/path.
• Tag schema.

Recommendations

Use this table structure:

Recommendation IDs:

• OBS-* for Insights/query tags.
• VIT-* for Vitess safety/deploy workflow.
• PG-* for Postgres roles, pg_strict, Traffic Control, PITR, network.
• WEB-* for webhooks and automation.
• APP-* for repository instrumentation.
• AGENT-* for MCP/agent workflows.

Proposed change set requiring approval

For every proposed change, include:

• ID.
• Exact target.
• Exact change.
• Interface to use.
• Why it is recommended.
• Expected effect.
• Possible availability impact.
• Test plan.
• Rollback plan.
• Whether it changes production.

Changes intentionally not applied

State clearly:

• No PlanetScale settings changed.
• No schema changed.
• No traffic controls changed.
• No roles or credentials changed.
• No webhooks changed.
• No code changed.
• No branches, backups, restores, deploy requests, or migrations created.

Evidence appendix

For each evidence item:

• Source.
• Command/API/MCP/repository path.
• Timestamp.
• Value.
• Notes.

Final required sentence

End the report with:

“No changes have been applied. Approve specific change IDs before any mutation.”