Back to Details

planetscale-customer-report-template

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

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.
报告旨在进行精准评估，帮助客户充分利用其运行的平台功能。功能采用需基于证据，而非表述话术。报告内容需技术化、陈述式——是工程师的评估，而非营销文案。
  • 将未使用的功能表述为带有量化影响的能力缺口。 绝不能写“已关闭（良好）”“未启用（安全）”或类似将未使用功能描述为正面结论的内容。正确格式为：当前状态、该功能提供的价值、对应的量化评估结果。示例：“原始查询收集：已禁用。启用后可暴露每次执行的字面参数值；适用于Q1（占总查询时间的38%），此场景下仅靠模式级数据不足以定位触发调用。”
  • 禁用情绪化表述。 不得使用“物尽其用”“成效显著”“易于采用”“将根因排查时间从小时缩短至分钟”之类的短语，也不得使用任何感叹语气。只需陈述机制与测量数据，让数字本身说明问题。
  • 运营成本需作为事实直接陈述，不得弱化： “字面值将对可观测性流水线可见”是该功能的固有属性，只需陈述一次，无需额外安抚。
  • 每项建议需引用对应的具体评估结果——如指纹、指标、事件数量、时间窗口。未附带测量数据的建议是不完整的。
  • 已启用功能需进行评估，而非夸赞。 若某功能已启用，需以可量化的方式报告其当前运行情况（如“异常检测在7天内9次标记连接峰值；未配置交付渠道”），并说明其配置是否完整。
  • 适配性是分析的一部分：若证据表明某功能不适用于该客户，需明确说明。
  • 建议需围绕变更能带来的价值展开，而非强调当前状态的风险。 应写“专用应用角色可为每个服务限定凭据范围，并支持无停机轮换”，而非“限制凭据泄露的影响范围”。避免使用夸张词汇：“影响范围”“未受保护”“暴露”“默认公开”“面临风险”。真实风险仍需作为事实陈述——如“生产分支运行零副本；主节点故障后需通过恢复操作恢复”是评估结果，应纳入报告。需排除的是夸张表述，而非信息披露。
  • 平台行为需基于已验证的语义报告，而非假设。 当两个API接口显示不同值时，通常是不同的设置——需查阅文档并报告实际生效状态。不得在未验证假设的情况下将平台行为标记为不一致、矛盾或存在bug。若语义无法验证，需分别报告各接口的结果，不做结论，并引导用户咨询PlanetScale支持团队。若已验证平台行为确实存在问题，需如实报告并转至PlanetScale支持团队——这是平台问题，而非客户配置评估结果。

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.
评估工具的故障（如HTTP状态码、MCP错误、CLI故障、令牌权限问题、超时、端点探测）仅描述运行情况，与数据库本身无关。这些内容应纳入运行日志，而非评估结果。
  • 若无法收集到证据，报告中需注明“本次运行未评估”，无需附带错误机制细节。
  • 证据附录包含已收集的证据。
  • 运行日志（工具错误、尝试路径、访问缺口）需随报告一同提供，供执行评估的人员查看——不得隐瞒任何信息。分离的原因在于工具错误无法反映客户数据库的状况。
  • 绝不能因调用失败就判定某功能未配置。“未配置”需基于成功调用返回空结果的情况。

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.
报告需为纯Markdown格式：包含标题章节、正文和管道表格。这是基础要求，必须完整生成——可在任何Agent、终端或聊天界面中使用。若宿主Agent提供更丰富的渲染界面（如Cursor画布、HTML预览、仪表板），可在Markdown报告之外额外使用这些界面，但绝不能替代Markdown报告。

Required report format

报告必填格式

PlanetScale best-practices assessment

PlanetScale最佳实践评估

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.
撰写3-7条要点。第一条需如实陈述平台当前为该数据库提供的服务及对应测量数据——例如：副本拓扑与故障转移状态、备份频率与上次成功备份时间、Insights收集量、已启用的安全功能。这并非夸赞，而是报告其余部分所基于的运行基线。后续要点需包含：
  • 最高风险的安全缺口。
  • 最高价值的可观测性改进建议。
  • 最高价值的自动化机会。
  • 引擎特定的工作流缺口。
  • 仓库 instrumentation 缺口。

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.
针对Vitess：
  • 安全迁移。
  • 部署请求。
  • 审批要求。
  • gated deployment 使用情况。
  • Schema回滚手册。
针对Postgres：
  • 分支迁移工作流。
  • 角色。
  • pg_strict。
  • 流量控制。
  • 备份/PITR。
  • 连接池。
  • 私有连接与IP限制。

Observability

可观测性

  • Query Insights state.
  • Anomalies.
  • Query tags.
  • Raw query collection posture.
  • Schema recommendations.
  • Query Insights状态。
  • 异常情况。
  • 查询标签。
  • 原始查询收集状态。
  • Schema建议。

Automation

自动化

  • Webhooks.
  • Agent loops.
  • CI/PR workflows.
  • Incident routing.
  • Webhooks。
  • Agent循环。
  • CI/PR工作流。
  • 事件路由。

Repository instrumentation

仓库 instrumentation

  • Frameworks and ORMs detected.
  • Current SQL comments or tracing.
  • Recommended SQLCommenter package/path.
  • Tag schema.
  • 检测到的框架与ORM。
  • 当前SQL注释或追踪情况。
  • 推荐的SQLCommenter包/路径。
  • 标签 schema。

Recommendations

建议

Use this table structure:
IDRecommendationTargetBenefitRiskApproval neededTest first?Evidence
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.
使用如下表格结构：
ID建议目标收益风险是否需要审批是否需先测试证据
建议ID规则：
  • OBS-*
    用于Insights/查询标签相关建议。
  • VIT-*
    用于Vitess安全/部署工作流相关建议。
  • PG-*
    用于Postgres角色、pg_strict、流量控制、PITR、网络相关建议。
  • WEB-*
    用于Webhooks与自动化相关建议。
  • APP-*
    用于仓库 instrumentation 相关建议。
  • AGENT-*
    用于MCP/Agent工作流相关建议。

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.
针对每项拟议变更，需包含：
  • ID。
  • 具体目标。
  • 具体变更内容。
  • 需使用的接口。
  • 推荐理由。
  • 预期效果。
  • 可能的可用性影响。
  • 测试计划。
  • 回滚计划。
  • 是否会变更生产环境。

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.
需明确说明：
  • 未修改任何PlanetScale设置。
  • 未修改任何Schema。
  • 未修改任何流量控制设置。
  • 未修改任何角色或凭据。
  • 未修改任何Webhooks。
  • 未修改任何代码。
  • 未创建任何分支、备份、恢复、部署请求或迁移任务。

Evidence appendix

证据附录

For each evidence item:
  • Source.
  • Command/API/MCP/repository path.
  • Timestamp.
  • Value.
  • Notes.
针对每项证据，需包含：
  • 来源。
  • 命令/API/MCP/仓库路径。
  • 时间戳。
  • 值。
  • 备注。

Final required sentence

必填收尾语句

End the report with:
“No changes have been applied. Approve specific change IDs before any mutation.”
报告结尾需包含：
“未应用任何变更。在执行任何修改前，请批准具体的变更ID。”