intake git:20260918.dcc08e9A

Immutable. This exact content is served forever at /api/v1/blob/1c83f9e5338d68b8.

---
name: intake
description: >
  Turn a raw stakeholder or client request into reviewable requirements: context, user stories,
  acceptance criteria, out-of-scope list, open questions, and the person who must answer each one.
  Use when a request arrives as a chat message, a meeting note, a mail, or a one-line ticket and
  the team cannot start work from it yet.
  Triggers on: "intake", "requirement", "làm rõ yêu cầu", "phân tích yêu cầu", "user story",
  "acceptance criteria", "要件定義", "要求整理", "clarify this request", "turn this into stories",
  "/atk:intake".
argument-hint: "[request-file|ticket-id|text] [--interview|--no-interview] [--lang <code>] [--out <path>]"
---

# Requirement Intake (`atk:intake`)

Converts an unstructured request into a requirement artifact that a Dev can estimate, a QA can
test, and a stakeholder can approve. The output records what was asked, what was assumed, and what
is still unanswered, with a name against every open question.

## Scope

Handles: reading the raw request, scanning the codebase for what already exists, splitting the
request into user stories, writing testable acceptance criteria, listing non-goals, and collecting
open questions with an owner each.

Does NOT handle: estimating effort (`atk:estimate`), technical design (`atk:design-doc`), task
assignment (`atk:breakdown`), or deciding priority and scope. Those belong to the PM and the
stakeholder; this skill records their decision, it does not make it.

## Roles

PM and BrSE/BA lead. Tech Lead reviews feasibility. QA reviews whether each acceptance criterion is
testable. See `shared/team-roles.md`.

## Invocation

```bash
/atk:intake <request-file>        # Read a meeting note, mail export, or spec fragment
/atk:intake "<pasted request>"    # Read the request straight from the prompt
/atk:intake <ticket-id>           # Pull the request from the detected tracker
/atk:intake --no-interview        # Draft from the request alone, mark every gap OPEN
/atk:intake --lang ja             # Write the artifact in Japanese
/atk:intake --out <path>          # Override the default output path
```

## Workflow

```
[1. Read request] -> [2. Scan repo] -> [3. Interview gaps] -> [4. Draft stories] -> [5. Review gate]
```

### 1. Read the request

Quote the request verbatim into the artifact before interpreting it. Interpretation drifts; the
quote does not.

### 2. Scan the repository

Find what already exists: matching features, similar endpoints, existing entities, prior
requirement docs. A request is often a change to something, not a new thing. Cite file paths.

### 3. Interview the gaps

Ask only what neither the request nor the repository answers, one question at a time, with two to
four concrete options and a recommendation. Stop at the first material answer per topic. Skip this
step under `--no-interview` and mark each gap `OPEN` with a suggested owner.

### 4. Draft stories and criteria

One story per user-visible outcome. Acceptance criteria are `Given / When / Then` and each one must
be checkable by a person who did not write it. Vague criteria such as "works correctly" or "is fast"
are rejected: replace them with a number, a state, or a visible result, or move them to open
questions.

### 5. Review gate

Set `status: IN REVIEW` and name the approver. Do not mark anything `APPROVED` on the team's behalf.

## Output

Written to `docs/records/requirements/<ticket-or-date>-<slug>.md` per `shared/artifact-paths.md`. Sections:
front matter, original request, context and current behavior, user stories with acceptance criteria,
out of scope, assumptions, open questions with owners, and impacted areas with file paths.

## Ticket

Follow `shared/ticket-adapters.md`. Offer to open one epic plus one issue per story. Show the list
first; create nothing without a yes.

## Definition of done

- [ ] Every story has at least one testable acceptance criterion.
- [ ] Every assumption is labelled as an assumption, not stated as a fact.
- [ ] Every open question names the person who must answer it.
- [ ] The out-of-scope list is non-empty, or its emptiness is explained.
- [ ] Nothing is marked `APPROVED` without the approver actually saying so.