mstar-compound-refresh（知识维护）

Load order

Read mstar-harness-core first. Path symbols → mstar-conventions. On conflict, mstar-harness-core wins.

Purpose

Knowledge documents in {KNOWLEDGE_DIR} age. Code changes, conventions evolve, patterns become obsolete. mstar-compound-refresh audits the knowledge store against the current codebase and makes it trustworthy again.

产物与操作路径

SSOT: mstar-conventions/references/artifact-storage-paths.md。本 skill 仅操作 {HARNESS_DIR}/knowledge/**/*.md + {HARNESS_DIR}/knowledge/README.md + <repo-root>/CONCEPTS.md + {HARNESS_DIR}/status.json（引用更新；v2 中知识引用挂在 workflow snapshot plan 行 metadata.knowledge_refs，见下）。禁止操作 docs/、{PLAN_DIR}/、{ITERATION_DIR}/、{SPECS_DIR}/。

Engine check (when available): run mstar compound validate <doc-path> --knowledge-dir <dir> (or import { scopeGuard, compoundRefreshScope } from "@mstar-harness/engine" in a host hook) to resolve the allowed scope above ({HARNESS_DIR}/knowledge/**, knowledge/README.md, <repo-root>/CONCEPTS.md, {HARNESS_DIR}/status.json) and guard every write against it. On fail -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.

When to use

Trigger	Example
mstar-compound detected overlapping docs	"Two docs cover N+1 queries — consider refresh"
Scheduled maintenance	"It's been a quarter, let's audit knowledge"
Domain refactored	After a major module rewrite
Explicit user request	/pm compound-refresh performance-issues
Project knowledge bootstrap	No/stale/partial STRATEGY.md, CONCEPTS.md, or {KNOWLEDGE_DIR} — see below

Bootstrap vs refresh

Mode	When	Procedure
Refresh	{KNOWLEDGE_DIR} exists; audit accuracy, merge overlaps, delete stale docs	This skill § Process (Phases 1–6)
Bootstrap	No knowledge scaffolding, or artifacts are absent/stale enough to warrant full distillation from codebase	references/project-knowledge-bootstrap.md (7-phase: survey → STRATEGY.md → CONCEPTS.md → baseline knowledge → indexing → harness init → commit)

Read the bootstrap reference on demand; do not paste its body into this SKILL.md.

Maintenance outcomes

For each candidate document, classify into one of five outcomes:

Outcome	Meaning	Default action
Keep	Still accurate and useful	No edit; report reviewed
Update	Core solution correct, references drifted	In-place edits (paths, module names, code snippets)
Consolidate	Two+ docs overlap heavily, both correct	Merge unique content into canonical doc, delete subsumed
Replace	Old doc is misleading; known better replacement exists	Create trustworthy successor, then delete old
Delete	No longer useful, applicable, or distinct	Delete — git history preserves it

Guardrail — rejected approaches: a captured rejected approach stays only while the losing idea remains a tempting, meaningful mistake; delete it once obsolete or no longer plausible. Calibration: first real run of this axis — 9 size-divergent knowledge docs (36–78 lines) under {KNOWLEDGE_DIR}/architecture-patterns/ classified at fold time, all kept by future value (evidence: the knowledge-prose-folds plan ## Review Gate Summary → Task evidence); length proved not to be a criterion.

Core rules

1. Evidence over opinion. Signals are inputs, not a scorecard. Use engineering judgment.
2. Prefer no-write Keep. Do not update a doc just to leave a review breadcrumb.
3. Match docs to reality. When code differs from doc, update the doc — not ask whether the code change was "intentional."
4. Be decisive. When evidence is clear (file renamed, class moved), apply. Only ask PM when genuinely ambiguous.
5. Avoid low-value churn. Don't edit for typos, polish, or cosmetic changes that don't improve accuracy.
6. Delete, don't archive — except formal iteration-start §1.6 corpus hygiene (mstar-iteration/references/iteration-corpus-hygiene.md), which moves superseded/redundant knowledge/specs to {HARNESS_DIR}/archived/knowledge|specs/. Outside that gate, git history is the archive; git log --diff-filter=D -- <path> finds deleted docs.

   Not adopted: frozen-archive seal machinery, Archived: triplets, or a verifier — they contradict rule 6 (delete, don't archive; git history is the archive); do not reintroduce.

7. Evaluate document-set design. Check whether two+ docs overlap and should be consolidated. Redundant docs silently drift apart.

Scope selection

Default: user-guided

1. Ask PM for scope: "All knowledge docs, a specific category, or a keyword?"
2. If category: narrow to {KNOWLEDGE_DIR}/<category>/.
3. If keyword: search frontmatter (module:, tags:, problem_type:) and filenames.

PM-directed: specific scope

PM provides a scope hint (directory name, filename, module name, or keyword). Match in this order:

1. Directory match under {KNOWLEDGE_DIR}/
2. Frontmatter field match
3. Filename match
4. Content search

Process

Phase 1: Inventory

1. List all .md files under {KNOWLEDGE_DIR}/ (excluding README.md and index files).
2. Read frontmatter of each candidate.
3. Group by category / module for impact clustering.

Phase 2: Assess per doc

For each doc, check:

1. Referenced code still exists? — grep for file paths, class names, function names mentioned.
2. Referenced conventions still match? — check against current AGENTS.md, CONCEPTS.md, lint configs.
3. Solution still the recommended approach? — has a newer pattern superseded it?
4. Overlap with other docs? — search for same module/tags to find duplicates.
5. Future decision value? — rationale / alternatives considered / negative guarantees / reintroduction conditions that would still guide a future change → Keep, regardless of length. A completed decision whose body has no future leverage left (one-off fix detail, superseded mechanics) enters the Delete candidate pool. Word count and age remain discovery aids, never criteria.

Phase 3: Classify and act

Classify each doc → Keep / Update / Consolidate / Replace / Delete. Apply changes.

Phase 4: Update indexes

1. Update {KNOWLEDGE_DIR}/README.md index table — update Status column, add/remove rows.
2. If a doc was linked from knowledge refs (workflow snapshot plan row metadata.knowledge_refs / v1 root status.json metadata), update the references.

Phase 5: Report

Produce a maintenance report:

• Docs reviewed (count)
• Docs kept (count)
• Docs updated (list with what changed)
• Docs consolidated (list with which canonical doc merged into)
• Docs replaced (list with successor path)
• Docs deleted (list with reason)
• Docs flagged for PM review (ambiguous cases)

Phase 6: CONCEPTS.md reconciliation

If CONCEPTS.md exists, reconcile it with the refreshed knowledge:

• Terms mentioned in updated/replaced docs may need updating in CONCEPTS.md
• Terms no longer referenced may be candidates for removal

If CONCEPTS.md doesn't exist but knowledge docs contain qualifying domain terms, propose bootstrapping it (full repo-wide seed). Use references/concepts-vocabulary.md from mstar-compound for rules (read on demand — cross-skill path resolution via skill directory).

Cross-skill coordination

mstar-compound-refresh reads vocabulary rules from mstar-compound's references. At runtime, resolve the path from the loaded skill directory:

The CONCEPTS.md vocabulary rules are in the mstar-compound skill at:
references/concepts-vocabulary.md
Read that file from the mstar-compound skill directory before Phase 6.

NOT to do

• Do not delete docs without checking for inbound links
• Do not "archive" — delete instead
• Do not ask PM about mechanical updates (path fixes, renamed modules)
• Do not change code to match outdated docs — update docs to match code
• Do not run without PM approval for destructive actions (Delete, Replace)

Evidence

正确结果 = 每篇候选文档有明确 verdict（Keep / Update / Consolidate / Replace / Delete）并落到产物：文档改动 + {KNOWLEDGE_DIR}/README.md 索引更新（Phase 4）+ 知识引用同步（workflow snapshot plan 行 knowledge_refs；v1 根 status.json legacy 引用） + 维护报告（Phase 5：reviewed / kept / updated / consolidated / replaced / deleted / flagged）+ CONCEPTS.md 对账（Phase 6）。

References

• 捕获侧规则与 CONCEPTS.md vocabulary 规则 → mstar-compound（Phase 6 前读 references/concepts-vocabulary.md）
• 路径符号与产物存储 SSOT → mstar-conventions（references/artifact-storage-paths.md）