Back to Details

pbs-spike-planning

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Spike Planning

Spike规划

Overview

概述

Generate a structured spike spec for a technical question that needs a real experiment to answer. The spec defines the question, success criteria, time box, and approach — ready to be executed by pbs-spike-execution in a dedicated session.
Core principle: A well-defined spike question is half the answer. Vague spikes waste time. This skill forces precision before execution.
Announce at start: "I'm using the pbs-spike-planning skill to define a spike for: [question summary]."
为需要通过实际实验解答的技术问题生成结构化的spike规范。该规范明确定义了问题、成功标准、时间箱和实施方法，可直接在专属会话中由pbs-spike-execution执行。
核心原则： 定义清晰的spike问题等于成功了一半。模糊的spike只会浪费时间。该技能要求在执行前先明确问题精度。
启动时声明： "我正在使用pbs-spike-planning技能为以下问题定义spike：[问题摘要]。"

When to Use

适用场景

  • Discovery identified uncertain technical questions that need real experiments (Block 7)
  • Mid-construction: you hit an unknown that can't be answered by docs or web search alone
  • Evaluating a technology, API, or pattern before committing to it
  • Any moment where "I think this works" needs to become "I verified this works"
  • 调研阶段识别出需要通过实际实验验证的不确定技术问题（第7模块）
  • 开发过程中：遇到无法仅通过文档或网络搜索解答的未知问题
  • 在正式采用某项技术、API或设计模式前对其进行评估
  • 任何需要将"我认为可行"转变为"我已验证可行"的场景

When NOT to Use

不适用场景

  • The answer is available in official docs or web search → just verify and document
  • The question is conceptual, not technical → that's brainstorming, not a spike
  • The experiment would take < 30 minutes → just do it inline, no spec needed
  • 可在官方文档或网络搜索中找到答案的问题 → 直接验证并记录即可
  • 概念性而非技术性问题 → 属于头脑风暴范畴，不是spike
  • 实验耗时不足30分钟 → 直接执行即可，无需编写规范

Input

输入

  • Required: A technical question or uncertainty to resolve
  • Optional: Context from discovery synthesis, phase spec, or current task
  • 必填： 需要解决的技术问题或不确定性点
  • 可选： 来自调研汇总、阶段规范或当前任务的上下文信息

The Process

流程

Step 1: Clarify the Question

步骤1：明确问题

Turn the vague uncertainty into a precise, answerable question:
BAD:  "Does this library work?"
GOOD: "Can Library X parse format Y with nested structures of depth > 5
       without losing data, in under 200ms for a 10MB file?"

BAD:  "Is the API fast enough?"
GOOD: "Does the Canton JSON API respond to party allocation requests
       in under 500ms when 10 concurrent requests are made?"
Ask the human to confirm the question is what they actually need answered.
将模糊的不确定性转化为精准、可解答的问题：
BAD:  "Does this library work?"
GOOD: "Can Library X parse format Y with nested structures of depth > 5
       without losing data, in under 200ms for a 10MB file?"

BAD:  "Is the API fast enough?"
GOOD: "Does the Canton JSON API respond to party allocation requests
       in under 500ms when 10 concurrent requests are made?"
请用户确认该问题是否是他们实际需要解答的问题。

Step 2: Define Success/Failure Criteria

步骤2：定义成功/失败标准

Make them measurable:
  • VIABLE if: [specific, measurable condition]
  • NOT VIABLE if: [specific, measurable condition]
  • INCONCLUSIVE if: [what "we still don't know" looks like]
确保标准可量化：
  • 可行条件：[具体、可量化的条件]
  • 不可行条件：[具体、可量化的条件]
  • 无结论条件：[哪些情况属于"我们仍无法确定"]

Step 3: Set Constraints

步骤3：设置约束

  • Time box: 1-4 hours (default: 2 hours). Complexity-based:
    • API call / library test → 1-2 hours
    • Integration with external service → 2-3 hours
    • Architecture pattern validation → 3-4 hours
  • Constraints: specific versions, no paid services, must work offline, etc.
  • Context references: link to the relevant sections of brainstorming/discovery/phase spec so the spike session has full context without needing the current conversation
  • 时间箱： 1-4小时（默认2小时），根据复杂度调整：
    • API调用/库测试 → 1-2小时
    • 与外部服务集成 → 2-3小时
    • 架构模式验证 → 3-4小时
  • 约束条件： 特定版本、不使用付费服务、必须支持离线运行等
  • 上下文引用： 链接到头脑风暴/调研/阶段规范的相关章节，这样spike执行会话无需依赖当前对话就能获取完整上下文

Step 4: Suggest Approach

步骤4：建议实施方法

Outline 2-4 concrete steps the spike executor should follow. Be specific enough that a fresh session can start without ambiguity.
列出2-4个spike执行者应遵循的具体步骤。描述要足够清晰，新会话启动后不会产生歧义。

Step 5: Generate Spike Spec

步骤5：生成Spike规范

Write the spec to 
.pbs-framework/exploration/spikes/spike-XX-[name].md
using the 
spike-spec.md.template
.
Naming convention:
  • spike-01-canton-api-latency.md
  • spike-02-websocket-reconnection.md
  • Number sequentially within the project
If called from discovery: Generate all identified spike specs, then return control to discovery.
If called mid-construction: Generate the spike spec in 
.pbs-framework/phases/phase-XX/spikes/
instead.
<HARD-GATE> The human MUST review and approve the spike spec before execution. If the question is unclear or success criteria are vague, iterate until precise. Do NOT proceed to execution — that happens in a separate session with pbs-spike-execution. </HARD-GATE>
使用
spike-spec.md.template
模板将规范写入
.pbs-framework/exploration/spikes/spike-XX-[name].md
文件。
命名规范：
  • spike-01-canton-api-latency.md
  • spike-02-websocket-reconnection.md
  • 项目内按顺序编号
如果是在调研阶段调用： 生成所有识别出的spike规范，然后将控制权交还给调研流程。
如果是在开发过程中调用： 改为将spike规范生成到
.pbs-framework/phases/phase-XX/spikes/
目录下。
<HARD-GATE> 执行前必须由用户审核并批准spike规范。 如果问题不明确或成功标准模糊，需反复迭代直至足够精准。 不要直接进入执行阶段——执行需在单独会话中通过pbs-spike-execution完成。 </HARD-GATE>

Common Mistakes

常见错误

  • Question too broad — "Does the API work?" is not a spike question. What specific behavior are you testing?
  • No measurable success criteria — "It should be fast" is not a criterion. "Response < 500ms at P95" is.
  • Time box too generous — 4 hours is the max. If you think it needs more, split into multiple spikes.
  • Missing context references — the spike session won't have your current conversation. Link to the docs it needs.
  • 问题过于宽泛 —— "API能用吗？"不是合格的spike问题。你要测试的具体行为是什么？
  • 没有可量化的成功标准 —— "它应该很快"不是合格的标准。"P95响应时间<500ms"才是。
  • 时间箱设置过长 —— 最长不得超过4小时。如果认为需要更长时间，拆分为多个spike。
  • 缺失上下文引用 —— spike执行会话无法获取当前对话内容，请链接到所需的相关文档。

Red Flags

风险提示

  • "This spike needs a full environment setup" → The spike scope is too big. Split it.
  • "I'll figure out what to test when I start" → That's not a spike, that's exploration. Define the question first.
  • "The whole feature needs spiking" → Break it into specific, independent questions.
  • "Let me just run the spike now" → Generate the spec. Execution happens in a separate session.
  • "这个spike需要搭建完整的环境" → spike范围过大，请拆分。
  • "等我开始做的时候再想测试什么" → 这不是spike，是无目的探索。请先定义问题。
  • "整个功能都需要做spike" → 拆分为具体、独立的问题。
  • "我现在直接跑spike就行" → 先生成规范。执行需在单独会话中完成。

Common Rationalizations

常见借口

ExcuseReality
"The question is obvious, no need for a formal spec"If it's obvious, writing the spec takes 5 minutes. Do it anyway.
"I'll remember the context"The spike session won't have this conversation. Write the context references.
"One big spike is easier than three small ones"One big spike exceeds the time box and answers nothing well. Split.
"Success criteria are hard to define"If you can't define success, you don't understand the question yet.
借口实际情况
"问题很明显，不需要正式规范"如果真的很明显，写规范只需要5分钟。还是写吧。
"我记得上下文内容"spike执行会话无法获取本次对话内容。请写下上下文引用。
"一个大spike比三个小spike省事"一个大spike会超出时间箱，而且没法很好地解答任何问题。拆分吧。
"成功标准很难定义"如果你定义不了成功标准，说明你还没理解问题本身。

Integration

集成说明

Called by:
  • pbs-exploration-discovery — Block 7, for all spikes identified during technical investigation
  • pbs-task-execution — when an unknown is hit mid-implementation
  • Standalone — anytime a technical question needs a real experiment
Generates specs for:
  • pbs-spike-execution — executed in separate sessions
Language: Write spike specs in the language defined in AGENTS.md 
framework_language
field. If not set, match the language of existing 
.pbs-framework/
documents.
调用方：
  • pbs-exploration-discovery —— 第7模块，处理技术调研过程中识别出的所有spike
  • pbs-task-execution —— 实现过程中遇到未知问题时调用
  • 独立调用 —— 任何需要通过实际实验解答技术问题的场景
生成的规范供给：
  • pbs-spike-execution —— 在单独会话中执行
语言要求： 按照AGENTS.md中
framework_language
字段定义的语言编写spike规范。如果未设置，与现有
.pbs-framework/
文档的语言保持一致。