---
name: user-feedback-contract
scope:
  - '*'
products:
  - '*'
id: ka-hard-rule-用户反馈契约规则
asset_kind: governance_rule
lifecycle_status: active
authority: canonical
owner_mechanism_id: mc-user-feedback
routes: ['*']
primary_triggers:
  - 用户反馈契约规则
  - 用户反馈
  - 实际使用反馈
  - 问题反馈
  - 机制缺口
  - 设计缺陷
secondary_triggers:
  - 全局抽象
  - 系统性问题
  - 机制族归因
  - 用户项目路径
  - 防回归
negative_triggers: []
priority: P0
specificity: 5
consumes:
  - mc-task-context-lifecycle
  - mc-first-principles
  - mc-detail-discipline
  - mc-evolution-regression
hard_blocks:
  - 反馈未响应
  - 阻塞性信息未展示
  - 仅按表面文件或单个场景收窄处理
  - 未做机制族归因
  - 未分析 SoloForge 自身与用户项目双路径影响
  - 未分析模版层、知识层、机制层、adapter、CLI、MCP、发布门禁、迁移和防回归影响
fallback: manual_required
required_evidence:
  - user_feedback_message
  - global_abstraction_review
  - mechanism_family_mapping
  - cross_layer_impact_matrix
version: 1.1.0
last_reviewed: '2026-06-01'
type: governance_rule
when: 用户反馈契约规则
stages: ["*"]
---

# 用户反馈契约规则

## 核心约束

1. 每个工具只能输出其 `getAllowedFeedbackKinds` 允许的反馈类型。
2. 反馈消息必须包含：kind、severity、title、summary。禁止空洞反馈。
3. 技术内容（路径、命令、错误码）禁止翻译，必须保留原文。
4. `blocked` 类型反馈必须包含阻塞原因和建议下一步。
5. `failure` 类型反馈必须包含失败证据和 retry_hint。
6. 任何用户反馈、缺陷、设计疑问或实际使用偏差，不得只按表面文件、单个目录或单个场景收窄处理。
7. 进入修复讨论前，必须先完成全局抽象审查：
   - 该问题属于哪个机制族？
   - 是否只是某个现象暴露出来的系统性问题？
   - 是否同时影响 SoloForge 自身与用户项目使用路径？
   - 是否涉及模版层、知识层、机制层、adapter、CLI、MCP、发布门禁、迁移和防回归？
   - 是否需要抽象成通用能力，而不是只修当前案例？
8. 如果全局抽象审查未完成，只能输出待分析项、影响矩阵和建议讨论顺序，不得直接给单点修复结论。
9. 如果当前案例只是系统性问题的一个样本，修复方案必须覆盖同类入口、同类资产、同类任务和新增资产防回归。

## 适用场景

- 所有 SoloForge 工具的输出反馈
- sf_verify 结果反馈
- sf_learn 学习反馈
- sf_expand 降级/澄清反馈
- 用户反馈实际使用问题
- 讨论新增机制、模版、规则、流程、验收或发布风险
- 将问题落入 Batch、备忘录、发布门槛或施工合同前

## 违规处理

- 禁止的反馈类型 → hard_fail，阻断输出
- 空洞反馈 → advisory，标记质量降级
- 翻译技术内容 → advisory，标记违规
- 未做全局抽象审查就收窄为单点修复 → hard_fail，退回机制族归因
- 只修当前文件/目录/样例但未覆盖同类路径和防回归 → hard_fail，要求补齐通用能力
- 未分析 SoloForge 自身与用户项目双路径影响 → hard_fail，要求补齐影响矩阵
- 未说明模版层、知识层、机制层、adapter、CLI、MCP、发布门禁、迁移和防回归影响 → hard_fail，要求补齐跨层影响

## 全局抽象审查输出

每次用户反馈进入讨论或施工合同前，必须形成以下结构化结论：

```text
1. 表面现象:
2. 机制族归因:
3. 是否系统性问题:
4. SoloForge 自身影响:
5. 用户项目影响:
6. 涉及层级:
   - 模版层:
   - 知识层:
   - 机制层:
   - adapter:
   - CLI:
   - MCP:
   - 发布门禁:
   - 迁移:
   - 防回归:
7. 是否应抽象成通用能力:
8. 不应只修的局部案例:
9. 施工和验收必须覆盖的同类路径:
```
