platform-request

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Platform request

平台请求

You work for the person who owns this app (a domain expert, not a developer). Some things they ask for are not yours to build: the platform (the Boring library, the hub, the VM, models and connectors) must change first. Your job then is not to hack around it but to hand the platform team an issue so complete that they can build it without talking to the person again.

The product of this skill is one GitHub issue, labelled

kind:platform

(the issue form

.github/ISSUE_TEMPLATE/platform.yml

), in this repository. It is read by the platform maintainer and by their coding agent. Everything they need must be in it.

你服务于该 app 的负责人（一位领域专家，而非开发者）。他们提出的一些需求并不由你来构建：平台（Boring library、hub、VM、models 和 connectors）必须先做出变更。此时，你的工作不是绕开平台自行 hack，而是向平台团队提交一份足够完整的 issue，让他们无需再次与负责人沟通就能完成构建。

本 skill 的产物是此仓库中的一个 GitHub issue，带有

kind:platform

标签（issue 表单

.github/ISSUE_TEMPLATE/platform.yml

），并由平台维护者及其 coding agent 阅读。他们所需的一切信息都必须包含在 issue 中。

When

适用时机

```
docs/CAPABILITIES.md
```
puts the need under "Not possible today".
The change needs
```
vendor/
```
,
```
deploy/
```
,
```
.github/
```
,
```
server/src/auth.ts
```
, a new model provider, a connector to another system, a scheduler, email.
Something fails and you cannot find why after two honest attempts (a hypothesis tested each time), or the platform behaves unlike its docs.
The change would take more than a day, or touches security or personal data.

Not for a product change you can build here: build it (skill new-agent, verify-app). If unsure, check

docs/CAPABILITIES.md

and

gh issue list --label kind:platform --state all

(it may already be asked, or solved).

```
docs/CAPABILITIES.md
```
将该需求列在 “Not possible today” 项下。
变更需要涉及
```
vendor/
```
、
```
deploy/
```
、
```
.github/
```
、
```
server/src/auth.ts
```
、新的 model provider、连接到其他系统的 connector、scheduler 或 email。
某项操作失败，认真尝试两次后仍无法找到原因（每次都检验了一个假设），或者平台的行为与文档不一致。
变更预计需要超过一天，或者涉及安全或个人数据。

如果是在这里可以自行构建的产品变更，则直接构建（使用 skill new-agent、verify-app）。如果不确定，请检查

docs/CAPABILITIES.md

和

gh issue list --label kind:platform --state all

（该需求可能已经被提出或解决）。

1. Interview the person (the most important step)

1. 访谈负责人（最重要的一步）

The maintainer was not in your conversation. Recover the context now, while the person is here. Talk in their language, plainly, one question at a time; never announce how many questions remain. Stop when no answer would change the issue.

The need in their words: what they want to do, and why now.
Three real situations (not hypotheticals): for each, what triggered it, what they had at hand, what they did, what they decided, what went wrong or took time, the result. If one is imagined, say so and ask for a real one. Remove anything that identifies a real person (patient, client, colleague): change names, dates of birth, identifiers; keep the shape of the case.
Today's way and its cost: how they manage without it (time, errors, another tool), and how often.
The decisive moment: when they are late or under pressure, at what point do they give up on the current way, and what do they do instead? Ask this once; it tells what must be automatic and what may stay manual.
Done looks like: what they would see and do when it works. Turn it into "The app shall …" lines they agree with.
Limits: what must never happen (data leaving, a document changed without them, a cost), and how urgent it is (blocking, weekly pain, nice to have).

平台维护者没有参与你与负责人的对话。现在负责人还在，要立即补齐上下文。用负责人熟悉的语言直白地交流，每次只问一个问题；绝不要说明还剩多少问题。当任何答案都不会再改变 issue 内容时停止。

用负责人自己的话描述需求：他们想做什么，以及为什么现在要做。
三个真实场景（不是假设）：对于每个场景，分别说明是什么触发了需求、当时手头有什么、做了什么、作出了什么决定、哪里出了问题或耗费了时间，以及最终结果。如果某个场景是想象出来的，就明确说明，并询问一个真实场景。删除任何能够识别真实个人的信息（患者、客户、同事）：更改姓名、出生日期、标识符；保留案例原有的结构。
当前做法及其成本：在没有该能力的情况下，他们如何处理（耗费的时间、产生的错误、使用的其他工具），以及这种情况发生得有多频繁。
临界时刻：当他们迟到或承受压力时，会在什么情况下放弃当前做法，转而采取什么措施？只问一次；这能说明哪些环节必须自动化，哪些环节可以继续手动处理。
完成标准：功能正常时，他们会看到什么、做什么。将其转化为负责人认可的“应用应当……”句式。
边界与限制：绝不能发生什么（数据流出、文档未经他们确认就被更改、产生费用），以及紧急程度如何（阻塞、每周都会造成困扰、锦上添花）。

2. Gather the evidence

2. 收集证据

What you tried: commands, the error text, the
```
verify
```
evidence (
```
network-summary --since-mark
```
,
```
console --errors
```
, screenshot) and the run rows (
```
verify api /api/runs
```
). Invented data only.
Versions:
```
git rev-parse --short HEAD
```
, the library commit in
```
vendor/boring/SOURCE.json
```
, and what is deployed (
```
list_app_tools
```
on the the hub, see docs/CAPABILITIES.md; or the version in
```
/healthz
```
).
Which row of
```
docs/CAPABILITIES.md
```
blocks it, or which doc the platform contradicts.
The nearest thing possible today (the "Nearest" column), and whether you built it.

你尝试过的内容：执行过的命令、错误文本、
```
verify
```
证据（
```
network-summary --since-mark
```
、
```
console --errors
```
、screenshot）以及运行记录（
```
verify api /api/runs
```
）。只能使用虚构数据。
版本信息：
```
git rev-parse --short HEAD
```
、library 在
```
vendor/boring/SOURCE.json
```
中的 commit，以及已部署的版本（在 hub 上运行
```
list_app_tools
```
，参见 docs/CAPABILITIES.md；或查看
```
/healthz
```
中的版本）。
```
docs/CAPABILITIES.md
```
中哪一行构成了阻塞，或者平台的行为与哪份文档相矛盾。
当前最接近的可行方案（“Nearest”列），以及是否已经自行构建该方案。

3. Make a mockup when the need is something to see

3. 当需求需要可视化时制作 mockup

A picture settles what three paragraphs cannot. Pick the lightest that works:

Text wireframe (always, in the issue): boxes and labels in a code block.

HTML mock: one self-contained file with invented data, then a PNG of it:

bash

node scripts/mock-shot.mjs docs/requests/<slug>/mock.html docs/requests/<slug>/mock.png

Commit both on a branch

request/<slug>

(never

main

), push it, and link the files from the issue (

https://github.com/<owner>/<repo>/blob/request/<slug>/docs/requests/<slug>/mock.png

A screenshot of today's page (
```
verify screenshot
```
) next to the mock, when the change is to an existing screen.

一张图能解决三段文字说不清的问题。选择足够且最轻量的形式：

文本线框图（始终需要，放在 issue 中）：在代码块中画出方框和标签。
HTML mock：一个使用虚构数据的自包含文件，然后生成对应的 PNG：
bash
```
node scripts/mock-shot.mjs docs/requests/<slug>/mock.html docs/requests/<slug>/mock.png
```
将两个文件 commit 到分支
```
request/<slug>
```
（绝不要使用
```
main
```
），push，并在 issue 中链接这些文件（
```
https://github.com/<owner>/<repo>/blob/request/<slug>/docs/requests/<slug>/mock.png
```
）。
当变更是针对现有页面时，将当前页面的 screenshot（
```
verify screenshot
```
）与 mockup 放在一起展示。

4. Draft, show, file

4. 起草、展示并提交

Write the issue body from
```
issue-template.md
```
(next to this file) into
```
.verify/request-<slug>.md
```
. Fill every section; write "unknown" rather than leave one out, and say who could find out.
Show the person the title, the summary and the acceptance lines, in their language, and ask whether it says what they need. Correct until they say yes. Filing an issue is visible to others: never file before that yes.

File it:

bash

gh issue create --label kind:platform --title "<the need, in a few words>" --body-file .verify/request-<slug>.md

Tell the person the link, what happens next (the platform team triages it), and what they can do meanwhile (the nearest workaround).
Leave nothing half-built: revert a workaround you did not finish, or finish it and say so in the issue.

根据本文件旁的
```
issue-template.md
```
编写 issue 正文，并写入
```
.verify/request-<slug>.md
```
。填写每个章节；不要遗漏任何章节，不知道的内容填写“unknown”，并说明谁可以查明。
用负责人的语言向其展示标题、摘要和验收标准语句，并询问这是否准确表达了他们的需求。持续修改，直到负责人明确同意。提交 issue 后其他人也能看到，因此在获得同意前绝不能提交。

提交 issue：

bash

gh issue create --label kind:platform --title "<the need, in a few words>" --body-file .verify/request-<slug>.md

将 issue 链接告诉负责人，说明接下来会发生什么（平台团队会进行 triage），以及在此期间负责人可以采取什么措施（最接近的 workaround）。
不要留下任何半成品：撤回尚未完成的 workaround，或者将其彻底完成并在 issue 中说明。

Never

禁止事项

Real personal data in the issue, the mockup or the evidence. The issue is read by people and agents outside the app.
A change in
```
vendor/
```
,
```
deploy/
```
,
```
.github/
```
or auth to "unblock" yourself.
An issue without the interview: "the person wants X" with no situation, no acceptance and no evidence will come back to them as questions.

绝不要在 issue、mockup 或证据中放入真实个人数据。issue 会由 app 外部的人员和 Agent 阅读。
不要为了给自己解阻而修改
```
vendor/
```
、
```
deploy/
```
、
```
.github/
```
或 auth。
不要在没有访谈的情况下提交 issue：如果只有“负责人想要 X”，却没有具体场景、验收标准和证据，平台团队只会把问题退回来询问。