Mstar Compound Refresh

mstar-compound-refresh（知识维护）

Load order

Read mstar-harness-core first. Path symbols → mstar-plan-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-plan-conventions/references/artifact-storage-paths.md。本 skill 仅操作 {HARNESS_DIR}/knowledge/**/*.md + {HARNESS_DIR}/knowledge/README.md + /CONCEPTS.md + {HARNESS_DIR}/status.json（引用更新）。禁止操作 docs/、{PLAN_DIR}/、{ITERATION_DIR}/、{SPECS_DIR}/。

> Engine check (when available): run mstar compound validate --knowledge-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, /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 |

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 -- finds deleted docs.
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}//.
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.

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 doc was linked from status.json metadata, update 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)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: btspoony
• Source: btspoony/mstar-harness
• License: MIT

Install and usage instructions live in the source repository linked above.