Outcome-First Codex Task Writer for a Feature or Bug Request

Turns a raw feature or bug request into a paste-ready Codex task with a goal, constraints, files in scope, definition of done and exact verification commands.

You get: Codex task and open risks and missing information

More like this

The prompt

outcome-first-codex-task-writer-for-a-feature-or-bug-request.md
Act as a senior engineer who writes task prompts for Codex CLI. Turn this request into a task Codex can run with codex exec: {paste your feature or bug request here}

If you do not know the repo's test command or the directories involved, ask me one or two short questions first. Otherwise proceed.

Rules:
- State the goal as an observable outcome, not an activity. Add non-goals so Codex does not widen the change.
- List files in scope as paths. Mark each one "confirmed" or "guess". Never invent paths.
- Write verification as exact shell commands, each with the expected result. If a command is unknown, write "UNKNOWN - confirm before running" instead of guessing.
- Make every done item checkable by a command or a diff.

Output format:
1. Codex task, ready to paste, with these labeled blocks: Goal, Constraints, Files in scope, Definition of done (checklist), Verify (commands in a code block), Report back (what Codex must summarize at the end).
2. Assumptions, as a short list separate from the task.
3. Open risks and missing information, each with a suggested next action.

Example output

AI-written example
## 1. Codex task

### Goal
Exporting invoices to CSV produces one correctly quoted row per invoice, even when the customer name or memo contains commas, quotes, or newlines. Opening the exported file in a CSV parser returns the same number of rows as there are invoices, with the same column count on every row.

Non-goals:
- Do not change the CSV column order or headers.
- Do not touch the PDF export or the invoice API endpoints.
- Do not upgrade dependencies or reformat unrelated code.

### Constraints
- Python 3.11. Use the standard library `csv` module only. No new dependencies.
- Keep the public signature of `export_invoices_csv(invoices, path)` unchanged.
- Keep the diff under about 60 lines, excluding tests.
- Do not edit existing passing tests. Add new ones.

### Files in scope
- `src/billing/export.py` (confirmed: named in the bug report)
- `tests/billing/test_export.py` (confirmed: named in the bug report)
- `tests/billing/fixtures/invoices_special_chars.json` (guess: create it if it does not exist)
- `CHANGELOG.md` (guess: add one line only if the file exists)

### Definition of done
- [ ] `export_invoices_csv` writes rows with `csv.writer` using `quoting=csv.QUOTE_MINIMAL` and `newline=""` on file open. Check with `git diff src/billing/export.py`.
- [ ] A new test fails on the original code and passes after the fix. Check by running it with the fix stashed and again with it applied.
- [ ] New tests cover a comma, a double quote, and an embedded newline in `customer_name` and `memo`.
- [ ] The full billing test suite passes.
- [ ] `git diff --stat` shows changes only in files listed above.

### Verify
```bash
# 1. New regression tests
pytest tests/billing/test_export.py -q -k "special_chars"
# Expected: all selected tests pass, 0 failures

# 2. Full billing suite
pytest tests/billing -q
# Expected: exit code 0, no failures or errors

# 3. Lint
UNKNOWN - confirm before running (ruff? flake8? none?)

# 4. Scope check
git diff --stat
# Expected: only the files listed under "Files in scope"
Report back
  • Root cause in one or two sentences.
  • Files changed, with a one-line reason for each.
  • Output of each verify command, pasted verbatim.
  • Any "guess" path that turned out to be wrong.
  • Anything you noticed but deliberately did not change.

2. Assumptions

  • The repo uses pytest and is run from the repository root.
  • Invoices are dicts or dataclasses with customer_name and memo fields.
  • The current bug comes from joining fields with "," manually rather than using csv.writer.
  • Excel compatibility (BOM, encoding) is out of scope.

3. Open risks and missing information

  • Lint command unknown. Next action: check pyproject.toml or Makefile and fill in step 3 before running.
  • Root cause unverified. The bug may also come from upstream data cleaning. Next action: have Codex reproduce the bug with a failing test before changing code.
  • Fixture path is a guess. Next action: run ls tests/billing/fixtures and correct the path.
  • Downstream consumers. A finance script may rely on the old broken format. Next action: ask the owner before merging.
Generated from this prompt by AI. Your results will vary.

Tips and common edits

Use before handing a vague ticket to Codex. Paste the request text, plus any stack traces or acceptance notes you already have.

Questions about this prompt

More in Codex

Codex Characterization-Test-First Refactor with Verification Handoff

Runs a behavior-preserving refactor in Codex exec. It pins current behavior with characterization tests, refactors in small verified steps inside an allowed scope, and ends with an evidence-based handoff for the merge decision.

Codex CI Failure Triage: Reproduce, Classify, Fix or Hand Off

Guides Codex through reproducing a failing CI job locally, classifying the cause as code, test, environment, or flaky, applying a minimal fix when safe, and producing an evidence-based handoff for anything it cannot resolve.

Codex Exec CI Fixer: Diagnose, Minimal Fix, Rerun, Stop After 3 Attempts

Gives codex exec a non-interactive procedure to diagnose a failing CI output, apply a minimal fix, rerun the checks and stop after three attempts with a clear report.

Codex Read-Only Repo Investigation for a Bug Report

Runs a read-only Codex investigation that maps the relevant code paths, test commands, and likely root causes for a bug report. It ends with a ranked hypothesis table and a go/no-go recommendation before any edits.

Codex Pre-Merge Diff Review with Severity-Ranked Findings

Has Codex review a branch diff against a base ref in read-only mode. It checks correctness, tests, security, and maintainability, and returns evidence-backed findings with severity and a merge recommendation.

Codex Pull Request Review With Comments Ranked by Severity

Has Codex review a pull request and return comments sorted into blocking, should-fix and nit, each with the file and line, the risk, and a suggested change.

Codex Writes an AGENTS.md for This Repository From the Real Setup

Has Codex inspect your repository and write a short, accurate AGENTS.md with the real build, test and lint commands, conventions and boundaries, checked by actually running them.

Agent Run Pre-Mortem and Self-Correction Loop Designer

Designs verification checks, error handling, and a self-correction loop for an agent task before it runs, based on likely failure modes.

Claude Code Root-Cause Bug Investigation with Failing Test and Minimal Patch

Directs Claude Code to reproduce a bug, trace it to a root cause using repository evidence, write a failing regression test, and apply the smallest safe fix. Ends with a verified diff, risks, and next actions.

Cursor Agent Bug Triage: Reproduce, Root-Cause, Fix, and Regression Test

Guides Cursor Agent through reproducing a bug, isolating the root cause with evidence, applying a minimal diff, and adding a regression test, ending with a verification checklist and risks.

Debug an Error From the Message and the Code Around It

Finds the most likely cause of an error from the message and the relevant code, ranks other possible causes, and gives the smallest fix plus a way to prove it worked.

Failing Test First Bug Fix

Reproduces a bug with a failing test, finds the root cause, applies the smallest fix and shows the test passing.