System Self Improve

/system-self-improve

The meta-improvement layer of the architect-playbook. When a review surfaces a gap that one of the audits missed — or when running an audit reveals a weakness in the audit itself — /system-self-improve reads the gap, locates the affected SKILL.md (and any adjacent files: README, CLAUDE.md, pre-audit-setup hook, MEMORY.md), proposes a minimal reversible edit, asks for confirmation, and on approval mutates the playbook so the same gap is more likely to be caught next time.

This is the only skill in the playbook that writes to files outside its own .architect-audits/ directory. That power is gated behind a deliberate two-stage flow.

How this differs from neighbouring skills

| Concern | Owner | | --- | --- | | Auditing a target codebase against an opinionated baseline | Every audit skill (/security-audit, /performance-audit, etc.) | | Generating an implementation plan that the user then executes against the target codebase | Every audit's phase 2 | | Running a review pass against a worktree containing fixes | Re-running the originating audit in a fresh chat against the worktree | | Reading a review's gap report and editing the originating audit's SKILL.md so the same gap is caught next time | /system-self-improve | | Maintaining cross-skill consistency (boundary tables, README index, README per-skill summary, CLAUDE.md rules, MEMORY.md preferences) when an audit evolves | /system-self-improve | | Updating its own SKILL.md when a meta-weakness is identified | /system-self-improve (recursive case, with stronger confirmation) |

How /system-self-improve is triggered

Three input modes, in priority order. The skill scans for them in this order and uses the first that yields usable input.

1. Review gap report (most common). A reviewer — fresh chat against a worktree, human, or another agent — writes .architect-audits//review-gap-report.md describing what the originating audit failed to catch. The default scan path is .architect-audits/*/review-gap-report.md in the current working directory; an alternative path is supplied via --gap-report=.
2. User-supplied gap description. The user invokes the skill with --gap="" plus --target-skill=. Useful when the user has noticed a gap directly without writing a formal review.
3. Pattern across audit runs. When run with --from-audit-history, the skill scans .architect-audits/*/findings.json across the project for patterns suggesting an audit is systematically wrong: every project hits the same threshold, an audit consistently surfaces partial with no violation (suggesting the threshold is too lenient or the check is too weak), an audit's noGraphify fallback is the dominant code path. This is the most speculative mode and reports candidates as suggestions only.

Where /system-self-improve operates

The skill must run from inside a clone of the architect-playbook repository, or pointed at one via --playbook-path=. It cannot edit a globally-installed copy of a skill in ~/.claude/skills/ because changes there don't survive re-install — improvements must land in the source repository and be re-installed via /install-architect-playbook-locally or /install-architect-playbook-globally.

When the gap report lives in a target project (/.architect-audits//review-gap-report.md) and the playbook clone is elsewhere, the user passes both --gap-report= and --playbook-path=.

Posture: dry-run by default, --apply always prompts

This is the only skill in the playbook with a meaningful --apply mode. Two modes:

• Dry-run (default). Diagnose, locate, propose. Write improvement-plan.md plus a unified diff for every file the plan would touch. Do not modify anything.
• --apply. After the same diagnose-locate-propose cycle, prompt the user with the summary and the diff, ask the single confirmation question, and on yes perform the edits and append a log entry. On no, exit cleanly with the plan still on disk.

There is no flag to skip the confirmation prompt under --apply. That deliberate design forecloses accidental autonomous self-modification — even with --apply, a human approves each application. The skill is opinionated about its own safety.

Usage

/system-self-improve                                          # dry-run; scan default review-gap-report paths
/system-self-improve --apply                                  # dry-run output + confirmation prompt + (on yes) mutation
/system-self-improve --gap="" --target-skill=   # user-supplied gap mode
/system-self-improve --from-audit-history                     # scan .architect-audits/*/findings.json for systematic patterns
/system-self-improve --gap-report=                      # explicit gap-report path
/system-self-improve --playbook-path=                   # operate on a playbook clone elsewhere
/system-self-improve --plan                                   # regenerate improvement-plan.md for an existing run

The skill never accepts any flag that bypasses the confirmation prompt under --apply. It also never operates on a target project's source files; it only reads gap reports and edits the playbook clone.

💡 Pro tip: Create a normal Git worktree for playbook edits before running /system-self-improve. Worktrees are no longer a separate slash command; audits expose them with --worktree, while this meta skill should be run from the checkout you want to edit.

The four stages plus Layer 0

The other audits use four layers organised by concern. This skill's layers are stages of the meta-improvement workflow, walked sequentially. Each stage either advances or surfaces a blocker. The status taxonomy differs from the audits accordingly: every stage records an outcome of advanced, blocked, or skipped, plus a blockerReason when relevant. There is no present | partial | missing | violation here — those concepts apply when grading a target codebase, not when diagnosing the playbook itself.

Layer 0 is informational only.

Layer 0 — Diagnostic snapshot (always written, no pass/fail)

• Playbook version: last commit hash, last commit subject, last-commit timestamp.
• Total skill count, with breakdown: ready, stub.
• Most-recently-modified skills (top 5), oldest skills by modification date (top 5; potentially stale).
• Total check count across all audits (sum of layer-1-through-N tables in every SKILL.md).
• Cross-skill overlap map: which skills surface gaps that other skills also surface (extracted from boundary tables and README per-skill summaries).
• Detected input source(s): list of review-gap-report.md files found, gap descriptions supplied via flags, or audit-history candidates.
• Graphify presence against the playbook itself: yes/no, plus the playbook's own god-node SKILL.md files when the graph is present.
• Existing system-self-improve-log.md entry count: history of past improvements.

Stage 1 — Weakness diagnosis

Read the input gap, classify it, and confirm it warrants action.

| Stage check | Expectation | Blocker signal | | --- | --- | --- | | Input source resolved | A review-gap-report.md is present, OR --gap was supplied with --target-skill, OR --from-audit-history produced at least one candidate. | No usable input. The skill stops and explains how to provide one. | | Gap classifiable | The gap maps to one of: missing check (no check covers this), weak check (a check exists but the detection misses cases), wrong threshold (a default is systematically off), stale detection logic (an ecosystem changed and the audit didn't), cross-skill drift (two skills disagree or duplicate), boundary error (the gap belongs to a skill that doesn't currently own it). | The gap is too vague to classify. The skill asks the user to refine it. | | Originating skill identified | The skill that should have caught the gap is identified — from the gap report's path, from --target-skill, or by matching the gap description to existing audit content. | Multiple skills could legitimately own the gap. The skill surfaces the candidates and asks the user to pick. | | Gap not already covered | The gap isn't already a check in the originating skill (i.e., the audit didn't run, or ran with the wrong filters). | The gap is already covered. The skill reports this and recommends re-running the audit with corrected filters; no edit needed. | | Boundary check | The gap doesn't more naturally belong to a different audit. | The gap belongs elsewhere. The skill recommends moving the proposed change to the better-fit skill. |

Stage 2 — Locate and analyse impact

Find the affected files and assess ripple effects.

| Stage check | Expectation | Blocker signal | | --- | --- | --- | | SKILL.md location | The originating skill's SKILL.md is found in the playbook clone. | Skill missing. The skill stops and asks the user whether the playbook path is correct. | | Affected sections identified | The specific layer table, detection-logic step, threshold list, or implementation-plan block to modify is located, with line numbers. | The proposed change touches more than three sections in one SKILL.md. The skill flags this as a refactor scope rather than a self-improve scope and asks the user to confirm. | | Ripple-effect map | Adjacent files that may need changes are identified: README skill index row, README per-skill summary, CLAUDE.md rules, pre-audit-setup/SKILL.md hook, other audits' boundary tables that mention the originating skill, MEMORY.md if a project-wide preference is implied. | None — ripple effects are surfaced as items in the plan, not as blockers. | | Graphify centrality assessed | When the playbook's own knowledge graph is present (built by running /pre-audit-setup from inside the playbook clone), the originating skill's centrality is recorded. God-node skills (high inbound boundary-table references) get a "high blast radius" tag, which raises the bar for the proposed edit. | None — the centrality assessment informs how cautious the proposed edit should be, not whether to proceed. | | Recursive-self-edit detected | When the originating skill is /system-self-improve itself, the skill flags this and the confirmation prompt downstream becomes the stronger recursive variant. | None — recursion is supported, not blocked. |

Stage 3 — Propose the edit

Generate the minimal, reversible edit and an accompanying plan.

| Stage check | Expectation | Blocker signal | | --- | --- | --- | | Edit is minimal | The proposed diff is the smallest change that closes the gap: add a check at the end of the relevant layer, refine the wording of an existing check, change a threshold default, update a detection-logic line. | The proposed diff exceeds 50 added or modified lines. The skill flags this and recommends manual authoring; some changes are too big for self-improve. | | Edit is reversible | The change can be reverted by reverting a single git commit. The plan records the previous values for any threshold changes and the previous text for any wording changes. | None — reversibility is guaranteed structurally, not by a check. | | Edit preserves SKILL.md structure | Frontmatter intact, layer numbering preserved, established section ordering preserved, boundary table syntax preserved. The two-phase flow convention is preserved. The status taxonomy convention is preserved. The Testing Philosophy across audits is preserved. The four-layer structural convention is preserved. | A proposed edit would break one of these. The skill rejects the proposal and asks the user to clarify the intent — these conventions are foundational. | | No prohibited mutations | The edit does not delete a check, does not delete a skill, does not change the four-layer structural convention, does not change the established two-phase flow or Testing Philosophy across audits, does not edit any target-project files. | A proposed edit would do any of these. The skill rejects the proposal. | | Cross-skill consistency edits included | Plan includes README index row update if a status changes, README per-skill summary update if behaviour changes, boundary table updates in adjacent skills, MEMORY.md update if a new durable preference is implied. | None — these are part of the plan output, not blockers. | | Conventional Commits message drafted | The plan includes a draft commit message: feat: for a new check, fix: for a corrected detection, chore: for a threshold tweak, docs: for prose-only refinement. | None. |

Stage 4 — Apply and verify

Confirm with the user and (on approval) mutate. This stage only runs when --apply is set. In dry-run mode the skill stops after stage 3 with the plan written to disk.

| Stage check | Expectation | Blocker signal | | --- | --- | --- | | Confirmation requested | The skill prints the diff summary and asks: "Apply this improvement plan to the playbook? (yes/no)". When the recursive-self-edit flag from stage 2 is set, the prompt becomes: "This change modifies the meta-improvement skill itself. The next run of /system-self-improve will use the new logic. Continue? (yes/no)" with a follow-on recommendation to commit immediately so the change is bisectable. | The user answers no. The skill exits cleanly; the plan stays on disk for manual application or re-invocation. | | Edits applied atomically | All file changes happen before the log is written. If any single edit fails (file-system error, malformed diff), all changes are rolled back. | A file-system error. The skill rolls back and reports. | | Post-edit verification | Every modified SKILL.md still has valid frontmatter, every modified table is still well-formed Markdown, every cross-reference in boundary tables and README still resolves to an existing file or anchor, the four-layer structural convention is still intact in modified files. | A verification failure. The skill rolls back the changes and reports the inconsistency. | | Log entry appended | A line is appended to system-self-improve-log.md at the playbook root recording: timestamp, gap source, originating skill, classification, summary of changes, and the suggested commit message. The log is append-only — never rewritten. | None. | | Commit suggestion printed | The skill prints the suggested Conventional Commits message and the list of modified files for the user to commit. The skill does not commit on its own — that is a deliberate boundary. | None. |

What this skill does

1. Reads the playbook's own knowledge graph when present. Soft dependency: when graphify-out/graph.json exists in the playbook clone (built by running /pre-audit-setup from inside the playbook), the audit identifies god-node skills and weights ripple-effect analysis accordingly. The skill still runs in full when the graph is absent (it greps for cross-references instead).
2. Confirms the playbook clone. Detects the playbook root by looking for the conventional structure: a top-level README.md mentioning "architect-playbook", a CLAUDE.md with the project rules, a set of /SKILL.md directories. If the current working directory is not a playbook clone and --playbook-path= is not supplied, the skill stops.
3. Resolves the input source in the priority order described above.
4. Walks Stage 1 — Weakness diagnosis and reports the gap classification.
5. Walks Stage 2 — Locate and analyse, including the ripple-effect map and Graphify centrality (when present). Flags recursive self-edits.
6. Walks Stage 3 — Propose the edit, generating the minimal diff plus the cross-skill consistency edits. Verifies the edit doesn't violate the structural conventions.
7. Writes Layer 0 — the diagnostic snapshot to .architect-audits/system-self-improve/snapshot.md and prepends the same content to improvement-plan.md.
8. Writes the proposal to .architect-audits/system-self-improve/:

• `improvement-p

…

Source & license

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

• Author: BenSheridanEdwards
• Source: BenSheridanEdwards/ArchitectPlaybook
• License: MIT

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