pythia-spec

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Settling the Spec

确定需求规格

Announce at start: "Using pythia-spec — this request has open decisions that are yours, not mine."

Phase: Learn → Ask — learn enough to ask well, ask until the spec is settled, and only then build

The other skills are the construction chain: they start after the spec is settled. This skill owns the moment before — because an agent that quietly settles the spec itself will build the wrong thing fluently, and the developer's first chance to disagree arrives after the code exists, when every choice costs a rewrite.

开始时告知： "正在使用pythia-spec——此需求中存在未明确的决策，这些决策应由您（开发者）决定，而非我。"

阶段： 了解→提问 —— 充分了解以提出恰当的问题，持续提问直到需求规格确定，之后再开始构建

其他技能属于构建环节：它们在需求规格确定后启动。此技能负责之前的阶段——因为如果Agent自行悄悄确定需求规格，可能会“流畅地”构建出错误的内容，而开发者第一次提出异议的机会是在代码完成后，此时任何修改都需要重写，成本极高。

The Iron Law

铁则

SPEC DECISIONS BELONG TO THE DEVELOPER. YOU PROPOSE; THEY CHOOSE.

SPEC DECISIONS BELONG TO THE DEVELOPER. YOU PROPOSE; THEY CHOOSE.

Spec or technical? The line that decides who decides

需求规格还是技术实现？界定决策归属的界限

Spec — ask first	Technical — decide yourself, cite your source
What is stored: new table vs new columns, what is kept vs deleted	Names and shapes — the conventions already decide them
Business behaviour: expiry times, retry limits, lockout counts, who is allowed	Which dictionary view or query answers a question
Security ↔ audit trade-offs: delete the token vs keep the trail	Following an existing pattern found via `similar`
Channels and scope: email or SMS, which tenants, which callers	Datatype dictated by the house rules for that kind of value
Deviating from a mandatory convention	Anything `pythia conventions` or the codebase answers

Rule of thumb: if two senior developers could reasonably ship different behaviour, it is spec. If the codebase or the conventions already answer it, it is technical — decide, and show the căn cứ.

需求规格——需先询问	技术实现——自行决定并说明依据
存储内容：新建表还是新增列，保留什么与删除什么	命名与格式——已有规范已做出规定
业务行为：过期时间、重试限制、锁定次数、权限范围	使用哪个字典视图或查询来解答问题
安全与审计的权衡：删除令牌还是保留操作痕迹	遵循通过 `similar` 找到的现有模式
渠道与范围：邮件还是短信，哪些租户，哪些调用方	数据类型由该类值的团队规则决定
偏离强制规范的情况	任何 `pythia conventions` 或代码库已给出答案的内容

经验法则：如果两位资深开发者可能合理地实现不同的行为，那么这属于需求规格范畴。 如果代码库或已有规范已给出答案，那么这属于技术实现范畴——自行决定并说明依据（căn cứ）。

The Workflow

工作流程

Learn enough to ask well — not enough to start building.
```
cols
```
and
```
src
```
on the tables involved,
```
conventions
```
,
```
similar
```
for how this house solves it. The output of this step is better questions, not code.
List every decision you would otherwise settle silently. The test: walk your imagined implementation and note each point where you picked a behaviour the developer never stated.
Ask, one at a time, options with trade-offs and a recommendation — never an open "what do you want?". Each option says what it costs: "OTP over SMS: 6 digits is guessable, so it forces an attempt counter and a lockout column — different table than the draft."
Write the settled spec back in a few lines and get a nod. That paragraph is now the scope —
```
pythia-write
```
's "the developer's sentence". This summary is not skippable; it is what was agreed.
Offer the written artifacts — the developer chooses. "Spec settled. Want it as a spec file and a step-by-step plan first, or build now?" Skipping is a legitimate answer; record it in one line and move on. The questions were the mandatory part — the documents never are.
Hand off: impact → write → apply, as always.

充分了解以提出恰当的问题——但无需达到可开始构建的程度。 查看涉及表的
```
cols
```
和
```
src
```
、
```
conventions
```
、
```
similar
```
以了解团队的解决方案。此步骤的产出是更优质的问题，而非代码。
列出所有你原本会自行决定的事项。 测试方法：在脑海中推演实现过程，记录每个你选择了开发者未明确说明的行为的节点。
逐个提出带有选项、权衡分析和建议的问题——绝对不要问开放式的“您想要什么？”。每个选项都要说明成本：“通过SMS发送OTP：6位数字容易被猜测，因此需要添加尝试计数器和锁定列——这与草稿中的表不同。”
用几句话写下确定后的需求规格并获得确认。这段内容将作为范围——即
```
pythia-write
```
中的“开发者表述”。此总结不可省略，它代表了双方达成的共识。
提供书面成果供开发者选择。 “需求规格已确定。您希望先出具规格文件和分步计划，还是直接开始构建？” 选择跳过书面成果是合理的，只需记录一行说明即可继续推进。提问是必须的环节，而书面文件并非必须。
交接：如往常一样，依次进行影响评估→编写→应用。

Caught deciding mid-build?

构建过程中发现需要决策？

Stop at that line. A new open decision discovered while coding is a new question — asking it late is cheap; presenting it as a fait accompli in the final report ("I also decided...") is the exact failure this skill exists to prevent.

立即停止。编码过程中发现的新的未明确决策属于新问题——晚提问的成本很低；而在最终报告中将其作为既成事实提出（“我还决定了……”）正是此技能要避免的错误。

Red Flags — STOP if you catch yourself thinking

危险信号——如果你有以下想法，请立即停止

Thought	Reality
"The task is simple, asking would stall"	Simple requests hide the most spec: a forgot-password flow carries seven of them. Three questions cost a minute; unbuilding costs an afternoon.
"Lazy mode says don't stall on questions"	Lazy shortens the solution, never the understanding. Settling spec IS understanding.
"I'll flag my choices in the final report"	By then the developer can only agree or demand rework. That is not a choice, it is a bill.
"A brainstorming skill from another pack will handle it"	If one fired, follow it. If none did, this is the floor — the kit assumes nothing else is installed.
"The developer said 'just do it'"	That covers the decisions they could see. New ones you discover are still theirs.
"They skipped the spec file, so I can skip the questions"	Backwards. The questions are mandatory; only the documents are optional.

想法	实际情况
“任务很简单，提问会耽误时间”	简单的需求往往隐藏最多的需求规格问题：一个找回密码流程就包含7个此类问题。三个问题只需一分钟；而推翻已构建的内容则需要一下午。
“偷懒模式告诉我不要在问题上耽误时间”	偷懒是简化解决方案，而非简化理解过程。确定需求规格本身就是理解的过程。
“我会在最终报告中说明我的选择”	到那时开发者只能同意或要求重写。这不是选择，而是强加的成本。
“其他套件中的头脑风暴技能会处理这个问题”	如果有其他技能触发，请遵循该技能。如果没有，此技能就是底线——工具包默认未安装其他相关技能。
“开发者说‘直接做就行’”	这句话只涵盖了他们能预见到的决策。你发现的新决策仍属于他们的权限范围。
“他们跳过了规格文件，所以我可以跳过提问”	这是本末倒置。提问是必须的；只有书面文件是可选的。

When NOT to use this skill

何时不应使用此技能

The request is fully specified, or a bug with one defensible correct behaviour — go straight to
```
pythia-impact
```
.
The developer already answered — do not re-ask what is settled; re-ask only what changed.
Pure refactors that keep behaviour identical.

需求已完全明确，或存在唯一合理修复方案的Bug——直接使用
```
pythia-impact
```
。
开发者已做出回答——不要重复询问已确定的事项；仅当情况发生变化时才重新提问。
不改变行为的纯重构工作。