wachi-definicion

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

/wachi-definicion — el artefacto que madura

/wachi-definicion — 可迭代成熟的工件

Escribís el contrato de producto de una ficha: qué se construye y cómo sabremos que está bien — con el detalle justo. Un solo artefacto que se enriquece in-place a medida que avanza (el contenido versionado de la ficha), nunca un doc funcional y uno técnico gemelos que driftan.

Fuente robada (skill propia, el original NO se invoca): EveryInc/compound-engineering-plugin
ce-brainstorm
+
ce-plan
@ v3.17.0 (artefacto unificado, secciones canónicas, scoping synthesis, prose economy). Re-sync: revisar upstream cada ~2 meses. Aterrizaje en RumIAndo:
skills/wachi-producto/references/aterrizaje-rumiando.md
. Embebé el spine (
_shared/agent-spine.md
): voz directa, anti-slop, quote-the-evidence, completion honesto.

你为需求卡片撰写产品契约：要构建什么、如何判定合格——篇幅恰到好处。仅用单个工件随进度原地迭代丰富（即需求卡片的版本化内容），绝不会出现功能文档和技术文档两份孪生文档内容脱节的情况。

借鉴来源（自有技能，不调用原版）：EveryInc/compound-engineering-plugin 的
ce-brainstorm
+
ce-plan
@ v3.17.0（统一工件、规范章节、范围整合、精简行文）。重新同步：约每2个月检查上游更新。 RumIAndo落地文档：
skills/wachi-producto/references/aterrizaje-rumiando.md
嵌入核心准则（
_shared/agent-spine.md
）：直接表达、拒绝冗余、引用依据、如实反馈完成度。

⚖️ IRON LAW

⚖️ 铁律

CONFIRMÁ EL ALCANCE ANTES DE ESCRIBIR. Corregir el alcance en la charla es barato; corregirlo después de escribir el artefacto (o peor, después de validar) es caro. Y: el progreso NO vive en el doc — vive en la state machine de RumIAndo. El doc solo declara su completitud.

撰写前必须先确认范围。 在沟通阶段调整范围成本很低；写完工件后再调整（更糟的是验证后再调整）成本极高。另外：进度不由文档体现——进度由RumIAndo的状态机记录。文档仅声明自身的完成度。

Fase 0 — Alcance primero (surface-scope-earlier)

阶段0 — 范围优先（surface-scope-earlier）

Antes de escribir una línea del artefacto, armá la síntesis de alcance en tres baldes:

Declarado — lo que el usuario pidió explícitamente.
Inferido — lo que vos completaste (¡esto es lo peligroso!).
Fuera de alcance — lo que NO entra, dicho.

Emití los call-outs: los puntos donde una decisión del usuario cambia materialmente el plan ("¿offline-first o requiere señal?", "¿solo técnicos o también productores?"). Confirmación bloqueante (AskUserQuestion, una por vez) salvo profundidad Liviana con cero call-outs → ahí procedé directo.

在撰写工件的任何内容之前，先将范围汇总分为三类：

已声明 — 用户明确提出的需求。
推断项 — 你自行补充的内容（这部分是风险点！）。
超出范围 — 明确不纳入的内容。

列出所有待确认项（call-outs）：即用户的决策会实质性影响方案的点（例如“是offline-first还是需要网络信号？”“仅面向技术人员还是也面向产品人员？”）。阻塞式确认（调用AskUserQuestion，一次问一个），除非是轻量级需求且无待确认项→这种情况可以直接推进。

Fase 1 — Entendé y dialogá

阶段1 — 理解与沟通

Leé el contenido actual de la ficha (versiones previas, la ideación si vino de
```
wachi-ideacion
```
) y la materia prima del fichero (
```
fichero_input
```
).
Presión de producto (interna, no se la muestres al usuario): ¿dónde le falta rigor a la idea? ¿qué condición de borde nadie nombró? Usala para dirigir el diálogo.
Diálogo colaborativo: separá los QUÉ (requisitos) de los CÓMO (implementación — no los resuelvas acá; si son decisiones que constriñen, van como Decisiones Clave).

阅读需求卡片的当前内容（历史版本，如果来自
```
wachi-ideacion
```
则查看构思内容）以及文件的原始素材（
```
fichero_input
```
）。
产品严谨性校验（内部使用，不要展示给用户）：想法的哪些地方不够严谨？有哪些边界条件没人提到？用这些问题引导沟通。
协作沟通：将**「是什么」（需求）和「怎么做」（实现）**分开——这里不解决实现问题；如果是会产生约束的决策，归入「关键决策」。

Fase 2 — Escribí el contrato (right-sized)

阶段2 — 撰写产品契约（right-sized）

Piso duro (siempre): Cápsula de Objetivo (objetivo, autoridad, bloqueantes abiertos) + Contrato de Producto con requisitos con IDs estables (

R1.

R2.

— prefijo plano, nunca renumerar al reordenar/borrar).

Secciones "incluir cuando aporten" (decidí por contenido, no llenes plantilla):

Sección	Incluila si…
Marco del problema	la motivación no es obvia desde el resumen
Decisiones clave	hubo elecciones de encuadre que constriñen (defaults, recortes de alcance)
Actores ( `A1.` )	hay comportamiento multi-parte (técnico, productor, admin…)
Flujos clave ( `F1.` )	hay comportamiento multi-paso (default esperable en features de comportamiento)
Ejemplos de aceptación ( `EA1.` )	algún requisito es condicional/depende de estado y queda ambiguo sin ejemplo
Criterios de éxito	hay señales de calidad/métrica que los requisitos no llevan
Fronteras de alcance	el alcance está disputado o hay non-goals tentadores (separá "diferido" de "fuera de la identidad del producto")
Preguntas abiertas	hay pendientes — distinguí bloqueantes (resolver antes de validar) de diferidas (las contesta el build)
Visualizaciones / wireframe	el concepto tiene estructura que mostrar (flujo, estados, relación de entidades) — las UI necesitan wireframe, no prosa
Fuentes	hay research que justifique el encuadre

Economía de prosa: encabezá con la decisión, después la razón. Una idea por oración. Un requisito = una oración de intención + a lo sumo un calificador. Sin relleno ni hedges. Resolvé en el lugar (reescribí lo superado), no estratifiques.

Cuándo NO escribir artefacto (las dos juntas): el diálogo no produjo alcance/decisiones dignas de IDs, y lo decidido fluye a los artefactos siguientes sin doc intermedio. Un ajuste trivial no necesita contrato — decilo y aterrizá directo.

硬性必含内容（始终需要）：目标概要（目标、负责方、未解决阻塞项） + 产品契约，其中需求需带稳定ID（

R1.

、

R2.

——使用扁平前缀，重新排序/删除时绝不要重新编号）。

「按需添加」章节（根据内容决定，不要为了填模板而加）：

章节	添加条件
问题背景	从摘要无法明显看出动机
关键决策	存在会产生约束的框架选择（默认值、范围裁剪）
角色（ `A1.` ）	涉及多方角色的行为（技术人员、产品人员、管理员等）
核心流程（ `F1.` ）	涉及多步骤行为（功能类需求的默认预期项）
验收示例（ `EA1.` ）	某个需求是条件性的/依赖状态，没有示例会产生歧义
成功标准	存在需求未覆盖的质量信号/指标
范围边界	范围存在争议，或有容易被误纳入的非目标（区分「延后实现」和「不属于产品定位」）
待解决问题	存在未决事项——区分阻塞项（验证前必须解决）和延后项（构建阶段再确认）
可视化 / wireframe	概念有需要展示的结构（流程、状态、实体关系）——UI类需求需要wireframe，而非文字描述
参考来源	有调研依据支撑框架设定

精简行文原则： 先给出结论，再说明原因。一句话只讲一个观点。一个需求 = 一句意图描述 + 至多一个限定条件。不要填充内容，不要模糊表述。直接修改更新（重写过时内容），不要堆叠旧内容。

无需撰写工件的情况（需同时满足）：沟通没有产生值得分配ID的范围/决策，且已确定的内容可以直接流转到后续工件，不需要中间文档。微小调整不需要产品契约——直接说明并落地即可。

Fase 3 — Aterrizá

阶段3 — 落地

El contrato es el contenido de la ficha:
```
guardar_ficha
```
(versiona snapshot inmutable;
```
p_nota
```
= qué cambió en esta versión). El JSONB
```
contenido
```
lleva las secciones; los IDs estables (
```
R*/A*/F*/EA*
```
) hacen trazable la validación y el build.
Sembrá el DoR (
```
actualizar_dor_ficha
```
): los ítems que este contrato ya sabe que deben cumplirse antes de construir (ej. "validado con ≥1 usuario", "sin preguntas bloqueantes", "wireframe revisado") — nacen
```
done: false
```
.
Cuando el contrato está completo y sin preguntas bloqueantes →
```
transition_ficha(→PARA_VALIDAR)
```
. Si quedan bloqueantes, la ficha se queda en
```
BORRADOR
```
— la completitud es binaria, no "casi lista".

Handoff: ficha en

PARA_VALIDAR

→ wachi-validacion-usuario
(o directo a

wachi-validacion-interna

si la profundidad Liviana no amerita sesión con usuarios — decilo explícito).

契约就是需求卡片的内容：调用
```
guardar_ficha
```
（生成不可变的版本快照；
```
p_nota
```
参数填写本次版本的变更内容）。JSONB类型的
```
contenido
```
字段存储各章节内容；稳定ID（
```
R*/A*/F*/EA*
```
）让验证和构建过程可追溯。
植入DoR（就绪定义）（调用
```
actualizar_dor_ficha
```
）：本契约已明确的、构建前必须满足的事项（例如“已通过≥1位用户验证”、“无阻塞性问题”、“wireframe已评审”）——初始状态均为
```
done: false
```
。
当契约内容完整且无阻塞性问题时 → 调用
```
transition_ficha(→PARA_VALIDAR)
```
（流转至待验证状态）。如果仍有阻塞项，需求卡片保持
```
BORRADOR
```
（草稿）状态——完成度是二元的，没有“差不多完成”。

交接：处于

PARA_VALIDAR

（待验证）状态的需求卡片 → 流转至**

wachi-validacion-usuario

**（如果是轻量级需求不需要用户验证环节，也可直接流转至

wachi-validacion-interna

——需明确说明）。