shaping

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Shaping Methodology

Shaping 方法论

A structured approach for collaboratively defining problems and exploring solution options.

这是一种用于协作定义问题、探索方案选项的结构化方法。

Multi-Level Consistency (Critical)

多级一致性（至关重要）

Shaping produces documents at different levels of abstraction. Truth must stay consistent across all levels.

Shaping 会生成不同抽象层级的文档。所有层级的核心信息必须保持一致。

The Document Hierarchy (high to low)

文档层级结构（从高到低）

Big Picture — highest level, designed for quick context acquisition
Shaping doc — ground truth for R's, shapes, parts, fit checks
Slices doc — ground truth for slice definitions, breadboards
Individual slice plans (V1-plan, etc.) — ground truth for implementation details

Big Picture —— 最高层级，用于快速获取项目上下文
Shaping 文档 —— 需求（R）、方案选项（Shapes）、组件、适配检查的基准文档
Slices 文档 —— 切片定义、原型图（Breadboard）的基准文档
独立切片计划（如V1-plan等）—— 实现细节的基准文档

The Principle

核心原则

Each level summarizes or provides a view into the level(s) below it. Lower levels contain more detail; higher levels are designed views that help acquire context quickly.

Changes ripple in both directions:

Change at high level → trickles down: If you flag a part as ⚠️ in the Big Picture, update the shaping doc's parts table too.
Change at low level → trickles up: If a slice plan reveals a new mechanism or changes the scope of a slice, the Slices doc and Big Picture must reflect that.

每个层级都是对下层文档的汇总或视图。下层文档包含更多细节，上层文档则用于快速获取上下文。

变更会双向传导：

高层级变更 → 向下传导： 如果在Big Picture中标记某个组件为⚠️，则同时需更新Shaping文档中的组件表。
低层级变更 → 向上传导： 如果切片计划揭示了新机制或改变了切片范围，则Slices文档和Big Picture必须同步更新。

The Practice

实践要求

Whenever making a change:

Identify which level you're touching
Ask: "Does this affect documents above or below?"
Update all affected levels in the same operation
Never let documents drift out of sync

The Big Picture isn't a static snapshot — it's a live summary that must stay connected to its source documents. The system only works if the levels are consistent with each other.

每当进行变更时：

明确当前修改的层级
思考：“此变更是否会影响上层或下层文档？”
在同一操作中更新所有受影响的层级
绝不能让文档内容出现不一致

Big Picture不是静态快照，而是实时汇总文档，必须始终与源文档保持同步。只有所有层级信息一致，这套体系才能有效运作。

Starting a Session

启动协作会话

When kicking off a new shaping session, offer the user both entry points:

Start from R (Requirements) — Describe the problem, pain points, or constraints. Build up requirements and let shapes emerge.
Start from S (Shapes) — Sketch a solution already in mind. Capture it as a shape and extract requirements as you go.

There is no required order. Shaping is iterative — R and S inform each other throughout.

当启动新的Shaping会话时，为用户提供两个入口：

从R（需求）开始 —— 描述问题、痛点或约束条件，逐步梳理需求，让方案选项自然浮现。
从S（方案选项）开始 —— 先勾勒脑海中的初步方案，将其记录为一个Shape，再逐步提炼需求。

没有固定的顺序要求。Shaping是迭代过程——R和S在整个过程中相互影响。

Working with an Existing Shaping Doc

基于现有Shaping文档开展工作

When the shaping doc already has a selected shape:

Display the fit check for the selected shape only — Show R × [selected shape] (e.g., R × F), not all shapes
Summarize what is unsolved — Call out any requirements that are Undecided, or where the selected shape has ❌

This gives the user immediate context on where the shaping stands and what needs attention.

当Shaping文档中已选定某个Shape时：

仅展示选定Shape的适配检查 —— 显示R × [选定Shape]（如R × F），而非所有Shape的适配情况
汇总未解决的问题 —— 指出任何状态为“未确定”的需求，或选定Shape未满足（❌）的需求

这样能让用户快速了解当前Shaping的进展，以及需要关注的重点。

Core Concepts

核心概念

R: Requirements

R：需求（Requirements）

A numbered set defining the problem space.

R0, R1, R2... are members of the requirements set
Requirements are negotiated collaboratively - not filled in automatically
Track status: Core goal, Undecided, Leaning yes/no, Must-have, Nice-to-have, Out
Requirements extracted from fit checks should be made standalone (not dependent on any specific shape)
R states what's needed, not what's satisfied — satisfaction is always shown in a fit check (R × S)

一组编号的问题空间定义。

R0、R1、R2... 是需求集合的成员
需求需通过协作协商确定，而非自动生成
跟踪状态：核心目标、未确定、倾向采纳/拒绝、必须满足、锦上添花、排除
从适配检查中提炼的需求需独立存在（不依赖特定Shape）
R定义的是需要达成的目标，而非已满足的内容 —— 满足情况始终通过适配检查（R × S）展示

S: Shapes (Solution Options)

S：方案选项（Shapes）

Letters represent mutually exclusive solution approaches.

A, B, C... are top-level shape options (you pick one)
C1, C2, C3... are components/parts of Shape C (they combine)
C3-A, C3-B, C3-C... are alternative approaches to component C3 (you pick one)

用字母代表互斥的解决方案思路。

A、B、C... 是顶层方案选项（需从中选择一个）
C1、C2、C3... 是Shape C的组件（需组合使用）
C3-A、C3-B、C3-C... 是组件C3的替代实现思路（每个组件需选择一个）

Shape Titles

Shape标题

Give shapes a short descriptive title that characterizes the approach. Display the title when showing the shape:

markdown

undefined

为每个Shape提供简短描述性标题，展示Shape时需附带标题：

markdown

undefined

E: Modify CUR in place to follow S-CUR

E: 原地修改CUR以遵循S-CUR

Part	Mechanism
E1	...


Good titles capture the essence of the approach in a few words:
- ✅ "E: Modify CUR in place to follow S-CUR"
- ✅ "C: Two data sources with hybrid pagination"
- ❌ "E: The solution" (too vague)
- ❌ "E: Add search to widget-grid by swapping..." (too long)

组件	实现机制
E1	...


好的标题能通过寥寥数语概括方案核心：
- ✅ "E: 原地修改CUR以遵循S-CUR"
- ✅ "C: 双数据源混合分页"
- ❌ "E: 解决方案"（过于模糊）
- ❌ "E: 通过替换...为widget-grid添加搜索功能"（过于冗长）

Notation Hierarchy

符号层级

Level	Notation	Meaning	Relationship
Requirements	R0, R1, R2...	Problem constraints	Members of set R
Shapes	A, B, C...	Solution options	Pick one from S
Components	C1, C2, C3...	Parts of a shape	Combine within shape
Alternatives	C3-A, C3-B...	Approaches to a component	Pick one per component

层级	符号	含义	关系
需求	R0、R1、R2...	问题约束	需求集合R的成员
方案选项	A、B、C...	解决方案思路	从S中选择一个
组件	C1、C2、C3...	Shape的组成部分	在Shape内组合使用
替代方案	C3-A、C3-B...	组件的实现思路	每个组件选择一个

Notation Persistence

符号持久性

Keep notation throughout as an audit trail. When finalizing, compose new options by referencing prior components (e.g., "Shape E = C1 + C2 + C3-A").

全程保留符号作为审计轨迹。最终确定方案时，可通过引用已有组件组合新选项（如“Shape E = C1 + C2 + C3-A”）。

Phases

阶段

Shaping moves through two phases:

Shaping → Slicing

Phase	Purpose	Output
Shaping	Explore the problem and solution space, select and detail a shape	Shaping doc with R, shapes, fit checks, breadboard
Slicing	Break down for implementation	Vertical slices with demo-able UI

Shaping分为两个阶段：

Shaping → Slicing

阶段	目标	输出
Shaping	探索问题与解决方案空间，选定并细化一个Shape	包含R、Shapes、适配检查、原型图的Shaping文档
Slicing	拆分方案以用于实现	可演示UI的垂直切片

Phase Transition

阶段过渡

Shaping → Slicing happens when:

A shape is selected (passes fit check, feels right)
The shape has been breadboarded into concrete affordances
We need to plan implementation order

You can't slice without a breadboarded shape.

从Shaping到Slicing的触发条件：

已选定某个Shape（通过适配检查，且符合预期）
该Shape已通过原型图（Breadboard）转化为具体的交互元素
需要规划实现顺序

没有原型图的Shape无法进行Slicing。

Big Picture Through Time

不同阶段的Big Picture

The Big Picture is a living document that reflects the current state of truth at lower levels:

Stage	Big Picture Contains
Exploring shapes	Not needed yet — still comparing options
Shape selected	Frame + Shape (fit check, parts, breadboard)
Shape breadboarded	Same, with full wiring diagram
After slicing	Adds Slices section (sliced breadboard + grid)
During implementation	Updated as slices complete (✅/⏳ status)

The Big Picture always summarizes what exists in the ground truth documents. It evolves as shaping and implementation progress.

Big Picture是动态文档，反映低层级文档的当前真实状态：

阶段	Big Picture包含内容
探索方案选项	暂不需要——仍在对比不同选项
选定Shape	框架 + Shape（适配检查、组件、原型图）
Shape完成原型图	同上，增加完整的连线图
Slicing完成后	新增Slices部分（切片后的原型图 + 切片网格）
实现过程中	随切片完成情况更新（✅/⏳状态）

Big Picture始终汇总基准文档中的内容，会随Shaping和实现过程不断演进。

Fit Check (Decision Matrix)

适配检查（决策矩阵）

THE fit check is the single table comparing all shapes against all requirements. Requirements are rows, shapes are columns. This is how we decide which shape to pursue.

适配检查是唯一用于对比所有Shape与需求的表格。需求为行，Shape为列。这是我们选定Shape的依据。

Format

格式

markdown

undefined

markdown

undefined

Fit Check

适配检查

Req	Requirement	Status	A	B	C
R0	Make items searchable from index page	Core goal	✅	✅	✅
R1	State survives page refresh	Must-have	✅	❌	✅
R2	Back button restores state	Must-have	❌	✅	✅

Notes:

A fails R2: [brief explanation]
B fails R1: [brief explanation]

undefined

Req	需求描述	状态	A	B	C
R0	支持从首页搜索内容	核心目标	✅	✅	✅
R1	状态在页面刷新后保留	必须满足	✅	❌	✅
R2	后退按钮可恢复之前的状态	必须满足	❌	✅	✅

说明：

A未满足R2：[简短解释]
B未满足R1：[简短解释]

undefined

Conventions

规范

Always show full requirement text — never abbreviate or summarize requirements in fit checks
Fit check is BINARY — Use ✅ for pass, ❌ for fail. No other values.
Shape columns contain only ✅ or ❌ — no inline commentary; explanations go in Notes section
Never use ⚠️ or other symbols in fit check — ⚠️ belongs only in the Parts table's flagged column
Keep notes minimal — just explain failures

始终显示完整的需求描述 —— 绝不在适配检查中缩写或简化需求
适配检查结果为二元制 —— 使用✅表示满足，❌表示不满足，无其他值
Shape列仅包含✅或❌ —— 不添加行内注释；解释内容放在“说明”部分
适配检查中禁止使用⚠️或其他符号 —— ⚠️仅用于组件表的标记列
说明部分保持简洁——仅解释未满足的原因

Comparing Alternatives Within a Component

组件内的替代方案对比

When comparing alternatives for a specific component (e.g., C3-A vs C3-B), use the same format but scoped to that component:

markdown

undefined

当对比特定组件的替代方案（如C3-A vs C3-B）时，使用相同格式，但范围限定为该组件：

markdown

undefined

C3: Component Name

C3: 组件名称

Req	Requirement	Status	C3-A	C3-B
R1	State survives page refresh	Must-have	✅	❌
R2	Back button restores state	Must-have	✅	✅

undefined

Req	需求描述	状态	C3-A	C3-B
R1	状态在页面刷新后保留	必须满足	✅	❌
R2	后退按钮可恢复之前的状态	必须满足	✅	✅

undefined

Missing Requirements

缺失需求

If a shape passes all checks but still feels wrong, there's a missing requirement. Articulate the implicit constraint as a new R, then re-run the fit check.

如果某个Shape通过了所有检查，但仍感觉不符合预期，说明存在缺失的需求。将隐含的约束条件明确为新的R，然后重新进行适配检查。

Possible Actions

可执行操作

These can happen in any order:

Populate R - Gather requirements as they emerge
Sketch a shape - Propose a high-level approach (A, B, C...)
Detail (components) - Break a shape into components (B1, B2...)
Detail (affordances) - Expand a selected shape into concrete UI/Non-UI affordances and wiring
Explore alternatives - For a component, identify options (C3-A, C3-B...)
Check fit - Build a fit check (decision matrix) playing options against R
Extract Rs - When fit checks reveal implicit requirements, add them to R as standalone items
Breadboard - Map the system to understand where changes happen and make the shape more concrete
Spike - Investigate unknowns to identify concrete steps needed
Decide - Pick alternatives, compose final solution
Create Big Picture - Once a shape is selected, create the Big Picture summary
Slice - Break a breadboarded shape into vertical slices for implementation

这些操作可按任意顺序进行：

填充R - 随时收集浮现的需求
勾勒Shape - 提出高层级方案思路（A、B、C...）
细化（组件） - 将Shape拆分为组件（B1、B2...）
细化（交互元素） - 将选定的Shape扩展为具体的UI/非UI交互元素及连线
探索替代方案 - 为某个组件确定多个实现选项（C3-A、C3-B...）
执行适配检查 - 构建适配检查（决策矩阵），对比选项与R的匹配度
提炼R - 当适配检查揭示隐含需求时，将其作为独立项添加到R中
制作原型图（Breadboard） - 梳理系统结构，明确变更点，让Shape更具体
预研（Spike） - 调查未知事项，确定实现所需的具体步骤
决策 - 选择替代方案，组合最终解决方案
创建Big Picture - 选定Shape后，创建Big Picture汇总文档
切片（Slice） - 将完成原型图的Shape拆分为垂直切片，用于实现

Communication

沟通规范

Show Full Tables

展示完整表格

When displaying R (requirements) or any S (shapes), always show every row — never summarize or abbreviate. The full table is the artifact; partial views lose information and break the collaborative process.

Show all requirements, even if many
Show all shape parts, including sub-parts (E1.1, E1.2...)
Show all alternatives in fit checks

当展示R（需求）或任何S（方案选项）时，必须显示所有行——绝不能进行汇总或缩写。完整表格是核心工件；部分视图会丢失信息，破坏协作流程。

显示所有需求，即使数量众多
显示所有Shape组件，包括子组件（如E1.1、E1.2...）
显示适配检查中的所有替代方案

Why This Matters

为何如此重要

Shaping is collaborative negotiation. The user needs to see the complete picture to:

Spot missing requirements
Notice inconsistencies
Make informed decisions
Track what's been decided

Summaries hide detail and shift control away from the user.

Shaping是协作协商的过程。用户需要看到完整信息才能：

发现缺失的需求
注意到不一致之处
做出明智决策
跟踪已确定的事项

汇总信息会隐藏细节，将控制权从用户手中转移。

Spikes

预研（Spikes）

A spike is an investigation task to learn how the existing system works and what concrete steps are needed to implement a component. Use spikes when there's uncertainty about mechanics or feasibility.

预研是一项调查任务，用于了解现有系统的工作方式，以及实现某个组件所需的具体步骤。当对实现机制或可行性存在不确定性时，使用预研。

File Management

文件管理

Always create spikes in their own file (e.g.,

spike.md

spike-[topic].md

). Spikes are standalone investigation documents that may be shared or worked on independently from the shaping doc.

始终为预研创建独立文件（如

spike.md

或

spike-[主题].md

）。预研是独立的调查文档，可与Shaping文档分开共享或处理。

Purpose

目标

Learn how the existing system works in the relevant area
Identify what we would need to do to achieve a result
Enable informed decisions about whether to proceed
Not about effort — effort is implicit in the steps themselves
Investigate before proposing — discover what already exists; you may find the system already satisfies requirements

了解现有系统相关领域的工作方式
明确实现目标所需执行的操作
为是否推进提供决策依据
不关注工作量——工作量隐含在步骤本身中
先调查再提案 —— 发现现有系统已有的功能；可能会发现系统已满足需求

Structure

结构

markdown

undefined

markdown

undefined

[Component] Spike: [Title]

[组件] 预研：[标题]

Context

背景

Why we need this investigation. What problem we're solving.

开展此调查的原因，要解决的问题。

Goal

目标

What we're trying to learn or identify.

我们希望了解或明确的内容。

Questions

问题

#	Question
X1-Q1	Specific question about mechanics
X1-Q2	Another specific question

编号	问题
X1-Q1	关于实现机制的具体问题
X1-Q2	另一个具体问题

Acceptance

验收标准

Spike is complete when all questions are answered and we can describe [the understanding we'll have].

undefined

当所有问题都得到解答，且我们能够描述[将获得的认知]时，预研完成。

undefined

Acceptance Guidelines

验收标准规范

Acceptance describes the information/understanding we'll have, not a conclusion or decision:

✅ "...we can describe how users set their language and where non-English titles appear"
✅ "...we can describe the steps to implement [component]"
❌ "...we can answer whether this is a blocker" (that's a decision, not information)
❌ "...we can decide if we should proceed" (decision comes after the spike)

The spike gathers information; decisions are made afterward based on that information.

验收标准描述的是我们将获得的信息/认知，而非结论或决策：

✅ "...我们能够描述用户如何设置语言，以及非英文标题的显示位置"
✅ "...我们能够描述实现[组件]的步骤"
❌ "...我们能够回答这是否是一个障碍"（这是决策，而非信息）
❌ "...我们能够决定是否推进"（决策在预研之后做出）

预研用于收集信息；决策需基于收集到的信息在之后做出。

Question Guidelines

问题规范

Good spike questions ask about mechanics:

"Where is the [X] logic?"
"What changes are needed to [achieve Y]?"
"How do we [perform Z]?"
"Are there constraints that affect [approach]?"

Avoid:

Effort estimates ("How long will this take?")
Vague questions ("Is this hard?")
Yes/no questions that don't reveal mechanics

好的预研问题聚焦于实现机制：

"[X]逻辑位于何处？"
"要实现Y需要做出哪些变更？"
"我们如何执行Z操作？"
"是否存在影响[方案思路]的约束条件？"

避免：

工作量估算（"这需要多长时间？"）
模糊问题（"这很难吗？"）
无法揭示实现机制的是非题

Breadboards

原型图（Breadboards）

Use the

/breadboarding

skill to map existing systems or detail a shape into concrete affordances. Breadboarding produces:

UI Affordances table
Non-UI Affordances table
Wiring diagram grouped by Place

Invoke breadboarding when you need to:

Map existing code to understand where changes land
Translate a high-level shape into concrete affordances
Reveal orthogonal concerns (parts that are independent of each other)

使用

/breadboarding

技能梳理现有系统，或将Shape细化为具体的交互元素。原型图可生成：

UI交互元素表
非UI交互元素表
按位置分组的连线图

在以下场景中使用原型图：

梳理现有代码，明确变更点
将高层级Shape转化为具体交互元素
揭示正交关注点（相互独立的组件）

Tables Are the Source of Truth

表格是基准依据

The affordance tables (UI and Non-UI) define the breadboard. The Mermaid diagram renders them.

When receiving feedback on a breadboard:

First — update the affordance tables (add/remove/modify affordances, update Wires Out)
Then — update the Mermaid diagram to reflect those changes

Never treat the diagram as the primary artifact. Changes flow from tables → diagram, not the reverse.

交互元素表（UI和非UI）定义了原型图。Mermaid图表是这些表格的可视化呈现。

当收到原型图的反馈时：

首先 —— 更新交互元素表（添加/删除/修改交互元素，更新输出连线）
然后 —— 更新Mermaid图表以反映这些变更

绝不能将图表作为核心工件。变更应从表格传导至图表，而非相反。

CURRENT as Reserved Shape Name

CURRENT作为保留Shape名称

Use CURRENT to describe the existing system. This provides a baseline for understanding where proposed changes fit.

使用CURRENT描述现有系统。这为理解拟议变更的位置提供了基准。

Shape Parts

Shape组件

Flagged Unknown (⚠️)

标记未知项（⚠️）

A mechanism can be described at a high level without being concretely understood. The Flag column tracks this:

Part	Mechanism	Flag
F1	Create widget (component, def, register)
F2	Magic authentication handler	⚠️

Empty = mechanism is understood — we know concretely how to build it
⚠️ = flagged unknown — we've described WHAT but don't yet know HOW

Why flagged unknowns fail the fit check:

✅ is a claim of knowledge — it means "we know how this shape satisfies this requirement"
Satisfaction requires a mechanism — some part that concretely delivers the requirement
A flag means we don't know how — we've described what we want, not how to build it
You can't claim what you don't know — therefore it must be ❌

Fit check is always binary — ✅ or ❌ only. There is no third state. A flagged unknown is a failure until resolved.

This distinguishes "we have a sketch" from "we actually know how to do this." Early shapes (A, B, C) often have many flagged parts — that's fine for exploration. But a selected shape should have no flags (all ❌ resolved), or explicit spikes to resolve them.

实现机制可在高层级描述，但无需完全明确。标记列用于跟踪此类情况：

组件	实现机制	标记
F1	创建widget（组件、定义、注册）
F2	魔术认证处理器	⚠️

空白 = 实现机制已明确——我们清楚具体如何构建
⚠️ = 标记为未知——我们已描述了要做什么，但尚未明确如何实现

Parts Must Be Mechanisms

为何标记未知项会导致适配检查失败：

Shape parts describe what we BUILD or CHANGE — not intentions or constraints:

✅ "Route

childType === 'letter'

typesenseService.rawSearch()

" (mechanism)

❌ "Types unchanged" (constraint — belongs in R)

✅代表已掌握实现方法 —— 意味着“我们知道此Shape如何满足该需求”
满足需求需要具体实现机制 —— 某个组件需切实达成需求
标记未知意味着我们不知道实现方法 —— 我们仅描述了想要的结果，而非实现路径
不能声称自己不知道的内容 —— 因此必须标记为❌

适配检查始终为二元制——仅允许✅或❌。不存在第三种状态。标记的未知项在解决前视为未满足。

这区分了“我们有一个初步构想”和“我们确实知道如何实现”。早期的Shape（A、B、C）通常有很多标记的组件——这在探索阶段是正常的。但选定的Shape应无标记（所有❌已解决），或明确通过预研解决这些未知项。

Avoid Tautologies Between R and S

组件必须是实现机制

R states the need/constraint (what outcome). S describes the mechanism (how to achieve it). If they say the same thing, the shape part isn't adding information.

❌ R17: "Admins can bulk request members to sign" + C6.3: "Admin can bulk request members to sign"
✅ R17: "Admins can bring existing members into waiver tracking" + C6.3: "Bulk request UI with member filters, creates WaiverRequests in batch"

The requirement describes the capability needed. The shape part describes the concrete mechanism that provides it. If you find yourself copying text from R into S, stop — the shape part should add specificity about how.

Shape组件描述的是我们要构建或修改的内容——而非意图或约束：

✅ "将

childType === 'letter'

路由至

typesenseService.rawSearch()

"（实现机制）

❌ "类型保持不变"（约束——属于R的范畴）

Parts Should Be Vertical Slices

避免R与S之间的重复

Avoid horizontal layers like "Data model" that group all tables together. Instead, co-locate data models with the features they support:

❌ B4: Data model — Waivers table, WaiverSignatures table, WaiverRequests table
✅ B1: Signing handler — includes WaiverSignatures table + handler logic
✅ B5: Request tracking — includes WaiverRequests table + tracking logic

Each part should be a vertical slice containing the mechanism AND the data it needs.

R定义的是需求/约束（预期结果）。S描述的是实现机制（达成目标的方式）。如果两者内容相同，说明该Shape组件未提供有效信息。

❌ R17：“管理员可批量请求成员签署” + C6.3：“管理员可批量请求成员签署”
✅ R17：“管理员可将现有成员纳入 waiver 跟踪体系” + C6.3：“带成员筛选的批量请求UI，批量创建WaiverRequests”

需求描述的是所需的能力，Shape组件描述的是提供该能力的具体实现机制。如果发现自己将R的内容复制到S中，请停止——Shape组件应补充如何实现的具体信息。

Extract Shared Logic

组件应为垂直切片

When the same logic appears in multiple parts, extract it as a standalone part that others reference:

❌ Duplicating "Signing handler: create WaiverSignature + set boolean" in B1 and B2
✅ Extract as B1: Signing handler, then B2 and B3 say "→ calls B1"

markdown

| **B1** | **Signing handler** |
| B1.1 | WaiverSignatures table: memberId, waiverId, signedAt |
| B1.2 | Handler: create WaiverSignature + set member.waiverUpToDate = true |
| **B2** | **Self-serve signing** |
| B2 | Self-serve purchase: click to sign inline → calls B1 |
| **B3** | **POS signing via email** |
| B3.1 | POS purchase: send waiver email |
| B3.2 | Passwordless link to sign → calls B1 |

避免将“数据模型”等水平层作为组件，将所有表归为一组。相反，应将数据模型与其支持的功能放在一起：

❌ B4: 数据模型 —— Waivers表、WaiverSignatures表、WaiverRequests表
✅ B1: 签署处理器 —— 包含WaiverSignatures表 + 处理器逻辑
✅ B5: 请求跟踪 —— 包含WaiverRequests表 + 跟踪逻辑

每个组件都应是包含实现机制及所需数据的垂直切片。

Hierarchical Notation

提取共享逻辑

Start with flat notation (E1, E2, E3...). Only introduce hierarchy (E1.1, E1.2...) when:

There are too many parts to easily understand
You're reaching a conclusion and want to show structure
Grouping related mechanisms aids communication

Notation	Meaning
E1	Top-level component of shape E
E1.1, E1.2	Sub-parts of E1 (add later if needed)

Example of hierarchical grouping (used when shape is mature):

Part	Mechanism
E1	Swap data source
E1.1	Modify backend indexer
E1.2	Route letters to new service
E1.3	Route posts to new service
E2	Add search input
E2.1	Add input with debounce

当相同逻辑出现在多个组件中时，将其提取为独立组件，供其他组件引用：

❌ 在B1和B2中重复“签署处理器：创建WaiverSignature + 设置布尔值”
✅ 提取为B1: 签署处理器，然后B2和B3中写“→ 调用B1”

markdown

| **B1** | **签署处理器** |
| B1.1 | WaiverSignatures表：memberId、waiverId、signedAt |
| B1.2 | 处理器：创建WaiverSignature + 设置member.waiverUpToDate = true |
| **B2** | **自助签署** |
| B2 | 自助购买：点击内联签署 → 调用B1 |
| **B3** | **通过邮件的POS签署** |
| B3.1 | POS购买：发送waiver邮件 |
| B3.2 | 无密码链接签署 → 调用B1 |

Detailing a Shape

层级符号

When a shape is selected, you can expand it into concrete affordances. This is called detailing.

先使用扁平符号（E1、E2、E3...）。仅在以下情况引入层级符号（E1.1、E1.2...）：

组件数量过多，难以理解
即将得出结论，需要展示结构
分组相关机制有助于沟通

符号	含义
E1	Shape E的顶层组件
E1.1、E1.2	E1的子组件（必要时添加）

层级分组示例（当Shape成熟时使用）：

组件	实现机制
E1	切换数据源
E1.1	修改后端索引器
E1.2	将信件路由至新服务
E1.3	将帖子路由至新服务
E2	添加搜索输入框
E2.1	添加带防抖的输入框

Notation

细化Shape

Use "Detail X" (not a new letter) to show this is a breakdown of Shape X, not an alternative:

markdown

undefined

选定Shape后，可将其扩展为具体的交互元素。这一过程称为细化。

A: First approach

符号规范

(shape table)

使用“Detail X”（而非新字母）表示这是Shape X的分解，而非替代方案：

markdown

undefined

B: Second approach

A: 第一种思路

(shape table)

(shape表格)

Detail B: Concrete affordances

B: 第二种思路

(affordance tables + wiring)

undefined

(shape表格)

What Detailing Produces

Detail B: 具体交互元素

Use the

/breadboarding

skill to produce:

UI Affordances table — Things users see and interact with (inputs, buttons, displays)
Non-UI Affordances table — Data stores, handlers, queries, services
Wiring diagram — How affordances connect across places

(交互元素表 + 连线)

undefined

Why "Detail X" Not "C"

细化产出

Shape letters (A, B, C...) are mutually exclusive alternatives — you pick one. Detailing is not an alternative; it's a deeper breakdown of the selected shape. Using a new letter would incorrectly suggest it's a sibling option.

A, B, C = alternatives (pick one)
Detail B = expansion of B (not a choice)

使用

/breadboarding

技能生成：

UI交互元素表 —— 用户可见并可交互的元素（输入框、按钮、显示内容）
非UI交互元素表 —— 数据存储、处理器、查询、服务
连线图 —— 交互元素在不同位置的连接方式

Documents

为何用“Detail X”而非“C”

Shaping produces up to four documents. Each has a distinct role:

Document	Contains	Purpose
Big Picture	Frame summary, Fit Check, Parts, Breadboard, Sliced Breadboard, Slices grid	10,000-foot view — quick context for driver and developer
Frame	Source, Problem, Outcome	The "why" — concise, stakeholder-level
Shaping doc	Requirements, Shapes (CURRENT/A/B/...), Affordances, Breadboard, Fit Check	The working document — exploration and iteration happen here
Slices doc	Slice details, affordance tables per slice, wiring diagrams	The implementation plan — how to build incrementally
Slice plans	V1-plan.md, V2-plan.md, etc.	Individual implementation plans for each slice

Shape字母（A、B、C...）代表互斥的替代方案——需从中选择一个。细化不是替代方案，而是对选定Shape的深入分解。使用新字母会错误地暗示这是同级选项。

A、B、C = 替代方案（选一个）
Detail B = B的扩展（非选项）

Big Picture Document

文档

The Big Picture is a one-page summary that shows the entire shaped feature at a glance. It helps:

The driver see the whole thing and track what we're doing
The developer maintain context about requirements and shape while working in slices

When to create: After a shape is selected and breadboarded, optionally before slicing is complete. The Big Picture evolves as slicing and implementation progress.

Shaping最多生成四类文档。每类文档都有明确的作用：

文档	包含内容	用途
Big Picture	框架汇总、适配检查、组件、原型图、切片后原型图、切片网格	全局视图——为负责人和开发人员快速提供上下文
框架文档（Frame）	来源、问题、成果	“为什么”——简洁的利益相关者视角
Shaping文档	需求、Shapes（CURRENT/A/B/...）、交互元素、原型图、适配检查	工作文档——探索和迭代在此进行
Slices文档	切片细节、每个切片的交互元素表、连线图	实现计划——如何逐步构建
切片计划	V1-plan.md、V2-plan.md等	每个切片的独立实现计划

Structure — Exactly Three Sections

Big Picture文档

markdown

undefined

Big Picture是单页汇总文档，可快速查看完整的已定型功能。它有助于：

负责人 了解整体情况，跟踪工作进展
开发人员 在处理切片时，保持对需求和Shape的上下文认知

创建时机： 选定Shape并完成原型图后，可在切片完成前创建。Big Picture会随切片和实现过程不断演进。

[Feature Name] — Big Picture

结构 —— 严格分为三个部分

Selected shape: [Letter] ([Short description])

markdown

undefined

Frame

[功能名称] —— Big Picture

Problem

—

[Pain points as bullet list]

选定Shape： [字母]（[简短描述]）

Outcome

框架

—

问题

[Success criteria as bullet list]

[痛点列表，用项目符号]

Shape

成果

Fit Check (R × [Selected Shape])

—

[Fit check table]

[成功标准列表，用项目符号]

Parts

Shape

—

适配检查（R × [选定Shape]）

[Parts table with Flag column]

[适配检查表]

Breadboard

组件

[Full Mermaid breadboard]

[带标记列的组件表]

Slices

原型图

[Sliced breadboard — Mermaid diagram with slice boundaries]

[Slices grid — markdown table]

---

[完整的Mermaid原型图]

Frame Section

切片

Copy Problem and Outcome from the Frame doc or shaping doc. Use bullet lists.

markdown

undefined

[切片后原型图——带切片边界的Mermaid图表]

[切片网格——markdown表格]

---

Frame

框架部分

Problem

—

Users cannot search letter content to find what they're looking for
When users navigate to a letter detail and come back, pagination state is lost
Page refresh loses any filter state

从框架文档或Shaping文档中复制问题和成果。使用项目符号列表。

markdown

undefined

Outcome

框架

—

问题

Users can search letters by content directly from the index page
Search and scroll state survives page refresh
Browser back button restores previous state

---

用户无法搜索信件内容以找到所需信息
用户导航至信件详情页后返回，分页状态丢失
页面刷新会丢失所有筛选状态

Shape Section

成果

Contains three parts: Fit Check, Parts, and Breadboard.

Fit Check (R × [Shape]):

Show only the selected shape column. Full requirement text in every row.

markdown

undefined

用户可从首页直接搜索信件内容
搜索和滚动状态在页面刷新后保留
浏览器后退按钮可恢复之前的状态

---

Fit Check (R × F)

Shape部分

Req	Requirement	Status	F
R0	Make letters searchable from the index page	Core goal	✅
R2	Navigate back to pagination state when returning from post detail	Must-have	✅
R3	Navigate back to search state when returning from post detail	Must-have	✅


**Parts table:**

Include the Flag column for flagged unknowns. Use "Flag" as the header, ⚠️ in flagged rows. Center-align with `:----:`.

```markdown

包含三个子部分：适配检查、组件、原型图。

适配检查（R × [选定Shape]）：

仅显示选定Shape的列。每行显示完整的需求描述。

markdown

undefined

Parts

适配检查（R × F）

Part	Mechanism	Flag
F1	Create `letter-browser` widget (component, def, register in CMS)
F2	URL state & initialization (read `?q=` `?page=` , restore on load)
F3	Search input (debounce, min 3 chars, triggers search)	⚠️


**Breadboard:**

Include the full Mermaid breadboard from the shaping doc. Use `flowchart TB` (top-to-bottom). Include:
- Place subgraphs (`subgraph lettersIndex["PLACE: Letters Index Page"]`)
- Component subgraphs nested inside places
- UI affordances (U1, U2...) and Non-UI affordances (N1, N2...)
- Wires Out as solid arrows (`-->`)
- Returns To as dashed arrows (`-.->`)
- Node styling (pink for UI, grey for Non-UI)

Always include a legend after the breadboard:

```markdown
**Legend:**
- **Pink nodes (U)** = UI affordances (things users see/interact with)
- **Grey nodes (N)** = Code affordances (data stores, handlers, services)
- **Solid lines** = Wires Out (calls, triggers, writes)
- **Dashed lines** = Returns To (return values, data store reads)

Req	需求描述	状态	F
R0	支持从首页搜索信件内容	核心目标	✅
R2	从帖子详情页返回时，恢复分页状态	必须满足	✅
R3	从帖子详情页返回时，恢复搜索状态	必须满足	✅


**组件表：**

包含标记列，用于标记未知项。表头使用“标记”，标记行使用⚠️。使用`:----:`居中对齐。

```markdown

Slices Section

组件

Contains two parts: Sliced Breadboard and Slices Grid.

Sliced Breadboard:

A modified version of the main breadboard with slice boundaries shown as colored subgraphs.

Key patterns:

Slice subgraphs:
```
subgraph slice1["V1: SLICE NAME"]
```
— wrap each slice's affordances
Invisible links for ordering:
```
slice1 ~~~ slice2
```
— forces V1 before V2 in layout
Colored fills: Each slice gets a distinct fill color and matching stroke
Transparent nested subgraphs: Components inside slices use
```
fill:transparent
```
to inherit the slice color

mermaid

flowchart TB
    subgraph slice1["V1: WIDGET WITH REAL DATA"]
        subgraph letterBrowser1["letter-browser"]
            U2["U2: loading spinner"]
            U3["U3: no results msg"]
            N3["N3: performSearch"]
        end
        N4["N4: rawSearch"]
    end

    subgraph slice2["V2: SEARCH WORKS"]
        U1["U1: search input"]
        N1["N1: activeQuery.next"]
    end

    %% Force slice ordering (invisible links)
    slice1 ~~~ slice2

    %% Cross-slice wiring
    U1 -->|type| N1
    N1 --> N3
    N3 --> N4

    %% Slice boundary styling (colored fills)
    style slice1 fill:#e8f5e9,stroke:#4caf50,stroke-width:2px
    style slice2 fill:#e3f2fd,stroke:#2196f3,stroke-width:2px

    %% Nested subgraphs transparent (inherit slice color)
    style letterBrowser1 fill:transparent,stroke:#888,stroke-width:1px

    %% Node styling
    classDef ui fill:#ffb6c1,stroke:#d87093,color:#000
    classDef nonui fill:#d3d3d3,stroke:#808080,color:#000
    class U1,U2,U3 ui
    class N1,N3,N4 nonui

Slice color palette (use consistently):

V1:
```
fill:#e8f5e9,stroke:#4caf50
```
(green)
V2:
```
fill:#e3f2fd,stroke:#2196f3
```
(blue)
V3:
```
fill:#fff3e0,stroke:#ff9800
```
(orange)
V4:
```
fill:#f3e5f5,stroke:#9c27b0
```
(purple)
V5:
```
fill:#fff8e1,stroke:#ffc107
```
(yellow)
V6:
```
fill:#fce4ec,stroke:#e91e63
```
(pink)

Slices Grid:

A markdown table with an empty header row. Aim for 2 rows × 3 columns (6 slices) or 3 rows × 3 columns (9 slices).

Each cell contains:

Linked title:

**[V1: SLICE NAME](./feature-v1-plan.md)**

(link to slice plan file)

Status:
```
✅ COMPLETE
```
or
```
⏳ PENDING
```
Bullet list: 3-4 key items using
```
• 
```
(bullet + space)
Demo: Italicized description of what can be demoed
Use
<br>
for line breaks within cells
Use
•  
as a spacer bullet to equalize cell heights

markdown

|  |  |  |
|:--|:--|:--|
| **[V1: WIDGET WITH REAL DATA](./letter-search-v1-plan.md)**<br>✅ COMPLETE<br><br>• Create letter-browser widget<br>• Register in CMS system<br>• rawSearch() with parentId<br>• Loading, empty, results UI<br><br>*Demo: Widget shows real letters* | **[V2: SEARCH WORKS](./letter-search-v2-plan.md)**<br>✅ COMPLETE<br><br>• Search input + activeQuery<br>• Debounce 90ms, min 3 chars<br>• Query passed to rawSearch()<br>• &nbsp;<br><br>*Demo: Type "dharma", results filter live* | **[V3: INFINITE SCROLL](./letter-search-v3-plan.md)**<br>✅ COMPLETE<br><br>• Intercom scroll subscription<br>• appendNextPage()<br>• Re-arm scroll detection<br>• &nbsp;<br><br>*Demo: Scroll down, more letters load* |
| **[V4: URL STATE](./letter-search-v4-plan.md)**<br>✅ COMPLETE<br><br>• ?q= and ?page= in URL<br>• initializeState() on load<br>• Router.navigate() on change<br>• Back button restores state<br><br>*Demo: Search, refresh, back all restore state* | **[V5: COMPACT MODE](./letter-search-v5-plan.md)**<br>✅ COMPLETE<br><br>• data.compact config<br>• Conditional scroll subscribe<br>• "See all X results" link<br>• Navigate with ?q=query<br><br>*Demo: compact=true shows fixed items + "See all" link* | **V6: CUTOVER**<br>⏳ PENDING<br><br>a) Local validation + R14<br>b) Deploy code (safe)<br>c) CMS cutover<br>d) Code cleanup<br><br>*TODO: Typesense index job* |

Note: Slices that are pending don't need links yet. Add links when the slice plan is created.

组件	实现机制	标记
F1	创建 `letter-browser` widget（组件、定义、在CMS中注册）
F2	URL状态与初始化（读取 `?q=` `?page=` ，加载时恢复）
F3	搜索输入框（防抖、最少3个字符、触发搜索）	⚠️


**原型图：**

包含Shaping文档中的完整Mermaid原型图。使用`flowchart TB`（从上到下）。包含：
- 位置子图（`subgraph lettersIndex["PLACE: Letters Index Page"]`）
- 嵌套在位置内的组件子图
- UI交互元素（U1、U2...）和非UI交互元素（N1、N2...）
- 输出连线（实线箭头`-->`）
- 返回连线（虚线箭头`-.->`）
- 节点样式（UI为粉色，非UI为灰色）

原型图后必须包含图例：

```markdown
**图例：**
- **粉色节点（U）** = UI交互元素（用户可见/可交互的内容）
- **灰色节点（N）** = 代码交互元素（数据存储、处理器、服务）
- **实线** = 输出连线（调用、触发、写入）
- **虚线** = 返回连线（返回值、数据存储读取）

Creating a Big Picture — Step by Step

切片部分

Create the file:
```
[feature]-big-picture.md
```
in the shaping docs folder
Add header: Feature name and selected shape with short description
Frame section: Copy Problem and Outcome from Frame doc or shaping doc
Shape section:
- Copy Fit Check from shaping doc, showing only selected shape column
- Copy Parts table, add Flag column if not present (mark any unknowns with ⚠️)
- Copy full Mermaid breadboard from shaping doc
- Add legend after breadboard
Slices section (after slicing is complete):
- Create sliced breadboard by wrapping affordances in slice subgraphs
- Add invisible links between slices for ordering
- Add colored fills to slice subgraphs
- Make nested component subgraphs transparent
- Create slices grid table with linked titles, status, bullets, demos
Maintain consistency: When lower-level docs change, update the Big Picture to reflect those changes (see Multi-Level Consistency)

包含两个子部分：切片后原型图和切片网格。

切片后原型图：

主原型图的修改版本，用彩色子图显示切片边界。

核心模式：

切片子图：
```
subgraph slice1["V1: 切片名称"]
```
—— 包裹每个切片的交互元素
排序用不可见链接：
```
slice1 ~~~ slice2
```
—— 强制V1在V2之前显示
彩色填充：每个切片使用不同的填充色和匹配的边框
透明嵌套子图：切片内的组件使用
```
fill:transparent
```
，继承切片颜色

mermaid

flowchart TB
    subgraph slice1["V1: 含真实数据的Widget"]
        subgraph letterBrowser1["letter-browser"]
            U2["U2: 加载中动画"]
            U3["U3: 无结果提示"]
            N3["N3: 执行搜索"]
        end
        N4["N4: 原始搜索"]
    end

    subgraph slice2["V2: 搜索功能生效"]
        U1["U1: 搜索输入框"]
        N1["N1: activeQuery.next"]
    end

    %% 强制切片排序（不可见链接）
    slice1 ~~~ slice2

    %% 跨切片连线
    U1 -->|输入| N1
    N1 --> N3
    N3 --> N4

    %% 切片边界样式（彩色填充）
    style slice1 fill:#e8f5e9,stroke:#4caf50,stroke-width:2px
    style slice2 fill:#e3f2fd,stroke:#2196f3,stroke-width:2px

    %% 嵌套子图透明（继承切片颜色）
    style letterBrowser1 fill:transparent,stroke:#888,stroke-width:1px

    %% 节点样式
    classDef ui fill:#ffb6c1,stroke:#d87093,color:#000
    classDef nonui fill:#d3d3d3,stroke:#808080,color:#000
    class U1,U2,U3 ui
    class N1,N3,N4 nonui

切片调色板（统一使用）：

V1:
```
fill:#e8f5e9,stroke:#4caf50
```
（绿色）
V2:
```
fill:#e3f2fd,stroke:#2196f3
```
（蓝色）
V3:
```
fill:#fff3e0,stroke:#ff9800
```
（橙色）
V4:
```
fill:#f3e5f5,stroke:#9c27b0
```
（紫色）
V5:
```
fill:#fff8e1,stroke:#ffc107
```
（黄色）
V6:
```
fill:#fce4ec,stroke:#e91e63
```
（粉色）

切片网格：

一个带空表头的markdown表格。目标为2行×3列（6个切片）或3行×3列（9个切片）。

每个单元格包含：

带链接的标题：
```
**[V1: 切片名称](./feature-v1-plan.md)**
```
（链接到切片计划文件）
状态：
```
✅ 已完成
```
或
```
⏳ 待处理
```
项目符号列表：3-4个关键项，使用
```
• 
```
（项目符号+空格）
演示说明：斜体描述可演示的内容
单元格内使用
<br>
换行
使用
•  
作为占位项目符号，使单元格高度一致

markdown

|  |  |  |
|:--|:--|:--|
| **[V1: 含真实数据的Widget](./letter-search-v1-plan.md)**<br>✅ 已完成<br><br>• 创建letter-browser widget<br>• 在CMS系统中注册<br>• 带parentId的rawSearch()<br>• 加载中、空状态、结果UI<br><br>*演示：Widget显示真实信件* | **[V2: 搜索功能生效](./letter-search-v2-plan.md)**<br>✅ 已完成<br><br>• 搜索输入框 + activeQuery<br>• 90ms防抖、最少3个字符<br>• 查询传递至rawSearch()<br>• &nbsp;<br><br>*演示：输入“dharma”，结果实时过滤* | **[V3: 无限滚动](./letter-search-v3-plan.md)**<br>✅ 已完成<br><br>• Intercom滚动订阅<br>• appendNextPage()<br>• 重新启用滚动检测<br>• &nbsp;<br><br>*演示：向下滚动，加载更多信件* |
| **[V4: URL状态](./letter-search-v4-plan.md)**<br>✅ 已完成<br><br>• URL中的?q=和?page=<br>• 加载时initializeState()<br>• 变更时Router.navigate()<br>• 后退按钮恢复状态<br><br>*演示：搜索、刷新、后退均恢复状态* | **[V5: 紧凑模式](./letter-search-v5-plan.md)**<br>✅ 已完成<br><br>• data.compact配置<br>• 条件式滚动订阅<br>• “查看全部X条结果”链接<br>• 带?q=query的导航<br><br>*演示：compact=true显示固定数量项 + “查看全部”链接* | **V6: 切换**<br>⏳ 待处理<br><br>a) 本地验证 + R14<br>b) 部署代码（安全）<br>c) CMS切换<br>d) 代码清理<br><br>*待办：Typesense索引任务* |

注意：待处理的切片无需添加链接。创建切片计划后再添加链接。

Document Lifecycle

创建Big Picture的步骤

Frame (problem/outcome)
    ↓
Shaping (explore, detail, breadboard)
    ↓
Slices (plan implementation)
    ↓
Big Picture (summarizes all of the above)

Frame can be written first — it captures the "why" before any solution work begins. It contains:

Source — Original requests, quotes, or material that prompted the work (verbatim)
Problem — What's broken, what pain exists (distilled from source)
Outcome — What success looks like (high-level, not solution-specific)

创建文件：在Shaping文档文件夹中创建
```
[feature]-big-picture.md
```
添加标题：功能名称 + 选定Shape的简短描述
框架部分：从框架文档或Shaping文档中复制问题和成果
Shape部分：
- 从Shaping文档中复制适配检查，仅显示选定Shape的列
- 复制组件表，若未包含标记列则添加（用⚠️标记未知项）
- 从Shaping文档中复制完整的Mermaid原型图
- 在原型图后添加图例
切片部分（切片完成后）：
- 创建切片后原型图，将交互元素包裹在切片子图中
- 添加切片间的不可见链接以排序
- 为切片子图添加彩色填充
- 将嵌套组件子图设为透明
- 创建切片网格表，包含带链接的标题、状态、项目符号、演示说明
保持一致性：当低层级文档变更时，更新Big Picture以反映这些变更（参见“多级一致性”）

Capturing Source Material

文档生命周期

When the user provides source material during framing (user requests, quotes, emails, slack messages, etc.), always capture it verbatim in a Source section at the top of the frame document.

markdown

undefined

框架文档（问题/成果）
    ↓
Shaping文档（探索、细化、原型图）
    ↓
Slices文档（规划实现）
    ↓
Big Picture（汇总以上所有内容）

框架文档可最先编写——它在任何解决方案工作开始前，捕捉“为什么”的问题。包含：

来源 —— 触发工作的原始请求、引用或材料（原文）
问题 —— 存在的问题、痛点（从来源提炼）
成果 —— 成功的标准（高层级，非解决方案特定）

Source

捕捉来源材料

I'd like to ask again for your thoughts on a user scenario...

Small reminder: at the moment, if I want to keep my country admin rights for Russia and Crimea while having Europe Center as my home center...

[Additional source material added as received]

当用户在框架阶段提供来源材料（用户请求、引用、邮件、Slack消息等）时，必须原文捕捉在框架文档顶部的“来源”部分。

markdown

undefined

Problem

来源

...


**Why this matters:**
- The source is the ground truth — Problem/Outcome are interpretations
- Preserves context that may be relevant later
- Allows revisiting the original request if the distillation missed something
- Multiple sources can be added as they arrive during framing

**When to capture:**
- User pastes a request or quote
- User shares an email or message from a stakeholder
- User describes a scenario they were told about
- Any raw material that informs the frame

**Shaping doc** is where active work happens. All exploration, requirements gathering, shape comparison, breadboarding, and fit checking happens here. This is the working document and ground truth for R, shapes, parts, and fit checks.

**Slices doc** is created when the selected shape is breadboarded and ready to build. It contains the slice breakdown, affordance tables per slice, and detailed wiring.

**Big Picture** is created once a shape is selected. It summarizes the Frame, Shape, and (once slicing is done) Slices. It stays in sync with the ground truth documents throughout implementation.

我想再次询问您对某个用户场景的看法...

温馨提醒：目前，如果我想保留俄罗斯和克里米亚的国家管理员权限，同时将欧洲中心设为我的主中心...

[收到其他来源材料时添加]

File Management

问题

Shaping doc: Update freely as you iterate — this is the ground truth
Slices doc: Created when ready to slice, updated as slice scope clarifies
Slice plans: Individual files (V1-plan.md, etc.) with implementation details
Big Picture: Created when shape is selected, updated to reflect lower-level changes

...


**为何如此重要：**
- 来源是基准事实——问题/成果是对来源的解读
- 保留可能在后续相关的上下文
- 若解读遗漏了某些内容，可重新查看原始请求
- 框架阶段收到多个来源时，可全部添加

**捕捉时机：**
- 用户粘贴请求或引用
- 用户分享利益相关者的邮件或消息
- 用户描述被告知的场景
- 任何为框架提供信息的原始材料

**Shaping文档**是开展工作的核心。所有探索、需求收集、Shape对比、原型图制作和适配检查都在此进行。这是R、Shapes、组件和适配检查的基准工作文档。

**Slices文档**在选定Shape完成原型图并准备构建时创建。包含切片分解、每个切片的交互元素表和详细连线。

**Big Picture**在选定Shape后创建。汇总框架、Shape和（切片完成后）切片的内容。在实现过程中始终与基准文档保持同步。

Keeping Documents in Sync

文件管理

See Multi-Level Consistency at the top of this document. Changes at any level must ripple to affected levels above and below.

Shaping文档：迭代过程中可自由更新——这是基准文档
Slices文档：准备切片时创建，随切片范围明确而更新
切片计划：独立文件（V1-plan.md等），包含实现细节
Big Picture：选定Shape后创建，更新以反映低层级变更

Slicing

保持文档同步

After a shape is breadboarded, slice it into vertical implementation increments. Use the

/breadboarding

skill for the slicing process — it defines what vertical slices are, the procedure for creating them, and visualization formats.

The flow:

Parts → high-level mechanisms in the shape
Breadboard → concrete affordances with wiring (use
```
/breadboarding
```
)
Slices → vertical increments that can each be demoed (use
```
/breadboarding
```
slicing section)

Key principle: Every slice must end in demo-able UI. A slice without visible output is a horizontal layer, not a vertical slice.

Document outputs:

Slices doc — slice definitions, per-slice affordance tables, sliced breadboard
Slice plans — individual implementation plans (V1-plan.md, V2-plan.md, etc.)

参见本文档顶部的多级一致性部分。任何层级的变更必须传导至所有受影响的上层和下层文档。

Example

切片（Slicing）

User is shaping a search feature:

markdown

undefined

Shape完成原型图后，将其拆分为垂直实现增量。使用

/breadboarding

技能进行切片——该技能定义了什么是垂直切片、创建切片的流程以及可视化格式。

流程：

组件 → Shape中的高层级实现机制
原型图 → 带连线的具体交互元素（使用
```
/breadboarding
```
）
切片 → 可独立演示的垂直增量（使用
```
/breadboarding
```
的切片部分）

核心原则： 每个切片必须以可演示的UI收尾。没有可见输出的切片是水平层，而非垂直切片。

文档产出：

Slices文档 —— 切片定义、每个切片的交互元素表、切片后原型图
切片计划 —— 独立的实现计划（V1-plan.md、V2-plan.md等）

Requirements (R)

示例

ID	Requirement	Status
R0	Make items searchable from index page	Core goal
R1	State survives page refresh	Undecided
R2	Back button restores state	Undecided

用户正在构建搜索功能：

markdown

undefined

C2: State Persistence

需求（R）

Req	Requirement	Status	C2-A	C2-B	C2-C
R0	Make items searchable from index page	Core goal	—	—	—
R1	State survives page refresh	Undecided	✅	✅	❌
R2	Back button restores state	Undecided	✅	✅	✅

Notes:

C2-C fails R1: in-memory state lost on refresh
C2-B satisfies R2 but requires custom popstate handler

undefined

ID	需求描述	状态
R0	支持从首页搜索内容	核心目标
R1	状态在页面刷新后保留	未确定
R2	后退按钮可恢复之前的状态	未确定

—

C2: 状态持久化

—

Req	需求描述	状态	C2-A	C2-B	C2-C
R0	支持从首页搜索内容	核心目标	—	—	—
R1	状态在页面刷新后保留	未确定	✅	✅	❌
R2	后退按钮可恢复之前的状态	未确定	✅	✅	✅

说明：

C2-C未满足R1：内存状态在刷新后丢失
C2-B满足R2，但需要自定义popstate处理器

undefined