the-rabak/compound-engineering-plugin/compound-refresh

Compound Refresh

Maintain the quality of docs/solutions/ over time. Review existing learnings against the current codebase, then refresh any derived pattern docs that depend on them.

Mode Detection

Check if $ARGUMENTS contains mode:autonomous. If present, strip it from arguments and run in autonomous mode.

Autonomous mode rules

• Skip all user questions.
• Process all docs in scope. If no scope hint was provided, process everything.
• Attempt all safe actions: Keep, Update, auto-Archive, and Replace when evidence is sufficient.
• If a write succeeds, record it as applied.
• If a write fails, record it as recommended in the report and continue.
• If classification is genuinely ambiguous, mark the doc stale with status: stale, stale_reason, and stale_date.
• Use conservative confidence. Borderline cases become stale in autonomous mode.
• Always generate a report with Applied and Recommended sections.

Local Grounding

Before editing anything under docs/solutions/, read the local guidance files in this order:

1. AGENTS.md
2. CLAUDE.md (if present)
3. README.md

Use them to preserve the repository's docs conventions, OpenViking guidance, and workflow naming.

Interaction Principles

These principles apply to interactive mode only. In autonomous mode, skip all user questions and apply the autonomous rules above.

Follow the same interaction style as /workflows:brainstorm:

• ask questions one at a time
• prefer multiple choice when natural options exist
• start with scope and intent, then narrow only when needed
• do not ask the user to decide before you have evidence
• lead with a recommendation and explain it briefly

The goal is to help the user make a good maintenance decision with minimal friction.

Refresh Order

Refresh in this order:

1. review the relevant individual learning docs first
2. note which learnings stayed valid, were updated, were replaced, or were archived
3. then review any pattern docs that depend on those learnings

Why this order:

• learning docs are the primary evidence
• pattern docs are derived from one or more learnings
• stale learnings can make a pattern look more valid than it really is

If the user starts by naming a pattern doc, you may begin there to understand the concern, but inspect the supporting learning docs before changing the pattern.

Maintenance Model

For each candidate artifact, classify it into one of four outcomes:

Core Rules

1. Evidence informs judgment. Use engineering judgment; do not treat this as a mechanical scorecard.
2. Prefer no-write Keep. Do not edit a doc just to leave a review breadcrumb.
3. Match docs to reality, not the reverse. If current code differs from a learning, update the learning to reflect the codebase as it exists today.
4. Be decisive, minimize questions. When evidence is clear, apply the update. Only ask when the action is genuinely ambiguous.
5. Avoid low-value churn. Do not edit a doc for cosmetic wording or style-only cleanup.
6. Use Update only for meaningful, evidence-backed drift. Paths, module names, links, code snippets, and metadata are fair game when accuracy improves materially.
7. Use Replace only when there is a real replacement. The current codebase, related docs, or recent verified fixes must provide enough evidence to document the successor honestly.
8. Archive when the code is gone and the problem domain is gone. Missing referenced files with no matching modern equivalent is strong archive evidence.

Scope Selection

Start by discovering learnings and pattern docs under docs/solutions/.

Exclude:

• README.md
• docs/solutions/_archived/

Find all .md files under docs/solutions/, excluding README.md files and anything under _archived/.

If $ARGUMENTS is provided, use it to narrow scope in this order:

1. Directory match - a subdirectory under docs/solutions/
2. Frontmatter match - module, component, or tags
3. Filename match - partial filename match is fine
4. Content search - keyword search inside files

If no matches are found, report that and ask the user to clarify. In autonomous mode, report the miss and stop.

If no candidate docs are found, report:

No candidate docs found in docs/solutions/.
Run `/workflows:compound` after solving problems to start building your knowledge base.

Phase 0: Assess and Route

Before asking the user to classify anything:

1. discover candidate artifacts
2. estimate scope
3. choose the lightest interaction path that fits

Route by Scope

Broad Scope Triage

When scope is broad:

1. inventory frontmatter and group by module, component, or category
2. identify dense clusters of learnings plus pattern docs
3. spot-check whether the primary referenced files still exist
4. recommend a starting area; in autonomous mode, process all clusters in impact order

Do not ask action-selection questions yet. First gather evidence.

Phase 1: Investigate Candidate Learnings

For each learning in scope, read it, cross-reference its claims against the current codebase, and form a recommendation.

A learning can go stale in several dimensions:

• References - do the file paths, class names, and modules still exist or have they moved?
• Recommended solution - does the fix still match how the code works today?
• Code examples - if snippets exist, do they still reflect the current implementation?
• Related docs - are cross-referenced learnings and patterns still present and consistent?
• Local guidance alignment - does the learning still match current repository conventions documented in AGENTS.md, CLAUDE.md, and README.md?

Match investigation depth to the learning's specificity. A learning with exact file paths and code snippets needs more verification than one describing a general principle.

Drift Classification: Update vs Replace

The critical distinction is whether the drift is cosmetic or substantive:

• Update territory - file paths moved, classes renamed, links broke, metadata drifted, but the core recommended approach is still correct.
• Replace territory - the recommended solution conflicts with current code, the architecture changed, or the preferred pattern is different.

The boundary: if you find yourself rewriting the solution section or changing what the learning recommends, stop. That is Replace, not Update.

Judgment Guidelines

Three guidelines that are easy to get wrong:

1. Contradiction = strong Replace signal. If the learning conflicts with current code or a recently verified fix, it is actively misleading.
2. Age alone is not a stale signal. Use age only as a prompt to inspect more carefully.
3. Check for successors before archiving. Before recommending Replace or Archive, look for newer learnings, pattern docs, PRs, or issues covering the same problem space.

Phase 1.5: Investigate Pattern Docs

After reviewing the underlying learning docs, investigate any relevant pattern docs under docs/solutions/patterns/.

Pattern docs are high-leverage. A stale pattern is more dangerous than a stale individual learning because future work may treat it as broadly applicable guidance.

A pattern doc with no clear supporting learnings is itself a stale signal.

Subagent Strategy

Use subagents for context isolation when investigating multiple artifacts. Choose the lightest approach that fits:

When spawning any subagent, include this instruction in its task prompt:

Use dedicated file search and read tools for all investigation. Do not use shell commands for file operations. Report: file path, evidence, recommended action, confidence, and open questions.

There are two subagent roles:

1. Investigation subagents - read-only. They must not edit files or archive anything.
2. Replacement subagents - write a single new learning to replace a stale one. Run these one at a time.

The orchestrator merges investigation results, detects contradictions, coordinates replacement subagents, and performs archival or metadata edits centrally.

Phase 2: Classify the Right Maintenance Action

After gathering evidence, assign one recommended action.

Keep

The learning is still accurate and useful. Do not edit the file. Report that it remains trustworthy.

Update

The core solution is still valid but references have drifted. Apply the fixes directly.

Replace

Choose Replace when the learning's core guidance is now misleading.

Assess whether evidence is sufficient to write a trustworthy replacement:

• Sufficient evidence - you understand both what the old learning recommended and what the current approach is. Proceed to write the replacement.
• Insufficient evidence - you cannot confidently document the current approach. Mark the file stale in place with:
• status: stale
• stale_reason
• stale_date: YYYY-MM-DD

Archive

Choose Archive when:

• the code or workflow no longer exists
• the learning is obsolete and has no modern replacement worth documenting
• the learning is redundant and no longer useful on its own
• there is no meaningful successor evidence suggesting it should be replaced instead

Action:

• move the file to docs/solutions/_archived/
• add archived_date: YYYY-MM-DD
• add archive_reason

Before archiving: check whether the problem domain still exists

If the referenced implementation is gone but the broader problem domain is still active, that is usually Replace, not Archive.

Auto-archive only when both the implementation and the problem domain are gone, or when the doc is fully superseded by a clearly better successor.

Pattern Guidance

Apply the same four outcomes to pattern docs, but evaluate them as derived guidance:

• Keep - underlying learnings still support the generalized rule
• Update - the rule holds but examples, links, or supporting references drifted
• Replace - the rule is now misleading or the refreshed learnings support a different synthesis
• Archive - the pattern is no longer valid, recurring, or distinct

Phase 3: Ask for Decisions

Autonomous mode