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