# agent-instruction-minto-refactor > Source: > Published: 2026-07-20 10:04:57+00:00 | --- | | | name: agent-instruction-minto-refactor | | | description: Refactors AGENTS.md, CLAUDE.md, and agent instruction files into action-oriented Minto/MECE/runtime-sequenced documents while preserving behavior. Use when rewriting agent instructions, cleaning unstructured rule dumps, restructuring user/workspace memory sections, comparing old vs new instructions, or preparing instruction-file evals. | | | --- | | | # Agent Instruction Minto Refactor | | | ## Goal | | | Turn an agent instruction file from a linear rule dump into an executable operating manual. | | | Do not optimize for pretty prose. Optimize for agent behavior under context pressure. | | | ## Inputs | | | Read: | | | - target `AGENTS.md`, `CLAUDE.md`, or agent instruction file | | | - nearby rule files: `.cursor/rules/*.mdc`, `.claude/settings`, project `AGENTS.md`, parent `AGENTS.md` | | | - referenced command, skill, workflow, memory, or routing files | | | - existing eval results if present | | | Preserve behavior unless source files conflict. If conflict exists, choose highest-precedence source and note the conflict. | | | ## Workflow | | | ### 1. Inventory Behaviors | | | Extract every instruction as a behavior: | | | - exact-stop rules | | | - required reads | | | - request classification | | | - routing and command execution | | | - ask/gate/decline rules | | | - project state and save rules | | | - style/personalization rules | | | - tool/knowledge rules | | | - maintenance rules | | | - user/workspace memory rules | | | Mark each as: | | | - **runtime**: affects every response | | | - **route-specific**: applies only to a request type | | | - **maintenance**: setup/sync/update behavior | | | - **memory/fact**: accumulated user or workspace fact | | | ### 2. Make Buckets MECE | | | Use action headings. Prefer: | | | ``` text | | | What [System] Optimizes For | | | How to Apply Rule Precedence | | | How to Stop Before Normal Response | | | How to Load Context | | | How to Classify Requests | | | How to Execute Each Request Type | | | How to Use Knowledge, Skills, and Tools | | | How to Ask, Gate, or Decline | | | How to Use Project State and Save Artifacts | | | How to Adapt Response Style | | | How to Maintain [System] | | | ``` | | | MECE test: | | | - Each rule has one primary home. | | | - Cross-references are allowed, duplicates are not. | | | - Stop rules are not buried in output/style sections. | | | - Slash commands live under classification/execution, not a disconnected appendix unless appendix is clearly reference-only. | | | - Style modifies form only; it never owns behavioral rules. | | | ### 3. Sequence by Runtime Dependency | | | Order sections by what makes the next section easier to execute: | | | 1. Precedence first: resolves conflicts. | | | 2. Stop rules next: decide whether normal flow happens. | | | 3. Context loading next: supplies facts for classification. | | | 4. Classification next: chooses route. | | | 5. Execution next: reads command/workflow files. | | | 6. Knowledge/tools next: supplies allowed references before questions/opinions. | | | 7. Ask/gate/decline next: controls output. | | | 8. Project/save next: controls artifact destination. | | | 9. Style next: modifies form after behavior is known. | | | 10. Maintenance last: not normal runtime. | | | ### 4. Refactor Unstructured Dumps | | | For sections like "learned preferences", "workspace facts", "notes", or sequential logs: | | | - Split stable rules from observations. | | | - Roll stable rules into existing runtime sections. | | | - Group facts by object: user, project, workflow, tool, repo, style, safety, memory. | | | - Convert repeated observations into one rule plus examples. | | | - Keep volatile or timestamped facts in a memory section, not top-level operating doctrine. | | | - Delete nothing silently. If a fact has no home, create a "Needs Routing" subsection and explain why. | | | Example: | | | ``` text | | | Bad: | | | - User likes concise answers. | | | - User hates overexplaining. | | | - User asked for caveman mode. | | | Good: | | | How to Adapt Response Style | | | - Prefer concise answers unless the task requires detail. | | | - Avoid explaining obvious mechanics. | | | - If caveman mode is active, use terse fragment style until user turns it off. | | | ``` | | | ### 5. Preserve Distinctive Persona | | | Do not lose behavioral voice blocks. Preserve or relocate: | | | - role/persona | | | - "do not substitute judgment" rules | | | - questioning philosophy | | | - exact refusal language | | | - exact output formats | | | - examples of fail/pass behavior | | | If a named concept remains referenced, define it. Example: if `journalist/spy rule` appears anywhere, include its definition. | | | ### 6. Rewrite | | | Produce a separate candidate file first, e.g.: | | | ``` text | | | docs/evals/[name]/AGENTS.minto.md | | | ``` | | | Do not replace live `AGENTS.md` until user approves. | | | Use: | | | - action headings | | | - concrete tables for routing | | | - exact output contracts in code blocks | | | - short examples for fragile behavior | | | - explicit precedence rules for conflicts | | | ### 7. Diff For Loss | | | Before saying done, compare old vs new: | | | - Search for distinctive terms from old file. | | | - List removed concepts, not just removed lines. | | | - Pay special attention to persona, memory, style, exact output, and examples. | | | - Re-add anything behaviorally important. | | | Use this prompt internally: | | | ``` text | | | What concept existed in old instructions that a model can no longer learn from new instructions? | | | ``` | | | ### 8. Eval If Possible | | | Create small synthetic tuples before broad claims: | | | - route cases | | | - exact-stop cases | | | - deliverable gate cases | | | - memory/style cases | | | - unstructured fact cases | | | - conflict cases | | | Run old and new with same model/runtime. Separate deterministic checks from human semantic labels. | | | Do not create LLM judges until human labels exist. | | | ## Output | | | Return: | | | - rewritten file path | | | - bucket map: old section -> new section | | | - sequencing rationale | | | - preserved concepts | | | - concepts intentionally removed | | | - eval result or eval plan | | | ## Hard Rules | | | - Do not silently delete weird unstructured facts. | | | - Do not bury exact-stop rules. | | | - Do not let style override behavior. | | | - Do not collapse classify, execute, and output gate into one blob. | | | - Do not claim MECE until every old rule has one primary home. |