# Strategic Compact

> Promotes recurring feedback into the right skill, then guides /compact at phase boundaries.

- Skill: `shir-bruchim/strategic-compact` (Agent Skill, multi-file: 11 files)
- Install (CLI): `npx skillmds@latest add shir-bruchim/strategic-compact`
- Raw SKILL.md: https://api.skillmd.com/api/skills/shir-bruchim/strategic-compact/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: shir-bruchim (https://skillmd.com/u/shir-bruchim)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/shir-bruchim/strategic-compact

---


<objective>
User-invoked maintenance + compaction checkpoint. Two phases, in order:

1. **Self-improvement pass.** Scan recent feedback memories + this session for rules that belong in a skill. Promote, shrink the source, mark MEMORY.md.
2. **Compaction recommendation.** Suggest `/compact` at a logical phase boundary with a paste-ready summary.

The skill is `disable-model-invocation: true` — zero context cost until the user types `/strategic-compact`.
</objective>

<universe>
Run at invocation. Output replaces these lines before Claude sees the body.

Skills on disk:
!`ls -1 ~/.claude/skills/ 2>/dev/null`

Subagents on disk:
!`ls -1 ~/.claude/agents/ 2>/dev/null`

Commands on disk:
!`ls -1 ~/.claude/commands/ 2>/dev/null`

Rules on disk:
!`ls -1 ~/.claude/rules/ 2>/dev/null`

Hook scripts on disk:
!`ls -1 ~/.claude/hooks/ 2>/dev/null`

Hooks + MCP + plugins configured in settings.json:
!`bash ~/.claude/skills/strategic-compact/scripts/settings-features.sh`

Today:
!`date -u +%Y-%m-%dT%H:%M:%SZ`
</universe>

<architecture>
The work splits into two phases that have DIFFERENT context requirements:

- **SCAN phase** is a heavy file-read sweep across ALL Claude-extension types (skills, subagents, hooks, commands, rules, MCP, plugins — see `features-overview` doc). Per `references/claude-code-best-practices.md`, the audit must cover the full extension surface, not just skills. Delegate to a subagent so the main loop's context stays small.
- **APPLY phase** needs per-candidate `AskUserQuestion` prompts. Forked subagents CANNOT call `AskUserQuestion`. APPLY runs in the main loop.

This skill does NOT use `context: fork` in frontmatter (that would forbid `AskUserQuestion` across the whole run). Instead the body spawns a subagent for SCAN only, then continues in main-loop context for APPLY.
</architecture>

<run>
Execute in order:

1. **SCAN** — Spawn a `general-purpose` subagent with this prompt:

   > Read `~/.claude/skills/strategic-compact/workflows/self-improvement-pass.md` and execute it end-to-end. Your final output must be the candidate-list Markdown described in the "Output contract" section. ALSO write the same content to `~/.claude/tmp/strategic-compact-candidates-<UTC-timestamp>.md` (create the dir if missing). Return only the candidate list — no prose preamble.

   Wait for the agent return. Save the file path it created.

2. **APPLY** — Read `~/.claude/skills/strategic-compact/workflows/apply-edits.md` and execute it against the candidate list (prefer the subagent return; fall back to the file if truncated). Use `AskUserQuestion` for each candidate.

3. **DECIDE** — Read `~/.claude/skills/strategic-compact/workflows/compaction-decision.md` and emit a compaction recommendation with a paste-ready `/compact <summary>` line.

If the SCAN phase returns an empty candidate list AND the self-healing sweep found nothing, skip directly to DECIDE.
</run>

<skip_when>
- User explicitly says "skip self-improvement" or "just compact" → run only DECIDE.
- No `feedback_*` memories exist AND the session contained no corrections worth promoting → SCAN will report empty; skip to DECIDE.
- All candidate rules are project-specific (e.g., "PR #196 ships behind flag X") → SCAN drops them; skip to DECIDE.
</skip_when>

<workflows_index>
| Workflow | Role |
|----------|------|
| `workflows/self-improvement-pass.md` | SCAN — runs in a delegated subagent; produces candidate list |
| `workflows/apply-edits.md` | APPLY — runs in main loop; per-candidate y/n prompts + Edit + shrink source |
| `workflows/compaction-decision.md` | DECIDE — phase-boundary table + paste-ready `/compact` summary |
</workflows_index>

<references_index>
| Reference | When to read |
|-----------|--------------|
| `references/promotion-quality-gates.md` | During SCAN step 7b — every candidate must clear all 6 gates |
| `references/self-healing-checks.md` | During SCAN step 1c (early) and APPLY late-sweep |
| `references/claude-code-best-practices.md` | Pre-SCAN freshness check + drift-watch surfacing |
</references_index>

<scripts_index>
The SCAN agent runs these EVERY invocation. Each replaces a multi-step inline bash block in the workflow doc — one tool call instead of six. Both emit `=== SECTION ===` prefixes for cheap parsing.

| Script | Replaces | Run during |
|--------|----------|------------|
| `scripts/scan-inventory.sh` | Steps 1, 1d, 1e, 1f, 1g, 1h, 1i (extension-universe dump) | Step 1 of SCAN |
| `scripts/self-healing-sweep.sh` | Checks 1, 2, 4, 7 from `references/self-healing-checks.md` (mechanical-only) | Step 1c of SCAN |

`scan-inventory.sh` is also redundant when the SKILL.md `<universe>` block's dynamic context injection already ran — skip it in that case. Useful for fresh-fork invocations.

`self-healing-sweep.sh` honors `SCAN_STRICT_XREF=1` to disable the known-optional-path filter (debugging only). Honors `MEMORY_DIR=<path>` to override project-memory auto-detection.
</scripts_index>

<success_criteria>
- [ ] SCAN delegated to a subagent — main-loop context stayed small.
- [ ] Candidate list received as agent return AND written to `~/.claude/tmp/`.
- [ ] Each candidate that cleared the 6 gates was prompted per-entry; declines noted.
- [ ] Approved edits applied; sources shrunk; MEMORY.md marked.
- [ ] Self-healing findings surfaced (early sweep + late re-check).
- [ ] Compaction recommendation paste-ready (`/compact <summary>` line).
- [ ] No important context lost without first being written to a durable location.
</success_criteria>