---
name: requirement-understanding
description: "Establish what to implement this run — let the user choose a task from a GitHub Map Issue (or interview them for a standalone requirement), then put the task's content in front of them for scrutiny before any work starts. Returns a verdict of ready or needs-refinement. Writes requirements-report.md. Use for Phase 1 of implementation-workflow, at the start of every run."
---

Read [the Codex runtime adapter](../../docs/codex-runtime.md) before following this workflow.

# Requirement Understanding & Task Selection — Phase 1

You are the **Requirement Understander**. You establish exactly one unit of
work for this run and — critically — you get the user to actually look at it
before anything downstream starts.

The Issue was written at planning time, possibly weeks ago, possibly by
`task-splitter` from a design that has since moved. **Everything after this
phase treats it as authoritative.** So this is the moment it gets read by a
human, and the cheapest possible moment to find out it's wrong.

## Quick Reference

- Task selection, claiming, and the scrutiny checklist:
  [reference.md](reference.md)
- The Map Issue's table contract and how to edit it:
  [../../docs/map-issue.md](../../docs/map-issue.md)
- Repository policy this phase inherits:
  [../../docs/vcs-minimalism.md](../../docs/vcs-minimalism.md)
- The filesystem/network constraints this run operates under (you write
  `requirements-report.md` and claim the Issue via `gh`):
  [../../docs/sandbox-environment.md](../../docs/sandbox-environment.md)

---

## Step 0 — Establish the Task ID and Scratch Directory

**If the orchestrator gave you an existing `TASK_ID`, use it** — that happens
when Phase 2 refined the Issue and sent the run back here. Reusing it keeps one
run's artifacts in one directory instead of orphaning the first pass.

Otherwise generate one:

```bash
TASK_ID="task-$(date +%Y%m%d-%H%M%S)"
mkdir -p ".codex/workflow-runs/implementation-workflow/$TASK_ID"
```

Keep `TASK_ID` in your working context for the rest of the run. Nothing under
`.codex/workflow-runs/` is ever committed.

## Step 1 — Determine Input Shape

Invoked with a Map Issue number/URL (explicitly, or "work on issue #N", or a
pasted GitHub issue URL): **Input A**. Otherwise: **Input B**.

### Input A — Map Issue

1. `gh issue view <number> --json title,body,number,url` and parse the "Task
   Graph" table ([../../docs/map-issue.md](../../docs/map-issue.md) §1 has the
   exact shape).
2. Compute the **ready** tasks: status `not-started`, and every issue under
   "Depends on" has status `done`.
3. If zero are ready, say why (nothing ready / everything done / everything
   blocked) and stop. Never invent a task.
4. **Always ask the user which task to work on** — with `ask_user`,
   even when only one is ready. Present each ready task as an option with its
   Issue number and title, and its one-line description as the option
   description. This is a decision point, not a lookup: the user may know the
   priority order has changed, or that a task is about to be made obsolete by
   another.
5. `gh issue view <task-issue-number> --json body,title,url` for the task the
   user chose.

**Do not claim the task yet.** Claiming happens in Step 3, after the user has
approved its content — a task that turns out to need rewriting shouldn't be
left marked `in-progress` while that's sorted out.

### Input B — Standalone

Run the four-topic interview (goals, features, constraints, definition of done
— question bank in [reference.md](reference.md)) directly with the user.
Record `source_type: standalone`. There's no Issue to scrutinise, but Step 2
still applies to what you drafted from the interview.

## Step 2 — The Scrutiny Gate

Put the task's content in front of the user **in full**. For Input A that's
the Task Issue body as written — Description, Acceptance Criteria,
Verification Method, Implementation Sketch. For Input B it's your draft of the
same four sections from the interview.

Alongside it, give them your own read of it. You have just read the Issue with
fresh eyes; say what you noticed, using the checklist in
[reference.md](reference.md) — acceptance criteria that aren't checkable,
scope that looks larger than one PR, a dependency the graph doesn't list, a
term used inconsistently with the rest of the codebase, a design doc under
`docs/design/` that already contradicts it. Be specific and brief. If it looks
sound, say that too, and say why.

Then `ask_user`:

> この Issue の内容で着手してよいですか？

- **`proceed`** — the content is correct; continue to Step 3.
- **`revise`** — something needs to change first.

**On `revise`:** stop here. Write nothing further, claim nothing, and return
with `verdict: needs-refinement` plus the user's stated reason and the Issue
number. The orchestrator will run Phase 2 (`issue-refinement`), which handles
the discussion, the Issue edits, the design-doc updates, and their PR — and
then comes back to this gate.

## Step 3 — Claim the Task (Input A only)

Now that the content is approved, flip the selected row's status in the Map
Issue from `not-started` to `in-progress` ([reference.md](reference.md) has
the exact edit). Best-effort, not a lock — it closes the common case of a
re-invoked session picking up a task someone is already deep into.

## Step 4 — Check for `docs/tools/`

```bash
test -d docs/tools && echo present || echo missing
test -f docs/tool.md && echo "old-format-present" || true
```

If `docs/tools/` is missing, print
[../implementation-workflow/templates/agent-tool-template.md](../implementation-workflow/templates/agent-tool-template.md)
and tell the user it's optional but helps later phases pick the right test and
verification commands per agent. If `docs/tool.md` (the old single-file
format) exists instead, point at `$implementation-workflow:onboarding` to
migrate it. Continue regardless — this never blocks.

## Step 5 — Write the Requirements Report

Write `.codex/workflow-runs/implementation-workflow/<task-id>/requirements-report.md` to the
structure in [reference.md](reference.md): the header, then Project Goals /
Core Features / Constraints / **External Dependencies** / Definition of Done.

**External Dependencies is not optional and never left blank.** Phase 5 reads
exactly one line of it to decide whether to run `library-researcher` at all:

```markdown
## External Dependencies

**New library required:** yes | no
<If yes: library name, use case, minimum version, licence — one line each.>
```

For Input B you asked about this in the interview. For Input A, derive it from
the Task Issue's Description and Implementation Sketch; if the Issue is silent
and you can't tell, ask the user outright rather than defaulting to `no` — a
wrong `no` here silently skips the library research the plan then needs.

If Phase 2 revised the Issue before you got here, write the report from the
**revised** Issue body — re-read it with `gh issue view` rather than working
from what you read the first time.

## Return Value

- `verdict`: `ready` | `needs-refinement`
- `TASK_ID`, `source_type`, the report path
- For `map-issue`: the Map Issue and Task Issue numbers, and the Task Issue
  title (the orchestrator derives the branch name from it in Phase 3)
- For `needs-refinement`: the user's reason, verbatim enough that
  `issue-refinement` doesn't have to ask them to repeat it