Regular System Self-Review

Decisions

Pending: Review frequency (weekly / triggered / both)?
Pending: Scope — config only or include vault health?
Pending: Health check trigger — /health skill, daily briefing, or both?
Decided: Use YAML frontmatter sync-frequency field per file to control how often docs are checked for freshness

User Tasks

Summary

Opus periodically reviews and improves its own configuration — agents, skills, hooks, rules, CLAUDE.md, and all Claude Code features.

Problem / Motivation

Claude Code evolves fast. New features (agents, skills, hooks, MCP servers, teams, cowork, planning mode) get added regularly. Without periodic review, the Opus setup becomes outdated and doesn’t leverage what’s available.

Proposed Solution

A scheduled self-review routine that audits the entire Opus configuration against current Claude Code capabilities, and proposes improvements.

What Gets Reviewed:

Component	Location	Review Question
CLAUDE.md	`/CLAUDE.md`	Still accurate? Missing new conventions?
Skills	`.claude/skills/`	Any new skills needed? Existing ones working well?
Hooks	`.claude/hooks/` + `settings.json`	Any new hook events useful? Current hooks effective?
Agents	`.claude/agents/`	Agent definitions still optimal? New agent types available?
Rules	`.claude/rules/`	Rules still relevant? Need new path-specific rules?
MCP Servers	`.mcp.json`	New integrations available? Current ones working?
Settings	`.claude/settings.json`	Permissions correct? New settings available?
Architecture	`vault/00_system/`	System docs still match reality?
Docs (all)	`vault/00_system/docs/`, dashboards, etc.	Content still accurate? Needs update? Check `sync-frequency` frontmatter for schedule.

Health Checks (Smoke Tests):

Periodic tests that verify working capabilities haven’t broken. Each capability in capabilities-dashboard gets a health check that Claude can run.

Check	What it tests	How
`/idea` skill	Capture pipeline works	Run skill, verify file created, clean up
`/status` skill	Status overview works	Run skill, verify output
Vault structure	All expected folders exist	Glob for required paths
Git integration	Repo healthy, remote reachable	`git status`, `git remote -v`
Hook scripts	Hooks execute without error	Trigger hook, check exit code
Template integrity	All templates exist and valid	Check `_templates/` files have frontmatter
Atlas access	Can read Atlas vault (once FR-062 done)	Read a known Atlas path
English-only check	All vault and code files are written in English	Scan files for non-English content, report violations
Token efficiency	CLAUDE.md, rules, skills, agents not bloated	Check file sizes, flag verbose or redundant content, propose trimming
Code quality	Codebase stays clean (complements FR-067)	Flag dead code, unused imports, stale configs
Broken wikilinks	No `[[links]]` pointing to non-existent files	Scan vault for wikilinks, verify targets exist
Stale FRs	No feature requests untouched for 30+ days	Check `updated` frontmatter, flag stale ones
Uncommitted changes	No large git diffs piling up without commit	`git status` + `git diff --stat`, warn if excessive
Secrets scan	No API keys, passwords, or .env content in repo	Scan for common secret patterns in tracked files
MCP server health	Configured MCP servers still responding	Check `.mcp.json` entries, verify connectivity
Orphan files	No files unlinked from any dashboard, FR, or doc	Cross-reference all files against links/references
Decision log freshness	No significant decisions missing from `decision-log.md`	Compare recent git history and FR decision checkboxes against log entries
Protected file integrity	No unauthorized changes to `edit-policy: strict` files	Hash or git-diff protected files against known-good state (complements FR-005)

Results feed back into capabilities-dashboard as [passing] / [failing] tags.

Open Questions

No open questions.

Phase Overview

Phase	Description	Status
Phase 1	`/self-review` skill + checklist	—
Phase 2	FR test runner — scan and run all FR test sections	—
Phase 3	Automated audit	—
Phase 4	Self-implementation	—

Phase 1: /self-review Skill + Checklist —

Goal: Create a manual self-review skill that audits the system and produces findings.

File / Feature	Details	Owner	Status
`/self-review` skill	`.claude/skills/self-review/SKILL.md`	mv	—
`/health` skill	Run all health checks, report results	opus	—
Health check definitions	Define checks per capability (see table above)	opus	—
Recurring task detection	Check for patterns that should become skills	opus	—
Tool usage audit	Review current tool/hook/agent usage	mv	—
Knowledge gap check	Flag stale proposals and outdated docs	opus	—
Config audit	CLAUDE.md, skills, hooks, agents, rules, MCP, settings	opus	—
Review checklist template	Standardized checklist for reviews	mv	—
Run schedule	Manually once per week	mv	—

Phase 2: FR Test Runner —

Goal: Systematically scan all FRs for ## Test sections and run them periodically.

File / Feature	Details	Owner	Status
FR test scanner	Scan all FRs in `10_features/` for `## Test` sections	mv	—
Classify tests	Determine which tests are automatable (script) vs manual (user)	mv	—
Run automated tests	Execute automatable tests and write results back to the FR	mv	—
Report manual tests	Surface manual tests that are due to the user	mv	—
Schedule	Run as part of health check or briefing	opus	—

Phase 3: Automated Audit —

Goal: Script that automatically checks for new Claude Code features and compares against current config.

File / Feature	Details	Owner	Status
Doc checker script	Checks Claude Code docs for new features	opus	—
Docs freshness cron	Scheduled task that reviews all system docs (architecture, dashboards, docs/) against actual state. Proposes updates to user — never auto-applies.	mv	—
sync-frequency frontmatter	Each doc gets a `sync-frequency: weekly	opus	monthly
Config comparison	Compare current config against available options	opus	—
Proposal generation	Generate improvement proposals	opus	—
Human approval	Present proposals to user for approval — all doc/config changes require explicit user sign-off	mv	—

Phase 4: Self-Implementation —

Goal: After human approval, implement changes automatically with rollback capability.

File / Feature	Details	Owner	Status
Auto-implement	Apply approved proposals	mv	—
Test changes	Verify the change works	mv	—
Rollback	Revert if tests fail	mv	—

Prerequisites / Gap Analysis

Requirements

Requirement	Description
REQ-1	FR-038 (Claude Manual) — knowledge base for comparison

Current State

Component	Status	Details
Skills infrastructure	done	`.claude/skills/` exists
Claude Code manual	—	FR-038 not yet built

Gap (What’s missing?)

Gap	Effort	Blocker?
Self-review skill	Med	No
Claude Code manual for reference	Med	No (can work without, better with)

Test

Manual tests

Test	Expected	Actual	Last
Weekly review produces improvement report	Report with findings	pending	-

AI-verified tests

Scenario	Expected behavior	Verification method
…	…	…

E2E tests

Scenario	Assertion
…	…

Integration tests

Component	Coverage
…	…

Unit tests

Component	Tests	Coverage
…	…	…

Note: This FR merges the former FR-048 (System Self-Review) and FR-048 (Periodic System Review).

History

Date	Event	Details
2026-02-26	Created	From brain dump
2026-02-27	Renumbered	From FR-013 to FR-012
2026-02-28	Reformatted	Aligned to feature-request template

References

FR-038 (Claude Manual) — the knowledge base, this is the action
FR-067 (Auto Cleaning) — vault/code hygiene, this is config evolution
FR-012 (Periodic System Review) — complementary: docs consistency vs config evolution
FR-005 (Protected Files) — edit-policy frontmatter complements sync-frequency; both use YAML metadata per file
ClaudeClaw Rebuild Prompt — status/health check script pattern (npm run status)
FR-029 (Task Scheduler) — provides scheduled execution runtime

Opus Vault

Explorer