compound-engineering-plugin-mirror/plugins/compound-engineering/skills/ce-compound-refresh/references/per-action-flows.md

Per-Action Flows

Read this reference when executing Phase 4. Find the section matching the action classified in Phase 2 and confirmed in Phase 3 (Keep, Update, Consolidate, Replace, or Delete) and follow that flow.

Keep Flow

No file edit by default. Summarize why the learning remains trustworthy.

Update Flow

Apply in-place edits only when the solution is still substantively correct.

Examples of valid in-place updates:

• Rename app/models/auth_token.rb reference to app/models/session_token.rb
• Update module: AuthToken to module: SessionToken
• Fix outdated links to related docs
• Refresh implementation notes after a directory move

Examples that should not be in-place updates:

• Fixing a typo with no effect on understanding
• Rewording prose for style alone
• Small cleanup that does not materially improve accuracy or usability
• The old fix is now an anti-pattern
• The system architecture changed enough that the old guidance is misleading
• The troubleshooting path is materially different

Those cases require Replace, not Update.

Consolidate Flow

The orchestrator handles consolidation directly (no subagent needed — the docs are already read and the merge is a focused edit). Process Consolidate candidates by topic cluster. For each cluster identified in Phase 1.75:

1. Confirm the canonical doc — the broader, more current, more accurate doc in the cluster.
2. Extract unique content from the subsumed doc(s) — anything the canonical doc does not already cover. This might be specific edge cases, additional prevention rules, or alternative debugging approaches.
3. Merge unique content into the canonical doc in a natural location. Do not just append — integrate it where it logically belongs. If the unique content is small (a bullet point, a sentence), inline it. If it is a substantial sub-topic, add it as a clearly labeled section.
4. Update cross-references — if any other docs reference the subsumed doc, update those references to point to the canonical doc.
5. Delete the subsumed doc. Do not archive it, do not add redirect metadata — just delete the file. Git history preserves it.

If a doc cluster has 3+ overlapping docs, process pairwise: consolidate the two most overlapping docs first, then evaluate whether the merged result should be consolidated with the next doc.

Structural edits beyond merge: Consolidate also covers the reverse case. If one doc has grown unwieldy and covers multiple distinct problems that would benefit from separate retrieval, it is valid to recommend splitting it. Only do this when the sub-topics are genuinely independent and a maintainer might search for one without needing the other.

Replace Flow

Process Replace candidates one at a time, sequentially. Each replacement is written by a subagent to protect the main context window.

When a replacement is needed, read the documentation contract files and pass their contents into the replacement subagent's task prompt:

• references/schema.yaml — frontmatter fields and enum values
• references/yaml-schema.md — category mapping
• assets/resolution-template.md — section structure

Do not let replacement subagents invent frontmatter fields, enum values, or section order from memory.

When evidence is sufficient:

1. Spawn a single subagent to write the replacement learning. Pass it:
   • The old learning's full content
   • A summary of the investigation evidence (what changed, what the current code does, why the old guidance is misleading)
   • The target path and category (same category as the old learning unless the category itself changed)
   • The relevant contents of the three support files listed above
2. The subagent writes the new learning using the support files as the source of truth: references/schema.yaml for frontmatter fields and enum values, references/yaml-schema.md for category mapping and YAML-safety rules for array items, and assets/resolution-template.md for section order. It should use dedicated file search and read tools if it needs additional context beyond what was passed.
3. Run python3 scripts/validate-frontmatter.py <new-learning-path> to catch silent-corruption parser-safety issues that the prose rules miss: malformed --- delimiter lines, unquoted # in scalar values (silent comment truncation), and unquoted : in scalar values (silent mapping confusion). Exit 0 means the doc is parser-safe; exit 1 means the script's stderr names the offending field(s) and what to fix — quote the value(s), re-write the doc, and re-run until exit 0. Do not declare success while validation fails. The script does not enforce schema rules and does not flag YAML reserved-indicator characters (those produce loud parser errors downstream rather than silent corruption — out of scope). Uses Python 3 stdlib only (no PyYAML or other deps).
4. After the subagent completes, the orchestrator deletes the old learning file. The new learning's frontmatter may include supersedes: [old learning filename] for traceability, but this is optional — the git history and commit message provide the same information.

When evidence is insufficient:

1. Mark the learning as stale in place:
   • Add to frontmatter: status: stale, stale_reason: [what you found], stale_date: YYYY-MM-DD
2. Report what evidence was found and what is missing
3. Recommend the user run ce-compound after their next encounter with that area

Delete Flow

Delete only when a learning is clearly obsolete, redundant (with no unique content to merge), or its problem domain is gone. Do not delete a document just because it is old — age alone is not a signal.

Before unlinking the file, run a final inbound-link check across the repo's markdown content to catch any references missed during Phase 1 investigation. Prefer the platform's native content-search tool (e.g., Grep in Claude Code) for efficiency; use ranged or context-line reads around matches rather than loading whole files.

Each match is a citation that will dangle after delete. Cleanup is mechanical — Phase 2 already classified the citations and confirmed Delete was right. Don't re-litigate.

If any citation surfaces here that wasn't seen in Phase 1 and is anything other than unambiguously decorative (substantive or mixed/unclear), stop and reclassify: autofix mode stale-marks; interactive mode asks the user whether Replace fits. Only proceed with cleanup when all late-discovered citations are unambiguously decorative.