@mstar-harness/opencode 1.8.0 → 1.8.2

package/harness-skills/mstar-coding-behavior/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mstar-coding-behavior
-description: Morning Star (启明星) 跨角色通用编码行为准则 —— Think Before Coding（先读懂再改、显式假设、不静默猜测、读 imports/test/项目模式）、Simplicity First（YAGNI 优先不写代码、The Ladder 决策层级含依赖评估、删除优于添加、简洁优于聪明、5 项具名反模式速查、`simplify:` 标记天花板与升级路径、最小耐久切片）、Surgical Changes（改动可追溯、Bug 修根因先 grep 所有调用点、不顺手重构、不 piggyback）、Debugging（读完整报错与栈追踪、先复现、一步一测、根因分析、Bug 修复前先写复现测试、卡住时坦白）、Review Feedback Handling（先核实反馈再改、逐项处理、可用证据反驳错误建议）、Goal-Driven Execution（非平凡逻辑必留一个可运行检查、模糊请求转可验证结果、测行为不测实现、已有测试前后对比、不能测试说理由、Step → verify 微模板、分批留 roadmap）、Communication（说做了什么及为什么、标记顾虑、精确表达不确定性、不解释已知的、commit message 质量）。任何实现、调试、重构、审查任务都应优先 Read 本 skill；`@fullstack-dev` / `@frontend-dev` / `@fullstack-dev-2` / `@architect` / `@qa-engineer` / `@ops-engineer` / `@prompt-engineer` 动手前必读；QC 审查员核对变更是否只做了该做的手术时必读。本 skill 不覆盖分支门禁、QC/QA 路由、Assignment 权限、Done 所有权等不变量（那些以 `mstar-harness-core` 为准）。
+description: Morning Star 跨角色通用编码行为准则 —— 任何实现、调试、重构、审查任务动手前必读。约束 Think Before Coding（先读懂再改、显式假设、不静默猜测）、Simplicity First（YAGNI、The Ladder、`simplify:` 标记、最小耐久切片）、Surgical Changes（改动可追溯、Bug 修根因先 grep 所有调用点、不 piggyback）、Debugging（先复现、一步一测、修前写复现测试）、Review Feedback Handling（先核实再改、证据反驳）、Goal-Driven Execution（非平凡逻辑留可运行检查、Step→verify）、Communication。`@fullstack-dev*` / `@frontend-dev` / `@architect` / `@qa-engineer` / `@ops-engineer` / `@prompt-engineer` 必读；QC 核对手术范围时必读。不覆盖分支门禁、QC/QA 路由、Assignment 权限。
 ---
 
 ## Load order（必读顺序）
@@ -9,55 +9,29 @@ description: Morning Star (启明星) 跨角色通用编码行为准则 —— T
 
 **摘要**：`mstar-harness-core` — 不变量与门禁；本 skill — 实现与审查时的工程习惯，不替代 harness。
 
-# Morning Star Coding Behavior Guidelines
-
-This skill captures lightweight, host-agnostic coding behavior principles that reduce common agent mistakes. It complements the other Morning Star skills and does not override stage gates or role routing.
-
-Priority remains (同 `mstar-harness-core` SKILL.md「信息源优先级」):
+Priority remains（同 `mstar-harness-core`「信息源优先级」）：① 当轮用户显式指令 ② 项目 `AGENTS.md` / `CLAUDE.md` ③ `mstar-harness-core` ④ 其它 `mstar-*`（含本 skill）⑤ `mstar-roles` 角色正文。
 
-1. User explicit instruction
-2. Project `AGENTS.md` / `CLAUDE.md`
-3. `mstar-harness-core` skill（global entry & SSOT）
-4. Other `mstar-*` skills（含本 skill）
-5. Role prompts in `mstar-roles` skill
+**Scope**：适用于非平凡编码/调试/重构/审查任务；trivial one-liner 用判断、保持低开销。定义执行行为，不定义分支策略或门禁所有权。
 
-## Scope
+# Morning Star Coding Behavior Guidelines
 
-- Applies to non-trivial coding, debugging, refactoring, and review tasks.
-- For trivial one-liners, use judgment and keep overhead minimal.
-- This skill defines execution behavior, not branch policy or gate ownership.
+Lightweight, host-agnostic coding-behavior principles that reduce common agent mistakes. Complements other Morning Star skills; does not override stage gates or role routing.
 
 ## 1) Think Before Coding
 
-Core idea: do not silently choose an interpretation when ambiguity exists.
-
-- State assumptions explicitly before implementation when uncertainty is material.
-- If there are multiple plausible interpretations, present options and ask for confirmation.
-- Surface key tradeoffs when they affect scope, risk, or maintainability.
-- If critical context is missing, pause and clarify instead of guessing.
+Do not silently choose an interpretation when ambiguity exists. State assumptions explicitly when material; if multiple plausible interpretations exist, present options and ask. Surface tradeoffs affecting scope/risk/maintainability. If critical context is missing, pause and clarify instead of guessing.
 
-Quick check:
-
-- Can another reviewer see what assumptions were made?
-- If assumptions are wrong, will the user detect it before large edits happen?
+Quick check: can another reviewer see the assumptions made? If assumptions are wrong, will the user detect it before large edits happen?
 
 **Never lazy about understanding.** Shorten the solution, never the reading. Read the task and every file the change touches fully first; trace the actual flow end to end. A small diff in the wrong place is not efficiency — it is a second bug shipped with confidence.
 
-**Read before you write.** Before generating code in an existing project:
-
-- Inspect the imports at the top of each file you are about to modify. They tell you which libraries the project actually uses — do not introduce a different library for the same purpose.
-- Look at nearby test files. They document expected behavior more precisely than comments or your own assumptions.
-- Follow existing project patterns. If there is a convention for API routes, file structure, or error handling, match it. Do not silently introduce a different pattern.
-- If you cannot find a precedent for something, say so. "I do not see a pattern for X in the codebase — should I follow approach Y?" is always better than guessing.
-- If you are not 100% sure a method signature or parameter exists, check the actual source code or docs before using it. Confidently calling a non-existent API is one of the costliest agent mistakes — it may compile, then fail at runtime.
+**Read before you write.** Before generating code in an existing project: inspect imports (which libraries the project actually uses — do not introduce a different library for the same purpose); look at nearby tests (they document expected behavior more precisely than comments); follow existing patterns (API routes, file structure, error handling — match it, do not silently introduce a different one). If no precedent exists, say so and ask. If not 100% sure a signature/parameter exists, check source/docs before using it — confidently calling a non-existent API may compile then fail at runtime.
 
-The failure mode: you generate "correct" code that is alien to the codebase it lives in. It works but looks like a different person wrote it. The human then has to either rewrite it to match or live with inconsistency forever.
+The failure mode: "correct" code that is alien to the codebase — works but looks like a different person wrote it, forcing a rewrite or permanent inconsistency.
 
 ## 2) Simplicity First
 
-Core idea: implement the smallest durable slice that satisfies the request and acceptance criteria.
-
-**Question the need (YAGNI).** Before writing code, ask: does this task need code at all? Can the goal be achieved by deletion, reusing existing logic, or a configuration change? If a path requires no code, take it and explain in one line.
+Implement the smallest durable slice that satisfies the request and acceptance criteria.
 
 **The Ladder.** A reflex hierarchy for every decision — stop at the first rung that holds:
 
@@ -65,20 +39,15 @@ Core idea: implement the smallest durable slice that satisfies the request and a
 2. **Already in this codebase?** A helper, util, type, or pattern that already lives here → reuse it. Look before you write.
 3. **Stdlib / built-in covers it?** Use it.
 4. **Native platform feature covers it?** CSS over JS, DB constraint over app code, OS primitive over a library.
-5. **Already-installed dependency solves it?** Use it. Never add a new dependency for what a few lines of code can do. When a new dependency appears necessary, evaluate: (a) can this be done with what is already in the project? (b) can the standard library do it? (c) is the package maintained (check last commit date and issue tracker) and reasonably sized? If you add it, state why in one sentence — silently adding packages is not acceptable.
+5. **Already-installed dependency solves it?** Use it. Never add a new dependency for what a few lines can do. When a new dependency appears necessary, evaluate: (a) can this be done with what is already in the project? (b) can the standard library do it? (c) is the package maintained (check last commit date and issue tracker) and reasonably sized? If you add it, state why in one sentence — silently adding packages is not acceptable.
 6. **Can it be one line?** One line.
 7. **Only then:** the minimum durable code that works.
 
-The ladder runs after understanding, not instead of it. Two rungs work → take the higher one and move on.
+The ladder runs after understanding, not instead of it. Two rungs work → take the higher one.
 
-**Deletion over addition. Boring over clever.** Removing unnecessary code is a feature. Cleverness is what someone decodes at 3am — prefer a boring, obvious solution that a tired reviewer can verify in seconds.
+**Deletion over addition. Boring over clever.** Removing unnecessary code is a feature; cleverness is what someone decodes at 3am — prefer a boring, obvious solution a tired reviewer verifies in seconds. Do not add unrequested features/flags/configurability; avoid new abstractions for single-use logic; prefer straightforward local fixes over framework-level reshaping **only when they fit the target design**; reject speculative error handling for impossible paths unless required by project policy.
 
-- Do not add features, flags, or configurability that were not requested.
-- Avoid introducing new abstractions for single-use logic.
-- Prefer straightforward local fixes over framework-level reshaping **only when they fit the target design**.
-- Reject speculative error handling for impossible paths unless required by project policy.
-
-**Simplification markers.** When a deliberate shortcut has a known ceiling (global lock, O(n²) scan, naive heuristic), mark it with a `simplify:` comment that names the ceiling and the upgrade path:
+**Simplification markers.** When a deliberate shortcut has a known ceiling (global lock, O(n²) scan, naive heuristic), mark it with a `simplify:` comment naming the ceiling and the upgrade path:
 
 ```text
 // simplify: global lock on cache misses. Replace with per-key lock if throughput matters.
@@ -87,66 +56,43 @@ The ladder runs after understanding, not instead of it. Two rungs work → take
 This signals intent — the simplicity is deliberate, not an oversight — and gives the next person the upgrade path without research.
 
 - Do not confuse "minimum" with "temporary." A small implementation must still align with the long-term target state, stable interfaces, and known follow-up plan.
-- If a workaround is unavoidable, label it as `simplify:` / `temporary`, explain why, and record the removal path in the plan/status artifact before claiming the task is complete.
+- If a workaround is unavoidable, label it `simplify:` / `temporary`, explain why, and record the removal path in the plan/status artifact before claiming the task complete.
 
 **Simplicity anti-patterns — stop and reconsider when you spot these:**
 
 | Anti-pattern | Signal |
 |---|---|
-| **Premature abstraction** | You are writing a class / interface / strategy pattern where a single function suffices. |
-| **Speculative error handling** | You are wrapping code in try/catch for errors that cannot happen. |
-| **Unnecessary configurability** | You are making a value configurable (env var, parameter) that will never change. Hardcode it until there is a real reason not to. |
-| **Dead flexibility** | You have an interface with one implementation, or a generic type with one instantiation — cost with zero benefit until a second use exists. |
-| **"In case we need to"** | Your justification for abstraction includes a guess about future requirements. "In case we need to" is not a requirement — it is a guess, and guesses about the future are usually wrong. |
-
-Default rule:
+| **Premature abstraction** | Writing a class/interface/strategy where a single function suffices. |
+| **Speculative error handling** | Wrapping code in try/catch for errors that cannot happen. |
+| **Unnecessary configurability** | Making a value configurable (env var, parameter) that will never change. Hardcode it until there is a real reason not to. |
+| **Dead flexibility** | An interface with one implementation, or a generic type with one instantiation — cost with zero benefit until a second use exists. |
+| **"In case we need to"** | Justification for abstraction includes a guess about future requirements. "In case we need to" is a guess, and guesses about the future are usually wrong. |
 
-- If 200 lines can be 50 with the same behavior, clarity, and durable architecture, prefer the smaller solution.
-
-Durability check:
-
-- Can this slice be extended by the next batch without undoing its core shape?
-- Are deferred items captured in an existing roadmap / task board / residual tracker, not just mentioned in chat?
-- Would a reviewer understand whether this is the final approach, a staged slice, or a deliberate simplification?
+**Durability check**: can this slice be extended by the next batch without undoing its core shape? Are deferred items captured in an existing roadmap/task board/residual tracker (not just chat)? Would a reviewer understand whether this is the final approach, a staged slice, or a deliberate simplification?
 
 ## 3) Surgical Changes
 
-Core idea: every changed line should be traceable to the task.
-
-- Touch only files and regions needed for the requested outcome.
-- Do not opportunistically refactor adjacent code.
-- Match existing style and patterns unless a change is explicitly requested.
-- Remove only artifacts made unused by your own change.
-- If unrelated issues are found, report them separately instead of piggyback editing.
+Every changed line should be traceable to the task. Touch only files/regions needed for the requested outcome; do not opportunistically refactor adjacent code; match existing style unless a change is explicitly requested; remove only artifacts made unused by your own change; report unrelated issues separately instead of piggyback editing.
 
-Traceability test:
-
-- Each hunk should map to a user requirement, acceptance criterion, or required fix-up.
+**Traceability test**: each hunk maps to a user requirement, acceptance criterion, or required fix-up.
 
 **Bug fix = root cause, not symptom.** A bug report names a symptom, not the cause. Before editing, grep every caller of the function or code path you are about to touch. The fix belongs where all callers route through — one guard in the shared function is smaller than a guard in every caller. Patching only the path the ticket names leaves every sibling caller still broken. Fix it once, at the narrowest shared point.
 
 ## 4) Debugging
 
-Core idea: when something does not work, investigate. Do not guess.
+When something does not work, investigate; do not guess.
 
-- **Read the error message entirely** — including the full stack trace. A `TypeError` can mean a hundred different things; the message and trace tell you which one.
-- **Reproduce before fixing.** If you cannot reproduce the problem, you cannot verify your fix. "I think this should fix it" is gambling, not debugging.
-- **Change one thing at a time.** Changing three things and seeing the bug disappear tells you nothing about which change fixed it — or what new bugs the other two introduced. Change one, test, change the next, test.
-- **Fix the root cause, not the symptom.** If a value is unexpectedly null, do not just add a null check and move on. Figure out why it is null. The null check might prevent a crash, but the underlying bug will manifest differently later. Before patching, grep every caller of the affected code path and fix at the narrowest shared point (see Surgical Changes · Bug fix = root cause).
-- **Write a reproduction test before fixing a bug.** Before changing any code, write a minimal test that reproduces the reported behavior. Run it — watch it fail. Then apply the fix. Run it — watch it pass. This is the only way to prove you fixed the actual problem and did not merely suppress symptoms.
-- **Run existing tests before and after your changes.** If tests passed before and fail after, you broke something. If tests were already failing before, say so — do not let your changes get blamed for pre-existing failures.
-- **If you are stuck, say so.** "I have tried X and Y and neither worked. Here is what I am seeing. I think the issue might be Z but I am not sure." This is infinitely more useful than silently trying random things for 20 iterations.
+- **Read the error message entirely**, including the full stack trace — a `TypeError` can mean a hundred things; the message and trace tell you which one.
+- **Reproduce before fixing.** If you cannot reproduce, you cannot verify. "I think this should fix it" is gambling.
+- **Change one thing at a time.** Changing three things and seeing the bug disappear tells you nothing about which change fixed it — or what new bugs the other two introduced.
+- **Fix the root cause, not the symptom.** If a value is unexpectedly null, do not just add a null check — figure out why it is null (see Surgical Changes · bug=root-cause).
+- **Write a reproduction test before fixing a bug.** Minimal test reproducing the reported behavior → watch it fail → apply fix → watch it pass. The only way to prove you fixed the actual problem, not merely suppressed symptoms.
+- **Run existing tests before and after changes.** If they passed before and fail after, you broke something. If they were already failing, say so.
+- **If stuck, say so.** "I tried X and Y; neither worked. I'm seeing Z. I think it might be W but am not sure" is infinitely more useful than silently trying random things for 20 iterations.
 
 ## 5) Goal-Driven Execution
 
-Core idea: convert vague requests into verifiable outcomes and iterate until verified.
-
-- Define concrete success criteria before major edits.
-- For multi-step tasks, use brief `Step -> verify` checkpoints.
-- For split delivery, maintain a durable roadmap: current slice, later slices, dependencies, owner/trigger, and completion condition.
-- Prefer evidence-backed completion claims (tests, command output, reproducible checks).
-- If verification fails, loop on diagnosis and fix before declaring completion.
-- Do not finish with "next plan / later / follow-up" only in prose. If the work is not fully complete, the remaining work must be written to the plan/status artifact or the task must report `Partial` / `Blocked`.
+Convert vague requests into verifiable outcomes and iterate until verified. Define concrete success criteria before major edits; use brief `Step -> verify` checkpoints for multi-step tasks; for split delivery, maintain a durable roadmap (current slice, later slices, dependencies, owner/trigger, completion condition); prefer evidence-backed completion (tests, command output, reproducible checks). If verification fails, loop on diagnosis and fix before declaring completion. Do not finish with "next plan / later / follow-up" only in prose — remaining work must be written to the plan/status artifact or the task reports `Partial` / `Blocked`.
 
 **Minimal check for non-trivial logic.** Any non-trivial change (a branch, a loop, a parser, a data transformation, a money or security path) must leave behind ONE runnable check — the smallest thing that fails if the logic breaks. An inline self-check, a quick `assert`-based demo, or one minimal test. No frameworks, no fixtures, no per-function suites unless asked. Trivial one-liners need none — YAGNI applies to tests too.
 
@@ -157,27 +103,13 @@ Micro template:
    Verify: [specific check]
 2. [Step]
    Verify: [specific check]
-3. [Step]
-   Verify: [specific check]
 ```
 
-**Verification discipline:**
-
-- **Test behavior, not implementation.** A test that checks whether a constructor sets properties is worthless. A test that checks whether validation actually rejects bad input is valuable. Focus on the interesting cases.
-- **If you cannot write a test, say why.** "I cannot easily test this because the database calls are tightly coupled to the business logic" is useful information that may signal a need for restructuring. Do not skip testing without an explanation.
+**Verification discipline**: test behavior, not implementation (a test checking whether a constructor sets properties is worthless; one checking whether validation rejects bad input is valuable — focus on interesting cases). If you cannot write a test, say why ("I cannot easily test this because the database calls are tightly coupled to the business logic" may signal a need for restructuring — do not skip testing without an explanation).
 
 ## 6) Review Feedback Handling
 
-Core idea: review feedback is technical input, not an order to perform unverified edits.
-
-When receiving code review, QA, CI, or human feedback:
-
-1. Read all feedback before editing.
-2. Clarify ambiguous items before partial implementation.
-3. Verify each suggestion against codebase reality.
-4. Apply technically correct feedback one item at a time.
-5. Test each fix individually where practical.
-6. Push back with evidence when feedback is incorrect, obsolete, risky, out of scope, or violates YAGNI.
+Review feedback is technical input, not an order to perform unverified edits. When receiving code review, QA, CI, or human feedback: read all feedback before editing; clarify ambiguous items before partial implementation; verify each suggestion against codebase reality; apply technically correct feedback one item at a time; test each fix individually where practical; push back with evidence when feedback is incorrect, obsolete, risky, out of scope, or violates YAGNI.
 
 Feedback priority:
 
@@ -192,22 +124,16 @@ Do not perform agreement. State the technical action, the verification result, o
 
 ## 7) Communication
 
-Core idea: how you communicate about code matters as much as the code itself.
-
-- **Say what you did and why.** Do not just dump a code block. "I moved the validation into a separate function because it was duplicated in three places and this makes it testable independently" — now the reviewer understands the change without reading every line.
-- **Flag concerns proactively.** If you implemented what was asked but see a problem, say so. "This works but it makes a database call per item — if the list grows large this will be slow. Want me to batch it?" saves hours later.
-- **Be precise about uncertainty.** "I am not sure if this library supports streaming responses" is useful. "I think this should work" is not. Tell the reviewer exactly what to verify.
-- **Match your explanation to context.** If they asked for a REST endpoint, do not explain what REST is. If they asked for a database index, do not explain what indexes do.
-- **Write specific commit messages.** "Fix bug" is useless. "Fix null pointer in user lookup when email contains uppercase chars" tells the next person exactly what happened.
+- **Say what you did and why** — not just a code dump ("moved validation into a separate function because it was duplicated in three places and this makes it testable independently").
+- **Flag concerns proactively** ("this works but makes a DB call per item — if the list grows large this will be slow; want me to batch it?").
+- **Be precise about uncertainty** ("I'm not sure if this library supports streaming responses" is useful; "I think this should work" is not — tell the reviewer exactly what to verify).
+- **Match explanation to context** — do not explain REST to someone who asked for a REST endpoint, or indexes to someone who asked for an index.
+- **Write specific commit messages** — "Fix null pointer in user lookup when email contains uppercase chars", not "Fix bug".
 
 ## Integration Notes
 
 - **SDD implementer reports** (`mstar-sdd`): completion evidence must include TDD triple — test file(s), command, output — in `task-N-report.md`; fix rounds add the same for new/changed tests.
-- This skill must not be used to bypass:
-  - branch constraints,
-  - QC/QA gate definitions,
-  - assignment authority,
-  - `Done` ownership rules.
+- This skill must not be used to bypass branch constraints, QC/QA gate definitions, assignment authority, or `Done` ownership rules.
 
 ## Anti-Bloat Rule for Prompt Maintenance
 

package/harness-skills/mstar-compound/SKILL.md

@@ -21,249 +21,77 @@ Knowledge that isn't captured evaporates when the session ends. Knowledge that i
 
 **SSOT**: `mstar-plan-conventions/references/artifact-storage-paths.md`。本 skill 不重定义路径；知识文档 → `{HARNESS_DIR}/knowledge/<category>/<slug>.md`，CONCEPTS.md → `<repo-root>/CONCEPTS.md`。`<category>` 取值见 `references/category-mapping.md`。
 
-## 是否值得结晶（自检清单 · 必须逐条回答）
+## 是否值得结晶（自检门禁）
 
-在调用本 skill 前，PM（或触发方）**必须**逐条回答以下问题。得分仅用于辅助决策，不替代判断。
+调用本 skill 前，PM（或触发方）**必须**对候选问题逐条自检 Q1–Q8（诊断耗时 / 非显而易见性 / 可复用性 / 项目特异性 / 既有重叠 / 架构影响 / 失败尝试价值 / 跨模块）。完整问题表、决策矩阵（Yes≥4 强烈建议；Yes=3 Lightweight；Yes≤2 跳过；Q5=Yes 高重叠不新建）与示例判定 → **`references/compound-workflow.md`**「是否值得结晶」。
 
-### 自检问题（每条回答 Yes / No / Not sure）
-
-| # | 问题 | 说明 |
-|---|------|------|
-| Q1 | 这个问题的诊断过程耗时是否 ≥ 15 分钟（或 ≥ 3 次尝试）？ | 若只是 1-2 次尝试就找到答案，可能太琐碎 |
-| Q2 | 解决方案是否涉及**非显而易见**的知识（隐含假设、框架行为、workaround）？ | 显而易见的知识无需文档化（如"少了个分号"） |
-| Q3 | 同一个开发者在未来遇到类似问题时，是否可能**再次花费相似的时间**来诊断？ | 核心问题：知识能否复用？ |
-| Q4 | 问题的**根因**是否是项目特定的（不是通用语言/框架问题）？ | 通用问题可搜索到，项目特定问题必须自己记录 |
-| Q5 | `{KNOWLEDGE_DIR}` 中是否**已有**与此高度重叠的文档？ | 若有 → 更新已有文档，不新建（见 Phase 2 重叠检测） |
-| Q6 | 此解决方案是否可能**引导未来架构决策**或成为约定？ | Knowledge track 的典型触发条件 |
-| Q7 | 此解决方案中的"**什么没起作用**"部分是否有价值？ | 失败的尝试往往是最有教学价值的部分 |
-| Q8 | 问题是否涉及** ≥ 2 个模块/组件**的交互？ | 跨模块问题最难排查，最值得记录 |
-
-### 决策矩阵
-
-| 得分 | 行动 |
-|------|------|
-| **Yes ≥ 4**（含 Q5=No） | **强烈建议结晶**。执行完整 Phase 1-7。 |
-| **Yes = 3** | **建议结晶**。使用 Lightweight 模式（Phase 1 单遍）。 |
-| **Yes ≤ 2** | **跳过**。在 conversation/Completion Report 中注明"跳过结晶（<简述原因>）"。 |
-| **Q5 = Yes（高重叠）** | 无论其它得分如何，**不要新建**。执行 Phase 2 重叠检测，更新已有文档即可。 |
-| **任一 Not sure** | 倾向于回答者的默认判断。若 Q1-Q4 有 ≥ 2 个 Yes，仍建议结晶。 |
-
-### 示例判定
-
-```
-Q1: Yes — debug 了 40 分钟
-Q2: Yes — ActiveRecord 的 counter_cache 在 after_destroy 回调中的时序问题
-Q3: Yes — 下次遇到类似时序问题仍会踩坑
-Q4: Yes — 是项目特有 model 结构导致的
-Q5: No  — grep 了 knowledge/ 无匹配
-Q6: No  — 纯 bug 修复
-Q7: Yes — 第一次尝试了手动更新 counter 导致数据不一致
-Q8: No  — 只涉及一个 model
-→ Yes = 5 → 强烈建议结晶（Bug track）
-```
+**快判**：Q5 高重叠 → 更新已有文档，**不新建**；其余按决策矩阵 Yes 数。
 
 ## Integration with mstar lifecycle
 
-Compound 在迭代收口时触发（`mstar-iteration` § iteration-close），不在 per-plan Done 后单独执行：
-
-```
-iteration-start → [plan lifecycle × N: specify→...→Done] → iteration-close
-                                                                  │
-                                                             mstar-compound
-                                                             (per-iteration round)
-                                                                  │
-                                                             {KNOWLEDGE_DIR}
-                                                                  │
-                                               feeds back into next iteration's specify / plan
-```
-
-迭代内所有 plan Done 后，PM 回顾整轮迭代中产生的可结晶知识，批量 compound。per-plan Done 是 per-plan 的闭环终点；compound 是迭代级收口活动。
+Compound 在迭代收口时触发（`mstar-iteration` § iteration-close），不在 per-plan Done 后单独执行：`iteration-start → [plan lifecycle × N] → iteration-close → mstar-compound（per-iteration round）→ {KNOWLEDGE_DIR} → feeds next iteration's specify/plan`。迭代内所有 plan Done 后，PM 回顾整轮迭代可结晶知识，批量 compound。per-plan Done 是 per-plan 闭环终点；compound 是迭代级收口活动。
 
 ### Iteration package promotion（iteration-close 强制盘点）
 
-正式迭代收口时，compound **除** plan 实现/debug/review 素材外，**必须**盘点当前迭代的 package：
+正式迭代收口时，compound **除** plan 实现/debug/review 素材外，**必须**盘点当前迭代 package。
 
 **路径**：`{ITERATION_DIR}/<iteration-id>/**`（含 `guides/`、`specs/`、扁平 `.md`；**默认排除** `delivery-compass.md` 除非 PM 显式纳入。Legacy 根目录 `*-delivery-compass.md` 同理排除）。
 
 | 步骤 | 动作 |
 |------|------|
-| 1. Inventory | 列出 package 下全部 `.md`（除默认排除的 compass）；读各文件 + package `README.md`（若有） |
+| 1. Inventory | 列出 package 下全部 `.md`（除默认排除 compass）；读各文件 + package `README.md`（若有） |
 | 2. Triage | 每篇：**Promote** / **Keep snapshot** / **Skip**（理由写入 compound 摘要） |
 | 3. Promote | 值得跨迭代复用 → 走 Q1–Q8（或轻量判定）→ Phase 2 重叠检测 → Phase 3–6 **结构化重写**进 `{KNOWLEDGE_DIR}/`（**禁止**无改写整文件复制） |
 | 4. Trace | 源文件顶栏或 package README：`Promoted to: <knowledge-path>`；`{KNOWLEDGE_DIR}/README.md` 的 Source 可记 `iteration:<iteration-id>/<relpath>` |
 | 5. Summary | PM 写入 compass `## Compound Round Summary`：提升篇数、保留快照、跳过及原因 |
 
-**Promote 典型**：迭代 spec 已验证且指导未来实现；guide 含非显而易见的过程知识或失败尝试。
-
-**Keep snapshot**：仅迭代史、已被 `{SPECS_DIR}/` 取代的草案、或自检 ≤2 Yes 的琐碎笔记。
+**Promote 典型**：迭代 spec 已验证且指导未来实现；guide 含非显而易见过程知识或失败尝试。**Keep snapshot**：仅迭代史、已被 `{SPECS_DIR}/` 取代的草案、或自检 ≤2 Yes 的琐碎笔记。边界 SSOT → **`mstar-iteration/references/iteration-artifact-boundaries.md`**。
 
-边界 SSOT → **`mstar-iteration/references/iteration-artifact-boundaries.md`**。
+## When to use / Skip
 
-## When to use (trigger)
+**Use**：迭代收口（`mstar-iteration` § iteration-close）批量回顾；独立触发（非迭代或紧急，任何非平凡问题解决后）；重大 bug 修复后（`mstar-iteration` 未启用时手动）。
 
-- **迭代收口时**（`mstar-iteration` § iteration-close）：PM 批量回顾所有 plan 的产物
-- **独立触发**（非迭代模式或紧急情况）：任何非平凡问题解决后，PM 或开发者手动触发
-- **Debug 后**：`mstar-iteration` 尚未启用时，重大 bug 修复后手动触发
-
-### Skip when
-
-- 自检清单判定 ≤ 2 个 Yes
-- Q5 高重叠（应更新已有文档而非新建）
-- 纯机械性工作：格式化、依赖升级、typo 修复
-- 问题仍在进行中或方案未经验证
+**Skip**：自检 ≤2 Yes；Q5 高重叠（更新已有而非新建）；纯机械工作（格式化、依赖升级、typo）；问题未经验证。
 
 ## Two tracks
 
-The skill classifies work into one of two tracks based on problem type:
-
 | Track | What it captures | Section structure |
 |-------|-----------------|-------------------|
 | **Bug** | Incident-level fix — "X broke, here's why and how we fixed it" | Problem, Symptoms, What Didn't Work, Solution, Why This Works, Prevention |
 | **Knowledge** | Durable guidance — "this is how we do X, and why" | Context, Guidance, Why This Matters, When to Apply, Examples |
 
-Track is determined by `problem_type`. See `references/category-mapping.md` for the full mapping.
+Track 由 `problem_type` 决定，完整映射见 `references/category-mapping.md`。
 
 ## Execution modes
 
 | Mode | When | Behavior |
 |------|------|----------|
-| **Full** (default) | Most cases | Dispatches research subagents for context analysis, solution extraction, and overlap detection |
+| **Full** (default) | Most cases | Dispatches research subagents for context analysis, solution extraction, overlap detection |
 | **Lightweight** | Simple fixes, context-tight sessions | Single-pass documentation, no subagents, faster |
 
 In Cursor, Full mode dispatches subagents via Task tool. PM selects mode.
 
-## Phase 1: Gather context
-
-Read the conversation history **and**, when `iteration_id` is known, scan **`{ITERATION_DIR}/<iteration-id>/`** package per **Iteration package promotion** above.
-
-Understand:
-- What problem was solved (the concrete issue)
-- What was tried and didn't work
-- What the working solution was
-- Why the solution works (root cause)
-- Which files/modules were involved
-- The plan_id if applicable (link to `status.json`)
-
-If `{KNOWLEDGE_DIR}/README.md` exists, scan its index for related existing documents.
-
-Classify the problem into a track (bug vs knowledge) and category using `references/category-mapping.md`.
-
-## Phase 2: Overlap detection
-
-Before creating a new doc, check if an existing doc covers the same ground:
-
-1. Extract keywords from the problem (module names, error messages, technical terms)
-2. Search `{KNOWLEDGE_DIR}/**/*.md` using frontmatter fields (`module:`, `tags:`, `problem_type:`)
-3. Score overlap across dimensions: problem statement, root cause, solution approach, referenced files, prevention
-
-| Overlap | Action |
-|---------|--------|
-| **High** (4-5 dimensions match) | **Update** the existing doc with fresher context instead of creating a new one. Add `last_updated` field. |
-| **Moderate** (2-3 dimensions match) | Create new doc; flag for consolidation review (potential `mstar-compound-refresh` trigger) |
-| **Low/None** | Create new doc normally |
-
-## Phase 3: Write the document
-
-### 3.1 Determine path
-
-Category → directory under `{KNOWLEDGE_DIR}/`. Examples:
-- Bug track: `build-errors/`, `runtime-errors/`, `performance-issues/`, `database-issues/`, `security-issues/`, `integration-issues/`
-- Knowledge track: `architecture-patterns/`, `design-patterns/`, `conventions/`, `workflow-patterns/`, `tooling-decisions/`, `best-practices/`
-
-Filename: `<sanitized-slug>.md` (lowercase, hyphen-separated, no date prefix).
-
-### 3.2 Frontmatter
-
-Required fields for both tracks (SSOT: `references/schema.yaml`):
-
-```yaml
----
-module: <area>
-date: YYYY-MM-DD
-problem_type: <enum value>
-category: <directory name>
-severity: critical|high|medium|low
-plan_id: <optional, link to status.json>
-tags: [<keywords>]
----
-```
-
-Bug-track adds: `symptoms`, `root_cause`, `resolution_type`.
-Knowledge-track adds: `applies_when` (optional).
-
-### 3.3 Body
-
-Follow the section structure from `assets/resolution-template.md` for the determined track.
-
-### 3.4 Validate
-
-After writing, validate the YAML frontmatter:
-- `---` delimiters are correct
-- All required fields present
-- Enum values match allowed values
-- `date` is YYYY-MM-DD format
-- Array fields use `[item1, item2]` syntax
-
-## Phase 4: Discoverability check
-
-Check whether the project's `AGENTS.md` or `CLAUDE.md` would lead a future agent to discover `{KNOWLEDGE_DIR}`.
-
-If `{KNOWLEDGE_DIR}` is not mentioned in the root instruction file, propose the smallest addition that surfaces the knowledge store. Example:
-
-```markdown
-- `{HARNESS_DIR}/knowledge/` — captured solutions and reusable patterns
-```
-
-Ask for user consent before applying (PM can approve). If the user declines, the doc is still written — only the discoverability edit is skipped.
-
-## Phase 5: CONCEPTS.md synergy
+## Workflow skeleton（Phase 1–7）
 
-If the captured learning introduces or clarifies a domain term whose meaning is project-specific and not obvious to a newcomer, propose adding it to `CONCEPTS.md` at the repo root.
+完整步骤细节（Gather context / Overlap detection / Write document 含 frontmatter schema + path + validate / Discoverability check / CONCEPTS.md synergy / Update indexes / Refresh trigger）→ **`references/compound-workflow.md`**。每 Phase 一个关键决策：
 
-Read `references/concepts-vocabulary.md` for inclusion rules. Only propose when the term meets the qualifying bar:
-- Its meaning in this project is precise enough that a new engineer would need it defined
-- It is not general programming vocabulary
-
-If `CONCEPTS.md` doesn't exist yet, ask whether to seed it. A seed populates the core domain nouns of the area the learning touches; a full repo-wide bootstrap is the job of `mstar-compound-refresh`.
-
-## Phase 6: Update indexes
-
-1. Add a row to `{KNOWLEDGE_DIR}/README.md` index table (create if missing):
-   - Document (link), Source Plan (`plan_id`), Description, Status (`Active`)
-
-2. If `plan_id` was provided, optionally update `status.json` metadata to reference this doc under `knowledge_refs`.
-
-**iteration-close gate**: `mstar-iteration` §3.2 #5 — **each** new doc in the compound round must complete this phase; do not skip for lightweight captures.
-
-## Phase 7: Refresh trigger
-
-After capturing, check if the new learning suggests an older doc may now be stale (contradicted, superseded, or in a refactored domain). If so, recommend:
-
-```
-Consider: /pm compound-refresh <scope hint>
-```
-
-Do not automatically run refresh — only flag when there's a concrete reason.
-
-## CONCEPTS.md bootstrap requests
-
-If invoked specifically to create CONCEPTS.md from scratch (not to document a solved problem), redirect to `mstar-compound-refresh` (which handles full repo-wide vocabulary bootstrapping). `mstar-compound` only seeds vocabulary as a side effect of capturing a real learning.
+1. **Gather** — 读对话史 + iteration package；分类 track/category（`references/category-mapping.md`）
+2. **Overlap** — 高重叠 → 更新已有（加 `last_updated`）；中度 → 新建并标 consolidation review；低/无 → 正常新建
+3. **Write** — path + frontmatter（SSOT `references/schema.yaml`）+ body（`assets/resolution-template.md`）+ YAML validate
+4. **Discoverability** — 若 root `AGENTS.md`/`CLAUDE.md` 未提 `{KNOWLEDGE_DIR}`，提议最小补充（需用户同意；拒绝则仅跳过该编辑，doc 仍写）
+5. **CONCEPTS.md** — 项目特定领域词满足 qualifying bar 时提议入 `CONCEPTS.md`（规则见 `references/concepts-vocabulary.md`）；全仓 bootstrap 归 `mstar-compound-refresh`
+6. **Indexes** — `{KNOWLEDGE_DIR}/README.md` 加行（Document / Source Plan / Description / Status）；可选 `status.json` `knowledge_refs`。**iteration-close gate**：每篇新 doc 必须 Phase 6
+7. **Refresh trigger** — 新知识暗示旧 doc 过时 → 推荐 `/pm compound-refresh <scope>`（不自动跑，仅 flag）
 
 ## Support files
 
-Read on demand at the step that needs them:
-
-- `references/schema.yaml` — canonical frontmatter schema (Phase 3)
-- `references/category-mapping.md` — problem_type → directory + track mapping (Phase 1)
-- `references/concepts-vocabulary.md` — CONCEPTS.md rules (Phase 5)
-- `assets/resolution-template.md` — section structure per track (Phase 3)
+读 `references/compound-workflow.md`（Q1–Q8 + Phase 1–7）、`references/schema.yaml`（frontmatter）、`references/category-mapping.md`（track/path 映射）、`references/concepts-vocabulary.md`（CONCEPTS.md 规则）、`assets/resolution-template.md`（track 正文结构）。
 
 ## Skill dependencies
 
-This skill integrates with:
-- **`mstar-plan-conventions`** — path symbols (`{KNOWLEDGE_DIR}`, `{HARNESS_DIR}`)
-- **`mstar-plan-artifacts`** — `status.json` linking, index maintenance
-- **`mstar-compound-refresh`** — for knowledge maintenance after capture
+- **`mstar-plan-conventions`** — path symbols（`{KNOWLEDGE_DIR}`、`{HARNESS_DIR}`）
+- **`mstar-plan-artifacts`** — `status.json` linking、index maintenance
+- **`mstar-compound-refresh`** — capture 后知识维护；CONCEPTS.md 全仓 bootstrap
 
 ## NOT to do