Hai Razor

Hai Razor

For Chinese readers, see SKILL.zh_CN.md. The English SKILL.md is the execution source of truth.

Overview

Audit the existence of product requirements, workflow steps, data fields, states, modules, layers, abstractions, service boundaries, and design choices, then classify each as Keep/Merge/Defer/Delete/Replace/Prove-first with evidence. The goal is not a smaller system — see Core Principle for the bar a concept must clear.

Core Principle

Every concept must earn its existence.

A thing deserves to exist only when removing it would break a real goal, erase a real distinction, hide an important risk, or push unavoidable complexity onto a worse owner. If a concept survives only because of habit, fear, symmetry, imagined future needs, or aesthetic completeness, cut it, merge it, defer it, or demand proof. Cutting real distinctions, safety, observability, permissions, migration paths, or a deep module that hides genuine complexity is not simplification — it is damage.

Razor Targets

Audit anything that claims a separate existence. The existence question is the lens for each type.

Classify Each Concept

After running the deletion test and finding the hidden owner (Workflow steps 4-5), assign every concept exactly one verdict.

Workflow

1. Name the chain being cut. State the scope (PRD section, feature flow, data model, module boundary, architecture chain, or implementation plan), the current goal it claims to serve, and list every concept asking for independent existence.

2. Gather evidence before judgment. Review the PRDs, docs, code, schemas, traces, tests, metrics, user flows, support cases, or decision records that bear on each concept. Separate evidence from inference — if a claim is plausible but unproven, label it an assumption or "prove first." Prefer concrete evidence about current behavior over imagined future extensibility. Every keep/cut/merge/defer/replace verdict needs a reason grounded in evidence, or an explicit statement that evidence is missing.

3. Map the current chain when the cut is structural. If the recommendation changes a substantial workflow, process, module chain, state machine, service boundary, or architecture flow, include before/after Mermaid diagrams — because a structural cut silently relocates responsibility, and a reviewer needs to see who now owns it. The before diagram shows existing actors, modules, steps, state/data flow, and where complexity currently lives; the after diagram shows what is deleted, merged, deferred, or moved, and who absorbs the rest. Skip diagrams only for small local audits where a table is clearer than a flow map.

4. Run the deletion test. For each concept ask: if this disappears, what concretely breaks? Distinguish "something feels less complete" from "a user goal, invariant, operation, safety property, or decision fails." If nothing breaks, the concept is suspect.

5. Find the hidden owner. If the concept is removed, who must absorb its responsibility? If it moves to a worse place, the concept may deserve to stay. If an existing concept can absorb it with less cognitive load, merge it.

6. Classify each concept using the decision table above. Give every concept exactly one verdict with its reason.

7. Protect necessary complexity. Explicitly name what should not be cut: complexity that prevents invalid states, secures trust boundaries, supports recovery, improves observability, or hides implementation behind a deep interface.

8. Attack the remaining design. Ask how future builders would reintroduce the deleted concept, and whether the cut creates hidden coupling, vague ownership, migration risk, or unclear acceptance. Add a guardrail: naming, test, doc boundary, acceptance criterion, architecture note, or follow-up proof.

9. Emit an HTML artifact for full audits. Path: /tmp/hai-razor-<slug>/index.html. After the Markdown answer, write a restrained, scannable report covering the verdict, evidence, before/after diagrams, Razor Map, cut/merge list, preserved complexity, risks, guardrails, and next steps. Skip it for a small local audit where HTML adds more ceremony than value, and say why. When one is written, return its absolute path.

Output

Read references/output-template.md before finalizing. The answer must contain, at minimum:

• A razor verdict for the reviewed scope, the stated razor principle used, and an explicit

not-audited scope (to prevent mis-cutting).

• An evidence table, or a clear statement that evidence is missing.
• A classification table mapping each concept to Keep / Merge / Defer / Delete / Replace / Prove

first, with the strongest survival argument for anything cut.

• The complexity that must be preserved.
• A concrete cut list or prove-first list, plus risks and guardrails.

For full audits, also produce the HTML report per Workflow step 9. Before/after Mermaid diagrams are required whenever the recommendation changes a substantial workflow, process, module chain, state machine, service boundary, or architecture flow.

Use a different skill when

• The target is a requirement document or product scope — use hai-prd.
• The target is module boundaries, dependency direction, or abstraction depth — use hai-architecture.
• The question is whether the whole idea is worth doing at all — use hai-idea.
• The user wants the cuts turned into an execution plan — use hai-goal.

Common Mistakes

• Cutting a concept because it is large, not because it is unnecessary.
• Treating "future extensibility" as evidence without naming the expected variation.
• Replacing a visible concept with a hidden convention and calling that simplification.
• Keeping a concept only because it has a name, a file, a meeting, or an owner.

Hai Razor Output Template

Use this template when auditing the existence necessity of requirements, workflow steps, fields, states, modules, abstractions, or any chain. It is the canonical output shape referenced from SKILL.md (Output section); the inline skeleton there is a summary of this. Keep verdicts evidence-led. The verdict vocabulary — Keep / Merge / Defer / Delete / Replace / Prove first — must match the decision table in SKILL.md verbatim. (For a Chinese-led run, see SKILL.zh_CN.md.)

# Hai Razor: <scope>

## Verdict
- **Verdict**: <keep core / merge some / defer some / delete some / replace current shape / prove first>
- **One-line reason**: <the single most important existence-necessity judgment>
- **Razor principle used**: <the bar this audit applied for "deserves to exist">

## Audit Scope
- **Chain / targets**: <PRD, flow, module, field list, state machine, architecture boundary, etc.>
- **Current goal**: <what this chain claims to achieve>
- **Not audited**: <what this pass does not judge, to prevent mis-cutting>

## Evidence
| Source | What was seen | Supports / weakens which verdict | Confidence |
|--------|---------------|----------------------------------|------------|
| <PRD/code/schema/metrics/user flow/tests/logs/interviews/...> | <concrete evidence> | <the keep/delete/merge/defer/replace/prove-first verdict it bears on> | High/Med/Low |

> If evidence is missing, say so directly and downgrade the affected verdict to "Prove first" or "assumption."

## Before / After
<Required when the recommendation changes a substantial workflow, process, module chain, state
machine, service boundary, or architecture flow — a structural cut relocates responsibility, and the
reviewer must see the new owner. A small local audit may omit this with a stated reason.>

### Before

flowchart LR A["existing actors / modules / steps"] --> B["where complexity currently lives"]

### After

flowchart LR A["preserved core responsibility"] --> B["new owner / simplified chain"]

## Razor Map
| Concept | Claimed purpose | What concretely breaks if deleted | Hidden owner | Verdict | Reason |
|---------|-----------------|-----------------------------------|--------------|---------|--------|
| <concept> | <what it claims to solve> | <user goal / invariant / safety / decision / ops impact> | <who absorbs the responsibility> | Keep/Merge/Defer/Delete/Replace/Prove first | <basis for the verdict> |

## To Cut or Merge
| Concept | Action | Strongest survival argument | Why it still falls short |
|---------|--------|-----------------------------|--------------------------|
| <concept> | Delete/Merge/Defer/Replace/Prove first | <strongest case for keeping it> | <why that case does not justify independent existence> |

## Complexity To Preserve
| Concept | Why preserved | Boundary that must not be mis-cut |
|---------|---------------|-----------------------------------|
| <concept> | <which goal, invariant, boundary, or risk it protects> | <where cutting starts to cause damage> |

## Shape After the Razor
<A short paragraph or list describing the smaller model after deletes, merges, or replacements.>

## Risks & Guardrails
- **Likely rebound**: <where future builders are most likely to reintroduce a deleted concept>
- **Mis-cut risk**: <real complexity that might have been deleted by mistake>
- **Guardrails**: <tests, acceptance criteria, naming, docs, architecture boundary, or follow-up proof tasks>

## Next Steps
<If executable, list the cut list; if evidence is thin, list the prove-first items; if it needs landing, route to `hai-goal`.>

## HTML Artifact
- **Path**: `/tmp/hai-razor-<slug>/index.html`
- **When**: required for a full audit; a small local audit may skip it with a stated reason.
- **Contents**: verdict, evidence, before/after diagrams, Razor Map, cut/merge list, preserved complexity, risks, guardrails, next steps.
- **Visual**: restrained, clear, scannable — do not just paste the Markdown into HTML.

Hai Razor 中文版

本文件是中文阅读版；执行规则以 SKILL.md 为准。

概览

审计产品需求、流程步骤、数据字段、状态、模块、层、抽象、服务边界和设计选择是否值得存在，然后把每一个概念分类为保留 / 合并 / 延后 / 删除 / 替代 / 先证明，并附上论据。目标不是把系统做小——一个概念要清过的门槛见“核心原则”。

核心原则

每一个概念都必须证明自己值得存在。

一个东西只有在被删除后会破坏真实目标、抹掉真实区别、遮蔽重要风险，或把不可避免的复杂度转移给更糟糕的承担者时，才配独立存在。如果它只是因为惯性、恐惧、对称感、想象中的未来，或“看起来完整”而存在，就应该被删除、合并、延后，或先要求证据。删掉真实区别、安全、可观测性、权限、迁移路径，或一个隐藏了真实复杂度的深模块，不是简化，是破坏。

可审计对象

任何声称独立存在的东西都可以审计。每种类型的“存在问题”就是它的审视镜头。

给每个概念分类

在做完删除测试和找隐藏承担者（工作流第 4-5 步）之后，给每个概念恰好分配一个判断。

工作流

1. 命名要剃的链路。 明确范围（PRD 段落、功能流、数据模型、模块边界、架构链路或实施计划）、它声称服务的当前目标，并列出所有要求独立存在的概念。

2. 先找论据，再下判断。 阅读和每个概念有关的 PRD、文档、代码、schema、链路追踪、测试、指标、用户流程、支持案例或决策记录。区分证据和推断——如果一个说法合理但没有被证明，就标成假设或“先证明”。优先使用当前行为的具体证据，不要把想象中的未来扩展当成证据。每一个保留 / 删除 / 合并 / 延后 / 替代判断，都必须绑定论据，或明确说明缺少证据。

3. 如果切的是结构性链路，先画当前图。 如果建议会改变较大的工作流、业务流程、模块链路、状态机、服务边界或架构流，就输出落实前/落实后的 Mermaid 对比图——因为结构性删减会悄悄转移责任，评审者需要看到现在由谁承担。落实前图展示现有参与者、模块、步骤、状态/数据流，以及复杂度目前在哪里；落实后图展示哪些东西被删除、合并、延后或移动，剩余责任由谁吸收。只有在小范围局部审计、表格比流程图更清楚时，才可以不画图。

4. 做删除测试。 对每个概念问：如果它消失，具体会坏什么？区分“看起来不完整”和“用户目标、不变量、操作、安全属性或决策真的失败”。如果什么都不会坏，这个概念就是可疑的。

5. 找隐藏承担者。 如果删掉这个概念，谁要吸收它原本的责任？如果责任会转移到更糟的位置，它可能应该保留。如果已有概念能以更低认知成本吸收它，就合并。

6. 给每个概念分类（用上面的判断表）。给每个概念恰好一个判断，并写明理由。

7. 保护必要复杂度。 明确哪些东西不该被砍：那些能阻止非法状态、保护信任边界、支持恢复、改善可观测性，或通过深接口隐藏实现细节的复杂度。

8. 攻击剩余设计。 问未来的人会怎样把被删的概念重新加回来，以及这次删减是否制造隐藏耦合、模糊所有权、迁移风险或不可验收的边界。增加护栏：命名、测试、文档边界、验收标准、架构说明或后续证明任务。

9. 为完整审计生成 HTML 交付物。 路径：/tmp/hai-razor-<slug>/index.html。在 Markdown 答案之后，写一份克制、可扫描的报告，包含结论、论据、落实前/落实后图、Razor Map、删减/合并清单、必须保留的复杂度、风险、护栏和下一步。如果只是很小的局部审计、HTML 比问题本身更重，可以跳过，但要说明为什么。生成了 HTML 时，回复里要给出它的绝对路径。

输出

最终输出前读取 references/output-template.md。答案至少必须包含：

• 对审计范围的剃刀结论、本次使用的切割原则，以及明确的“不审计”范围（避免误切）。
• 论据表，或明确说明当前缺少论据。
• 把每个概念分类为保留 / 合并 / 延后 / 删除 / 替代 / 先证明的表格，并给出每个被砍概念最强的存活理由。
• 必须保留的复杂度。
• 具体的删减清单或先证明清单，以及风险和护栏。

对完整审计，还要按工作流第 9 步产出 HTML 报告。当建议改变较大的工作流、业务流程、模块链路、状态机、服务边界或架构流时，必须给出落实前/落实后的 Mermaid 对比图。

何时改用别的 skill

• 目标是需求文档或产品范围——用 hai-prd。
• 目标是模块边界、依赖方向或抽象深度——用 hai-architecture。
• 问题是整个想法到底值不值得做——用 hai-idea。
• 用户想把删减结果变成执行计划——用 hai-goal。

常见错误

• 因为一个概念大就砍，而不是因为它不必要。
• 把“未来扩展性”当证据，却说不出未来变化族。
• 把显性概念替换成隐性约定，然后称之为简化。
• 仅仅因为它已经有名字、文件、会议或 owner 就保留它。