Issue authoring for codex agents

Codex is a stronger fit when the issue body gives it explicit boundaries. Claude Code tends to follow broad wording literally; codex tends to infer the most substantive nearby work unless the issue says exactly what may change.

Case study: dashecorp/dashe-website#117 asked for a README typo fix, but PR #118 changed CSS containment on a different page. Review-E flagged the scope mismatch correctly. The lesson is to make the allowed diff shape part of the task, not implied context.

Required Structure

Section	Include	Why
File constraint	`Edit ONLY path/to/file.md. Do not modify any other file.`	Codex respects hard file limits. Soft hints like “work in this area” leave room to redefine the task.
Definition of done	`PR opened with exactly 1 file changed and no more than 5 lines diff.`	A precise PR shape outperforms “push a PR” because it makes off-scope work visibly invalid.
No-op handling	`If no change is needed, exit without opening a PR.`	Prevents codex from finding something else to improve just to produce a PR.
Scope-mismatch escape	`If the requested file does not contain the issue, stop and comment on the issue.`	Keeps the agent from correcting adjacent defects. Off-scope PRs are also blocked by the review gates in rar#155 and rc#396.

Correct Issue Body

## Task

Fix the typo "exmaple" in `README.md`.

## Scope

Edit ONLY `README.md`. Do not modify any other file.

## Definition of done

- PR opened with exactly 1 file changed.
- Diff is no more than 3 changed lines.
- The only intended text change is `exmaple` -> `example`.

## No-op

If `README.md` does not contain `exmaple`, comment on this issue and exit without opening a PR.

Anti-Patterns Observed

Anti-pattern	How codex may read it	Safer replacement
`Fix ANY typo, grammatical issue, or trivially-improvable line.`	Treats “trivially-improvable” as permission to rewrite nearby content.	`Fix ONLY the typo "exmaple" in README.md.`
`Either way, push a PR.`	Pushes something even when the requested change is absent.	`If no requested change is needed, do not open a PR.`
`Read X and improve it.`	Looks for adjacent or more substantive issues.	`Edit ONLY X. Limit changes to the acceptance checklist below.`
`Work in the docs area.`	May touch related files, nav, or examples.	`Edit ONLY docs/foo.md. Do not modify sidebar, config, or generated files.`

Claude Vs Codex Framing

Same intent	Claude-oriented issue	Codex-oriented issue
Fix one typo	`Please fix the typo in README.md and open a PR.`	`Edit ONLY README.md. Replace "exmaple" with "example". Open a PR with exactly 1 file changed and no more than 3 changed lines. If the typo is absent, comment and exit without a PR.`
Improve one sentence	`Read the intro and make it clearer.`	`Edit ONLY docs/intro.md. Change only the second paragraph. Keep the meaning unchanged. Do not edit headings, examples, nav, or config. PR must have exactly 1 file changed.`
Verify no change needed	`Check whether this page needs a grammar fix. Either way, push a PR.`	`Inspect ONLY docs/page.md. If no grammar error is present, comment "No change needed" and do not open a PR.`

When Codex Independence Helps

Use broader codex prompts when the goal is discovery rather than a bounded patch. Exploratory issues benefit from the planning prior that caused the README miss:

## Task

Survey the rig page for layout, copy, and accessibility problems.

## Scope

You may inspect all files needed to understand the page. Open a PR only for low-risk fixes. If the issues need design input, file findings as an issue comment instead.

## Definition of done

- Either a PR with focused fixes and a test plan, or an issue comment listing findings.
- Explain why each changed file was necessary.

Do not use exploratory framing for typo fixes, one-file documentation edits, dependency bumps, or any task where the operator already knows the exact desired diff.