/dr-optimize

Overview

/dr-optimize audits the entire Datarim framework — skills, agents, commands, templates — and identifies problems: unused components, duplicates, oversized files, broken references, and outdated documentation counts. It generates a report with proposals ranked by risk and applies only the changes you approve.

Usage

/dr-optimize
/dr-optimize project
/dr-optimize framework

When to Run

• After every 5-10 completed tasks
• After /dr-addskill to check for overlaps with existing skills
• When skills stop triggering or Claude seems to forget instructions
• When /dr-archive Step 0.5 (reflection) suggests it

What It Does

1. Determine Scope — the initialized project's client discovery directories (.agents/, .claude/, .cursor/) and .datarim-runtime/, with ownership reported separately; or, for an explicit framework audit, the Datarim source repository (changes proposed as a pull request). Global scope is not supported.
2. Full Inventory — builds a complete table of all skills, agents, commands, and templates with file sizes, descriptions, and cross-references.
3. Dependency Graph — maps commands to agents, agents to skills, and skills to skills. Identifies orphaned components.
4. Issue Detection — checks for: unused skills/agents, oversized files (skills: warn over 300 lines, split over 400; agents: warn over 120, split over 180), duplicate coverage (over 70% overlap), stale descriptions, broken references, doc count mismatches, description-budget violations, selective-loading candidates, and Diátaxis docs drift (soft warning).
5. Report — presents findings with framework health status (GOOD, NEEDS ATTENTION, BLOATED), issue counts by severity, and proposals ranked from low to high risk.
6. Approval Gate — asks which proposals to apply (all, none, or specific numbers). Applies only approved changes.
7. Sync Documentation — updates AGENTS.md, README.md, and dr-help.md with correct component counts and tables, and logs changes in datarim/history/evolution-log.md.

Arguments

Optional. project (default: the initialized project) or framework for an explicit audit of the Datarim source repository. Global/user scope is not supported.

Output

Full audit report with dependency graph, optimization proposals, applied changes summary, and updated documentation.

Example Session

> /dr-optimize

=== OPTIMIZATION REPORT ===

Framework Health: NEEDS ATTENTION
Components: 19 agents, 79 skills, 28 commands, 28 Markdown templates plus supporting assets
Total lines: 4,250
Description budget: 5,200 / 8,000 chars (65%)

Issues found: 4
  1. [Low] Unused skill: legacy-deploy.md (no agent references)
  2. [Low] Stale description: security.md (content diverged)
  3. [Medium] Duplicate coverage: testing.md and qa.md (72% overlap)
  4. [Medium] Doc count mismatch: README says 60 skills, disk has 67

Proposals:
  1. prune-skill: Remove legacy-deploy.md
  2. fix-description: Update security.md description
  3. merge-skills: Combine testing.md into qa.md
  4. sync-docs: Update AGENTS.md counts

Which proposals should I apply? (all / none / 1,2,4)

Related Commands

• /dr-addskill — adding new components
• /dr-archive — Step 0.5 reflection may trigger optimization suggestion
• /dr-help — verify command list after changes

Reporting the result

Apply Human Outcome Reporting before a human-facing update or result. Explain the user-visible outcome, the original conditions, checks and evidence, and open limitations. A stage result does not mean the entire task is complete. Keep exact protocols and technical records intact. To explain again without continuing work, use /dr-explain.