LUAgam/skills/clarify

Skill: clarify

CLI Bootstrap

在执行任何 harnessctl 命令前，校验环境变量 HARNESSCTL 是否已配置：

test -n "${HARNESSCTL:-}" && test -x "$HARNESSCTL" || {
  echo "ERROR: HARNESSCTL 环境变量未设置或不可执行。请先执行: export HARNESSCTL=/path/to/stage-harness/scripts/harnessctl" >&2
  exit 1
}

Multi-role CLARIFY engine — converts a raw idea into a structured, validated problem statement.

Purpose

Before writing any spec, we must understand the problem deeply. The CLARIFY stage uses a Lead Orchestrator + domain-scout + specialist roles to surface requirements, risks, unknowns, and decisions — while respecting the Interrupt Budget.

domain-scout runs before codebase impact analysis on every epic (no opt-out).

Agent Roles

| Role | Agent | Responsibility | |------|-------|---------------| | Lead | lead-orchestrator | Coordinates flow, owns Decision Bundle | | Domain | domain-scout | Product/domain framing → domain-frame.json (no code reads) | | Scenario | scenario-expander | Expands high-risk semantic signals → generated-scenarios.json | | Analyst | requirement-analyst | Decomposes goals → requirements (consumes domain-frame.json) | | Impact | impact-analyst | Finds affected surfaces + blast radius | | Challenger | challenger | Stress-tests assumptions (consumes domain-frame.json) | | Router | project-surface-router | Maps requirements → codebase surfaces | | Specialist | deep-dive-specialist | Digs into ambiguous areas on demand |

CLARIFY Flow

与 agents/lead-orchestrator.md 对齐：先 Intake，再 Domain Scout，再并行四角色。

Step 1 — Idea Intake

Lead Orchestrator reads:

• Epic description from user
• .harness/project-profile.yaml (risk level, intensity)
• Existing unknowns in unknowns-ledger.json (if resuming)

Output: Structured idea summary with initial assumption list.

Step 1.5 — Source Material Loading（自适应）

Lead 检查 .harness/features/<epic-id>/requirement-index.json 是否存在：

• 存在且 input_density: "rich"：读取 source-materials.md 全文，提取关键需求条目，将其作为后续所有 agent 的显式输入上下文。Lead 在派发 Step 2/3 的每个 agent 时，prompt 中必须包含 source-materials.md 的路径引用或内容摘要。
• 存在且 input_density: "minimal"：跳过本步骤，仅使用 epic description 作为输入。
• 不存在（旧 epic 或手动创建）：跳过本步骤，行为与 minimal 一致。

本步骤零开销适配：对简单口述需求无任何额外动作；对富文档需求则确保原始精度在后续阶段可追溯。

Step 2 — Domain Scout（固定前置，在代码影响扫描之前）

• 调度 domain-scout：仅基于需求文案、project-profile.yaml、可选领域标签（可附带 Step 1 摘要）。
• Lead 必须真的调用 stage-harness:domain-scout agent；不得由 Lead 自己口头代替、不得只做 mkdir 或重复读取画像来冒充 Step 2 完成。
• 产出 .harness/features/<epic-id>/domain-frame.json（结构化，轻量；完整 schema 以 agents/domain-scout.md 为准）。
• Step 0 门禁对齐：顶层须含 business_goals、domain_constraints、semantic_signals、candidate_edge_cases、candidate_open_questions（与 scripts/clarify_gate_shared.py 的 DOMAIN_FRAME_REQUIRED_KEYS 一致）。不得用旧键名（如 domain、subdomain、domain_signals）顶替这些字段。
• Lead 将摘要合并进 clarification-notes.md 的 Domain Frame / 领域框架 章节。
• 若运行时已提供 profile/state 摘要，Lead 不得在 Step 2 前反复做低价值状态探测；拿到最小必要上下文后应立即派发 domain-scout。

Step 2.5 — Project Anchor Read（项目锚定读取，必选）

domain-scout 完成后、Step 3 并行分析之前，Lead 必须读取项目核心文档：

1. 检查 CLAUDE.md 是否引用了项目 README；若有，读取该文件。
2. 否则检查项目根目录是否存在 README.md 或 README；若有，读取该文件。
3. 若均不存在，跳过并标注"项目无 README"。

目的：为 Step 3 各并行 agent 提供项目架构上下文（组件职责、子系统边界、已有能力）。domain-scout 仅推断领域知识，不含项目实际技术架构。

硬约束：1. 仅读取项目级文档（README），不做代码扫描。 2. 读取后提取的关键上下文应附加到 Step 3 各 agent prompt 中。

Step 3 — Parallel Analysis（spawn 4 agents simultaneously）

Launch in parallel:

Agent 1 (requirement-analyst): Description: decompose requirements, Input includes domain-frame.json + source-materials.md (if rich) → requirements-draft.md
Agent 2 (impact-analyst):      Description: map codebase blast radius, Scan codebase surfaces + read project-profile.yaml → `impact-scan.md`；`workspace_mode: multi-repo` 时另写 `cross-repo-impact-index.json`（契约优先、深扫仓数受 `scan.max_repos_deep_scan` 约束）
Agent 3 (challenger):          Description: stress test assumptions, Input includes domain-frame.json + source-materials.md (if rich) → challenge-report.md
Agent 4 (scenario-expander):   Description: expand edge cases, Input includes domain-frame.json + source-materials.md (if rich) → generated-scenarios.json

Source Material 传递规则：当 requirement-index.json 的 input_density 为 rich 时，Agent 1/3/4 的 dispatch prompt 中必须包含 source-materials.md 的文件路径，要求 agent 读取原文并在产出中保留对源文档的精确引用（如 [SRC-001:L42]）。input_density 为 minimal 时不传递该文件。

Wait for all four to complete.

impact-analyst may internally use agent teams / parallel subagents only after a first-pass map and only when 3+ major modules are implicated, risk_level is high, or blast radius already appears broad/systemic. This does not change the outer CLARIFY contract: Step 3 still has four top-level roles, and the Lead waits only for the final consolidated impact-scan.md.

若 primary_surfaces hint 无效，impact-analyst 必须先做有界重定向（顶层浅扫 + 预算内缩圈），而不是退化为全仓宽扫；若预算内仍无法定位，必须显式报告 evidence gap / retarget required。

证据分级要求（适用于所有 Step 3 并行 agent）：所有并行 agent 在产出中涉及组件职责、模块归属、依赖关系、技术能力等事实性声明时，必须区分声明类型：

• FACT：有明确代码路径、文档引用、配置文件或运行证据支持
• INFERENCE：基于多处线索推断，但尚无单一直接证据
• ASSUMPTION：当前未验证，仅用于推动后续澄清

不得将 INFERENCE / ASSUMPTION 写成无标注的断言。涉及后续 Decision Bundle 前提的判断，必须保留 evidence 来源（文件路径、文档章节、代码符号）。

沉淀规则：challenge-report.md 中 Critical / Warnings 级发现须进入 unknowns-ledger.json 或 decision-bundle.json，不得仅停留在报告中。

Step 4 — Semantic Reconciliation（语义归并）

Lead 在路由代码承载面之前，交叉核对 domain-frame.json、generated-scenarios.json、requirements-draft.md、challenge-report.md。语义归并分为两个认知阶段，必须按顺序执行：

阶段 A — Evidence Reconciliation（证据归并）：

• 汇总各并行产物中对同一实体（组件、模块、接口、职责边界）的事实性声明，按 FACT / INFERENCE / ASSUMPTION 分级。
• 识别多份产物之间的冲突声明（如：产物 A 声称组件 X 负责功能 Y，产物 B 声称组件 Z 负责功能 Y）。
• 冲突裁决优先级：FACT > INFERENCE > ASSUMPTION；同级冲突时以项目权威文档（README、架构文档、project-profile.yaml、代码证据）为准。
• 被裁决为错误或未证实的声明，不得作为 Decision Bundle 中 must_confirm 的前提条件。
• 裁决摘要写入 clarification-notes.md 的「语义归并」小节。

阶段 B — Scenario Reconciliation（场景归并）：

合并矛盾语义、将未闭合组合升级为 must_confirm / UNK / DEC，并产出 scenario-coverage.json。generated-scenarios.json 必须使用 canonical scenarios[] 结构，且高/中置信度场景应带 scenario_id、pattern、source_signals、scenario、why_it_matters、expected_followup；scenario-coverage.json 则使用 canonical { epic_id, version, scenarios, signals? }，记录每个 SCN-xxx 的覆盖状态与映射去向，并在需要时通过 signals[] 显式闭合高/中置信度语义信号。clarification-notes.md 中则追加简短 Semantic Reconciliation / 语义归并 小节（可与 Traceability 合并）。

REQ 编号对齐规则：scenario-coverage.json 和 clarification-notes.md 中引用的 REQ 编号必须与 requirements-draft.md 的最终编号一致。若并行 agent 使用了临时编号，Lead 必须在进入 Step 5 前完成对齐。

Step 5 — Surface Routing

• project-surface-router reads requirements-draft.md + impact-scan.md，将 REQ 映射到具体文件 → surface-map.md（按需）。
• Lead 或专用步骤按 skills/project-surface/SKILL.md 生成/更新 surface-routing.json（承载面、repo_id、dive_strategy、scan_budget、evidence_level）；surfaces[] 每项都必须显式包含 type 和 path；输入可含 cross-repo-impact-index.json（multi-repo 时由 impact-analyst 写出，且 full mode 下不应缺失）。
• 若 .harness/project-profile.yaml 声明了可选 coupling_role_ids，Lead 需要为本 epic 判断是否存在需要显式闭环的联动责任；需要时写出 change-coupling-closure.json，并在 surface-routing.json.surfaces[].serves_roles 或 exemptions[].binds_to = DEC-* / UNK-* 中闭环。

Step 6 — Deep Dive (conditional)

If any requirement is rated UNCLEAR or AMBIGUOUS by challenger: → Spawn deep-dive-specialist for that requirement → Update unknowns-ledger.json with new UNK-xxx entries

Step 7 — Decision Bundle Construction

Lead Orchestrator aggregates all findings into Decision Bundle (must_confirm / assumable / deferrable).

Interrupt Budget rules:

• must_confirm decisions → pack into Decision Packet → single user interrupt
• assumable decisions → auto-proceed with proposed_default, log in bundle
• deferrable decisions → defer to SPEC/PLAN stage, add to unknowns-ledger

Budget limits (from project-profile.yaml):

• low risk: max 1 user interrupt
• medium risk: max 2 user interrupts
• high risk: max 3 user interrupts

DEC ↔ UNK 同步规则：同一问题同时出现在 decision-bundle.json（DEC-xxx）和 unknowns-ledger.json（UNK-xxx）时，两条记录必须通过 linked_unk / linked_dec 互相引用，且状态必须一致。Lead 在进入 Step 8 前须验证同步。

Step 7.5 — Source Coverage Audit（源文档覆盖审计，仅 rich 模式）

当 requirement-index.json 的 input_density 为 rich 时，Lead 必须在定稿前验证源文档的每个章节/段落都被至少一个 CLARIFY 产物引用或显式排除。未覆盖的章节为 gap，Lead 须逐条处置（纳入 REQ / 延后到 SPEC / 标记为 non-goal / 记入 unknowns-ledger）。审计结果写入 clarification-notes.md 的 ## Source Coverage Audit 小节。

input_density 为 minimal 或文件不存在时跳过本步骤。

Step 8 — CLARIFY Summary & Gate

Finalize clarification-notes.md（含 Domain Frame、REQ 列表、范围边界等）。

若使用 ## 六轴澄清覆盖，六轴名称必须与 gate canonical 标签一致：StateAndTime / 行为与流程、ConstraintsAndConflict / 规则与边界、CostAndCapacity / 规模与代价、CrossSurfaceConsistency / 多入口、OperationsAndRecovery / 运行与维护、SecurityAndIsolation / 权限与隔离。不要改写成项目定制标签。

User focus points（通用，非项目定制）：若用户在对话中点名了必须单独验收的关注点，在笔记中增加 ## Focus Points（或 ## 用户关注点 / ## 用户点名关注），每条一行且行内必须出现 REQ- / CHK- / SCN- / DEC- / UNK- 之一；或使用可选 focus-points.json（items[].maps_to 等字段指向上述编号）。未点名则不要添加空壳小节；一旦添加，stage-gate check CLARIFY 会校验闭环。

Full 模式下的场景驱动 Focus（与 clarify_gate_shared 信号一致）：当 closure 模式为 full 时，对 generated-scenarios.json 中 high 置信度、在 scenario-coverage.json 中已登记且非 dropped_invalid 的 SCN-xxx，若文本命中 StateAndTime 或 ConstraintsAndConflict 相关信号，必须在 Focus 小节或 focus-points.json（maps_to / closure_ref / mapped_to / trace）中显式出现该 SCN 编号。notes_only 不应用此规则。

当 conflict / retry / rewrite / amplification / performance / capacity 语义出现时，Lead 还应把对应的代价/性能风险沉淀到 CostAndCapacity / 规模与代价 轴，并闭合到 SCN / REQ / DEC / UNK，而不是仅停留在 prose。

Before proceeding to SPEC:

• $HARNESSCTL stage-gate check CLARIFY --epic-id <epic-id> 必须通过（含 domain-frame.json、challenge-report.md、笔记中的 Domain Frame 标题）
• All must_confirm decisions resolved (via Decision Packet)
• No BLOCKED items without mitigation

Outputs

所有文件路径均为 .harness/features/<epic-id>/：

| File | 生成方式 | Description | |------|---------|-------------| | domain-frame.json | domain-scout | 领域框架结构化草稿（Step 2） | | generated-scenarios.json | scenario-expander | 基于 domain-frame 的高风险场景展开结果 | | requirements-draft.md | requirement-analyst | 需求草案 | | impact-scan.md | impact-analyst | 影响面扫描 | | cross-repo-impact-index.json | impact-analyst | multi-repo 时：契约优先的仓级影响索引（必需；单仓可缺省） | | surface-routing.json | Lead / project-surface 流程 | 承载面路由与扫描预算（与 surface-map.md 配合） | | change-coupling-closure.json | Lead（可选） | 项目已声明 coupling_role_ids 时，用于记录本 epic 的 required_role_ids 与 exemptions；未启用 taxonomy 时可缺省 | | challenge-report.md | challenger | 挑战报告（须含 ## Summary） | | scenario-coverage.json | Lead 汇总 | SCN-xxx 到 REQ/CHK/DEC/UNK 的结构化映射 | | surface-map.md | project-surface-router | 需求→代码路由（若执行路由步骤） | | clarification-notes.md | Lead 汇总 | 澄清笔记（须含 ## Domain Frame 或 ## 领域框架；须含 ## Deferred to SPEC 小节；input_density=rich 时须含 ## Source Coverage Audit） | | unknowns-ledger.json | unknowns-ledger-update.sh init/add | 未知问题台账 | | decision-bundle.json | decision-bundle.sh generate/add | 全量决策分类 | | decision-packet.json | decision-bundle.sh packet | must_confirm 打包 | | focus-points.json | Lead / 用户关注点归档（可选） | 用户点名关注点 → REQ/CHK/SCN/DEC/UNK 的结构化映射；与笔记中 Focus Points 小节二选一或并存 |

interrupt-budget.json 不再作为独立产物文件，预算状态通过 $HARNESSCTL budget check 从 state.json 读取。

Usage

Invoke skill: clarify
Epic: <epic-name>
Risk level: medium
Input: <user's raw idea>