---
name: revising-agents-md
description: Use when a user explicitly asks to capture durable learnings from the current session in AGENTS.md after discovering reusable commands, conventions, validation steps, architecture facts, environment constraints, or recurring gotchas.
---

# Revise AGENTS.md

## Overview

Turn verified session discoveries into concise Codex guidance for future work.
Keep only durable information, place it at the narrowest scope where it
governs work, show the proposed diff, and obtain approval before editing.

## Workflow

1. **Reflect.** Extract candidate commands, conventions, validation steps,
   architecture relationships, environment constraints, and recurring
   gotchas from the current session.
2. **Inspect evidence.** Read the relevant repository files and existing
   `AGENTS.md` or `AGENTS.override.md` chain. Check Git tracking and ignore
   state when deciding whether guidance is shared or personal. Treat a claim
   as verified only when supported by a safe command result, repository file,
   or explicit user confirmation.
3. **Classify every candidate.** Record `candidate`, `keep/exclude`,
   `evidence`, `destination`, and `reason`. Exclude content already documented
   accurately.
4. **Filter aggressively.** Exclude secrets, credentials, personal data,
   unverified claims, generic advice, facts obvious from code, one-off fixes,
   temporary state, and session narrative. Never reproduce a sensitive value,
   even in an exclusion explanation.
5. **Choose the narrowest durable scope.**
   - Codex-home `AGENTS.md`: cross-repository personal preferences, only when
     the user explicitly requests global scope.
   - Repository-root `AGENTS.md`: guidance true for work across the repository.
   - Nested `AGENTS.md`: guidance true only for one package, service, feature,
     or subtree.
   - `AGENTS.override.md`: only when the user explicitly requests replacement
     semantics at that directory.

   Scope follows the code or work governed by the instruction, not the
   directory from which its command must run. A payment-only test command
   belongs in payments guidance even when it says to run from repository root.
6. **Draft grouped diffs.** For each destination, show a one-line reason and
   the exact minimal diff. Prefer one line per concept and preserve the
   existing file's structure.
7. **Request approval.** End with an explicit question asking which proposed
   changes the user wants applied. Do not create or edit a file before the
   user approves its exact destination and content.
8. **Apply and verify.** Edit only approved destinations. Re-read the resulting
   instruction chain, check conflicts and duplication, and verify changed
   commands and paths.

## Required Proposal

```markdown
## Session Learning Review

| Candidate | Decision | Evidence | Destination | Reason |
| --- | --- | --- | --- | --- |
| ... | Keep/Exclude | ... | path or none | ... |

### Update: path/to/AGENTS.md
**Why:** one durable, evidence-backed reason

```diff
+ concise instruction
```

No files were edited. Which proposed changes should I apply?
```

When no candidate qualifies, say so and do not propose an empty file.

## Quick Reference

| Candidate | Decision |
| --- | --- |
| Verified recurring command | Keep at the scope whose work uses it |
| Package-only gotcha | Keep in that package's nested `AGENTS.md` |
| Personal preference | Global only after explicit global request |
| Existing accurate instruction | Exclude as duplicate |
| One-off fix or session history | Exclude |
| Generic best practice | Exclude |
| Unverified claim | Exclude or verify safely first |
| Secret or personal data | Exclude without reproducing the value |

## Example

A session verifies `npm run test:payments` and proves it must run from the
repository root. If only payment work needs that command, propose this in
`services/payments/AGENTS.md`:

```diff
+- Run `npm run test:payments` from the repository root.
```

Do not place it at repository root merely because that is the execution
directory.

## Common Mistakes

- Saving everything because the session was difficult or time-consuming.
- Confusing command execution location with instruction scope.
- Creating an override for ordinary additive guidance.
- Duplicating an instruction that is already accurate.
- Persisting unverified deployment or environment claims.
- Showing a diff without explicitly asking for edit approval.