ma-doctor

ma-doctor — audit and improve this agent system's harness

Run this when the user asks to audit / doctor / tune / improve the setup itself — its agents, skills, rules, memory — never for a physics or MadGraph task.

This reshapes the harness. Hardening behavior from a specific past mistake into memory is /ma-reflect's job; this is the structural sibling — it changes the agents, skills, and rules themselves. It is human-gated: recommend first, change only on the user's explicit approval.

Everything the workflow needs is in this skill's folder:

• analyst.md — the analysis brief.
• lessons/ — agent-design principles (lessons/INDEX.md is the list).
• cc-mechanics.md — what Claude Code can and cannot do, so a recommendation is buildable.
• use-case.md — the product goals every change must serve.
• reviewers/ — the five panel briefs.

1. Snapshot

Before anything else, archive the current harness so the whole operation is revertable to the exact pre-doctor state:

root="${CLAUDE_PROJECT_DIR:-$PWD}"
ts=$(date -u +%Y-%m-%dT%H-%M-%SZ)
mkdir -p "$root/.madagents/harness-archive/$ts"
cp -r "$root/.claude" "$root/.madagents/harness-archive/$ts/"

2. Analyze

Dispatch a general-purpose agent with the full text of analyst.md as its instructions. It returns prioritized, evidence-cited recommendations. It is read-only — it analyzes and reports, it never edits.

3. Present and discuss

Relay the recommendations to the user. Each names the weakness and its evidence, the proposed change, the principle it follows, and the risk. Make no change yet. Discuss until the user decides.

4. Approve

Apply only the changes the user explicitly approves. If the user is unsure, stay in discussion.

5. Apply

Apply the approved change to .claude/. When editing an existing agent card, edit its body in place — do not overwrite its description, which may carry a learned routing refinement.

Edit by targeted substitution — never normalise. A change that spans many files (a discipline across the roster, a slate, the wiki) is surgical: write an exact-string or tightly-anchored replacement for the one thing you are changing. Never add a "cleanup" pass — collapsing whitespace, tidying punctuation, stripping empty parens. Each looks harmless alone; together they silently rewrite content that had nothing to do with the change, and the result still parses, so nothing errors.