autoimprove

Autoimprove

Autonomously improve vault quality by composing existing agents and skills into a score-gated loop. Inspired by Karpathy's autoresearch: modify → evaluate → keep/discard → repeat.

Why This Skill Exists

The vault accumulates entropy — stubs, stale MOC counts, missing wikilinks, mechanical issues. Previously, every improvement required a human prompt. This skill picks the highest-impact improvement, executes it, measures the result, and repeats until the score plateaus or the budget runs out.

The Score

The loop is gated by a deterministic 0–100 quality score. Run commonplace score to see it. For the full dimension breakdown and weights, read references/scoring.md — only needed when you have to interpret per-dimension deltas or explain the score to the user.

Workflow

Important: use commonplace commands, never custom scripts

All analysis is built into the commonplace CLI. Never write Python scripts, shell one-liners, or custom code to parse indexes, check links, count issues, or analyze vault state. The commands output human-readable summaries by default:

• commonplace index → "Indexed 230 files: 93 sources, 114 concepts, 10 MOCs"
• commonplace lint → "Critical: 23 | Improvement: 58 | Suggestion: 71"
• commonplace score → "Score: 78.6/100 (C)" with per-dimension breakdown
• commonplace scope-check → JSON array of violations (empty = clean)

Never pipe JSON to python3 or jq. Reflexes from training are wrong here — there is always a better path:

• Need a quick read of vault state? Use the human-readable default (no --json).
• Need to filter or count? Grep the .wiki/*.jsonl index files directly (they are line-delimited).
• Need structured data for multiple steps? commonplace lint --json > /tmp/lint.json then Read the file.

The --json flag exists for other scripts to consume, not for shell one-liners.

Step 0: Resolve vault path and git checkpoint

Run commonplace vault-path to get the vault path.

If the vault is a git repo, create a safety checkpoint before starting:

cd "$VAULT_PATH" && git add --all '*.md' && git commit -m "autoimprove: checkpoint before run" --allow-empty 2>/dev/null || true

The user can git diff HEAD~1 or git reset HEAD~1 to review/revert.

Step 1: Baseline

Rebuild indexes fresh (full, not incremental) and compute baseline score:

commonplace index
commonplace score

Show the score output to the user directly — it's already human-readable.

Step 2: Plan improvements

Run lint to identify actionable issues:

commonplace lint

Categorize by priority (cheapest and highest-impact first):

1. Mechanical fixes (Tier 2, Haiku): malformed dates, stale MOC counts, duplicate frontmatter entries
2. Pruning (Tier 2, Haiku): remove low-value concept stubs and clean up their references
3. MOC sync (Tier 2, Haiku): MOCs missing source entries that reference them
4. Inline linking (Tier 2, Haiku): source notes mentioning vault pages (concepts, sources, MOCs) without wikilinks, and summary sections with no inline links
5. Stub compilation (Tier 3, main model): fill concept stubs with real definitions — cap at 5 stubs per round, ordered by backlink count descending
6. Semantic audit (Tier 3, main model): read top concept notes by backlinkCount, detect contradictions and synthesis gaps, generate synthesis pages — cap at 2 synthesis pages per round
7. Cross-domain synthesis (Tier 3, main model): only if score ≥ 70. Identify concepts bridging multiple domains and check if recent sources have created connections worth surfacing.

Show the plan:

Found 228 improvable issues:
  Round 1: 5 mechanical fixes (Haiku) + 1 stale MOC (Haiku)
  Round 2: concept linking pass (Haiku)
  Round 3: compile top 5 stubs (main model)
  Round 4: semantic audit — top 10 concepts, identify contradictions + synthesis gaps (main model)
  Round 5: cross-domain synthesis — only if score ≥ 70 (main model)

Step 3: Execute rounds

For each round (default max 3, configurable via $ARGUMENTS as --rounds N):

Pick the highest-priority category with remaining issues and execute. Agent names use the commonplace: prefix:

Task	Agent name
Mechanical fixes	commonplace:wiki-linter
Pruning	commonplace:wiki-pruner
MOC sync	commonplace:wiki-moc-updater
Inline linking	commonplace link (deterministic script — no agent)
Freshness	commonplace:wiki-freshness-checker
Domain management	commonplace:wiki-domain-manager

For the per-round mechanics (what to pass each agent, semantic-audit steps, cross-domain flow), read references/rounds.md. That file also covers the post-loop freshness check.

After each round, re-score:

commonplace score

Show the delta:

Round 1 complete: 43.7 → 52.1 (+8.4)
  integrity:    0.0 → 6.3  (+6.3) — fixed 5 mechanical issues
  consistency: 14.3 → 15.0 (+0.7) — synced 1 stale MOC

Stop conditions (check after each round):

• Score dropped: new_score < previous_score → STOP with warning. Something went wrong.
• Plateau: delta < 0.5 → stop, no more easy wins.
• No issues remain: all fixable issues resolved.
• Budget exhausted: reached max rounds.

Step 4: Report

Show final results:

Autoimprove Complete
  Before: 43.7/100 (F)
  After:  62.3/100 (D)
  Delta:  +18.6

  Rounds executed: 3
  Changes:
    - Fixed 5 mechanical issues (malformed dates, stale counts)
    - Synced 1 MOC (Reinforcement Learning: 9→10)
    - Added 12 concept wikilinks across 8 source notes
    - Compiled 5 concept stubs (ReAct, behavioral cloning, ...)

  Remaining (needs human judgment):
    - 41 concept stubs (say "fill in the stubs" for more)
    - 221 broken wikilinks (path-prefixed, needs systematic fix)
    - 2 potential merge candidates (behavioral cloning + imitation learning)

If score history exists (.wiki/score-history.json), show trend:

Score trend:
  2026-04-04: 38.2
  2026-04-05: 43.7 → 62.3 (this session: +18.6)

Log

Append a summary entry to $VAULT_PATH/.wiki/log.md after the run:

commonplace log --entry "## [$(date +%Y-%m-%d)] autoimprove | Score: {before} → {after}\n- Rounds: N. {Summary of changes}\n"

What This Skill Does NOT Do

• Create new source notes (that's wiki-ingest)
• Create new domains (that's wiki-domain)
• Answer research questions (that's wiki-query)
• Delete notes or rename concepts (needs human judgment)
• Revert changes automatically (git checkpoint is for manual recovery)
• Run wiki-deep-link. Embedding-based candidate surfacing is opt-in only — the user runs commonplace deep-link (and the wiki-deep-link skill) manually when they suspect link-density gaps. Autoimprove sticks to grep-based linking via commonplace link. The concept-density-without-source-links lint check surfaces notes that would benefit from manual deep-link review.

Cost Awareness

Per-round cost profiles live in references/scoring.md. Default priority ordering ensures cheap rounds happen first; the user can cap with --rounds N. Semantic audit runs only at rounds ≥ 4; cross-domain synthesis only if score ≥ 70 and rounds ≥ 5.