{
  "markdown": "# claude-perfectionist\n\nA Claude Code skill that audits and optimizes instruction harnesses — root `CLAUDE.md`, rules, skills, hooks, settings, MCP config, and canonical docs.\n\nOptimizes for **agent reliability per unit of always-on context**, not for the shortest file.\n\n> ⚠️ If you have `claude-md-management` or another CLAUDE.md-related skill installed, it may intercept free-text queries before the perfectionist gets a chance. When in doubt, run `/perfectionist` — it invokes the skill deterministically.\n\n**Try it:**\n- `\"My Claude keeps using yarn but we switched to pnpm months ago\"` — traces the misbehavior to contradicting instructions across your config surfaces, produces a corrected snippet.\n- `\"Audit my CLAUDE.md\"` — full harness sweep: finds contradictions, stale commands, context bloat, missing verification, and tells you the 3–5 changes that matter most.\n- `/perfectionist audit` — deterministic invocation with an explicit mode (`audit | propose | apply`, optional `--json`).\n\n## Quick Start\n\n### Claude Code — plugin (recommended)\n\n```bash\n/plugin install into-the-intraverse/claude-perfectionist\n```\n\n### Claude Code — via marketplace\n\nIf you have the [bazaar](https://github.com/into-the-intraverse/bazaar) marketplace:\n\n```bash\n/plugin marketplace add into-the-intraverse/bazaar\n/plugin install claude-perfectionist@bazaar\n```\n\n### Claude Code — manual (personal)\n\n```bash\ngit clone https://github.com/into-the-intraverse/claude-perfectionist.git\ncp -r claude-perfectionist/skills/claude-perfectionist ~/.claude/skills/claude-perfectionist\n```\n\nAfter installing, ask Claude:\n\n```\nAudit my CLAUDE.md and instruction harness\n```\n\n---\n\n## What It Does\n\nThe perfectionist inspects the full harness surface:\n\n| Surface | What it checks |\n|---|---|\n| Root `CLAUDE.md` | always-on bloat, missing verification, generic instructions, stale commands |\n| `.claude/rules/` | misplaced scoped knowledge, path-scoping opportunities |\n| `.claude/skills/` | overlapping triggers, vague descriptions |\n| `.claude/agents/` | unclear routing boundaries |\n| `.claude/settings.json` | enforcement gaps that should be config, not prose |\n| Hooks | prose-only invariants that should be deterministic |\n| `.mcp.json` | undocumented tool surfaces |\n| `REVIEW.md` | review-only guidance polluting normal sessions |\n| `README`, `docs/` | duplicated content, external-only sources of truth |\n\nIt produces a verdict-first report with:\n- **Verdict** — 2–4 sentences on whether the harness is trustworthy, plus a grade (A–F with human meaning)\n- **Top findings** — max 5, prioritized by severity, in plain language\n- **Recommended changes** — specific, actionable, max 7\n- **Open questions** — only blocker-level\n- **Appendix** — harness map, validation plan, evidence (only when needed)\n- **Machine-readable JSON report** — on request (`--json` or ask for it)\n\nThe report adapts its template to the scenario: default audit, new/empty harness bootstrap, or contradiction debug.\n\n## Modes\n\n| Mode | What it does | When to use |\n|---|---|---|\n| `audit` | Diagnose only. No file changes. | First pass, understanding the current state |\n| `propose` | Diagnose + draft minimum high-leverage changes. | Default. Most common use. |\n| `apply` | Diagnose + edit files directly (repo files only; user-level configs get snippets, never edits). | When you're ready to commit changes |\n\nAsk Claude to use a specific mode:\n\n```\nAudit my instruction harness — audit mode only\n```\n```\nPropose optimizations for my CLAUDE.md\n```\n```\nApply the top changes to my harness\n```\n\nIf you don't specify, the perfectionist defaults to **propose**.\n\nOr use the slash command with an explicit mode: `/perfectionist audit`, `/perfectionist apply --json`.\n\n## Core Philosophy\n\n1. **Evidence over opinion** — findings are grounded in repo files, not abstract best practices.\n2. **Always-on context accounting** — distinguishes real context savings from cosmetic reorganization.\n3. **Right surface for the job** — routes guidance to rules, hooks, skills, docs, or settings instead of piling everything into `CLAUDE.md`.\n4. **Fix before you delete** — fix contradictions and add verification before removing anything. Delete only when content is clearly stale, redundant, or zero-value.\n5. **Verification is non-negotiable** — a harness without concrete verification commands is a critical finding.\n6. **Honest confidence** — when evidence is incomplete, lower confidence instead of raising severity. Distinguish verified defects from likely issues and open questions.\n\n## Repo Structure\n\n```\n.claude-plugin/\n└── plugin.json                       # Plugin metadata\ncommands/\n└── perfectionist.md                  # /perfectionist slash command\nskills/\n└── claude-perfectionist/\n    ├── SKILL.md                      # Core skill (control plane, under 500 lines)\n    └── references/\n        ├── finding-model.md          # Optional finding fields, tags, worked examples\n        ├── examples.md               # Annotated before/after examples\n        └── report-schema.json        # Machine-readable output schema\nfixtures/                             # Fake harnesses for testing the skill\n├── bloated-monorepo/\n├── contradiction/\n└── empty-bootstrap/\n```\n\n`SKILL.md` is the control plane — compact core logic under 500 lines (hook-enforced: warning at 450 lines, block at 500).\n`references/` files load on demand only when the perfectionist needs detailed schemas or examples.\n\n## Example Output\n\nGiven a bloated `CLAUDE.md` with review checklists, unverified commands, and wiki-only references, the perfectionist might produce:\n\n```\n# Verdict\nThe root CLAUDE.md is a 210-line dumping ground. Three review checklists (~80 lines) and\nsix service-specific sections (~60 lines) consume always-on context that should be conditional.\nFix the review-only misplacement and stale external references first.\n\nGrade: C — major cleanup needed\n\n## Top findings\n| Severity | Problem                              | Action                                                    |\n|----------|--------------------------------------|-----------------------------------------------------------|\n| major    | Review checklists in always-on memory | Move into REVIEW.md; add one-line pointer in root         |\n| major    | Service-specific sections in root     | Move into per-service rule files                          |\n| major    | References to tools Claude can't use  | Delete Notion/Slack/Confluence refs or replace with docs  |\n| major    | Routing to agents that don't exist    | Remove unless .claude/agents/ definitions are added       |\n| minor    | LOC-based planning trigger            | Rewrite: plan when ambiguous, irreversible, or broad      |\n```\n\n## Detailed Usage\n\n### First audit\n\nRun an audit first to understand your starting point:\n\n```\nAudit my Claude Code instruction harness. Show me the harness map, \ntop findings, and grade. Audit mode only — don't change anything.\n```\n\n### Targeted optimization\n\nFocus on specific problems:\n\n```\nMy CLAUDE.md is 400 lines. Help me reduce always-on context cost \nwithout losing verification or routing. Propose mode.\n```\n\n### Full apply\n\nWhen ready to commit:\n\n```\nApply the top 3 changes from your audit. Create any new files \n(rules, docs, REVIEW.md) that the extraction plan calls for.\n```\n\n### Monorepo\n\n```\nAudit the instruction harness for the apps/web package. \nCheck for contradictions with the root CLAUDE.md.\n```\n\n### After refactoring\n\n```\nI just restructured my .claude/ directory. Re-audit and check \nthat routing still works and nothing got lost.\n```\n\n## Requirements\n\n- Claude Code with skills support.\n- No external dependencies. The skill is pure markdown + JSON schema.\n\n## Contributing\n\nIssues and PRs welcome. The skill follows its own philosophy:\n- Changes should be grounded in evidence (real failure modes, not theoretical improvements).\n- Keep `SKILL.md` under 500 lines. Push detail to `references/`. A PostToolUse hook warns at 450 lines and blocks at 500.\n- Test changes by running the skill against each directory under `fixtures/`; findings should match the corresponding example in `references/examples.md`.\n\n## License\n\nMIT\n",
  "bytes": 8157,
  "sha": "078fff086c99bcc753f84b457cccd5a287ec8b9e6c19530c23e92fd2d436d21a",
  "repo_slug": "into-the-intraverse/claude-perfectionist",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_into_the_intraverse_claude_perfectionist_692c34b4/readme"
}