Plan

---
name: plan
description: >
  Turn a piece of work into phases and steps: today's code with file paths, phases that each end in
  something reviewable, steps that leave the tree working and how each is checked, what is out of
  scope, and what is unclear with who must answer. Also reviews a written plan against the
  repository and the request, challenges it with one agent per way it can fail, and records the
  answers to its open questions. Use before starting work, on work somebody else designed, when work
  needs stages but one owner, or when a plan needs checking before anyone builds on it.
  Triggers on: "plan this ticket", "implementation plan", "plan this in phases", "lập kế hoạch",
  "kế hoạch thực thi", "vạch bước", "chia giai đoạn", "làm ticket này thế nào", "実装計画",
  "作業計画", "段階に分けて", "review this plan", "check this plan", "soát lại plan",
  "review kế hoạch", "計画をレビュー", "challenge this plan", "phản biện kế hoạch",
  "計画に反論して", "record the answers in the plan", "ghi câu trả lời vào plan",
  "計画に回答を反映して", "/atk:plan".
argument-hint: "[ticket|design-path|description|plan-path] [--inline] [--challenge] [--answer] [--review] [--comment] [--layer <name>] [--out <path>]"
---

# Implementation Plan (`atk:plan`)

Answers one question: for this work, which files, in which order, checked how. It is the layer
between the design and the code, written by the person who will do the work, for that person and
their reviewer.

Work that needs several days and several reviewable pieces gets several phases, in one plan
directory. Nobody has to chop a piece of work into small tickets before they are allowed to plan it:
finding where the seams are is what this skill is for.

The plan is a draft and acting on it needs nobody's approval. Writing down the steps you intend to
take is drafting, not deciding, so rule 3 in `shared/team-roles.md` does not bite here. What needs
approval is an architectural choice, and choosing between architectures is `atk:design-doc`. When
this skill finds it is comparing approaches rather than sequencing one, it has crossed into that
skill's work and says so.

## Scope

Handles: reading the ticket or description and any design it points at, scanning the repository for
what exists today, cutting the work into phases that each end in something mergeable, sequencing
each phase into steps that leave the tree working, naming what each step touches and how it is
checked, listing what is out of scope and what is still open, reading the written plan back against
the repository it claims things about; under `--review`, doing that reading for a plan somebody
else wrote, under `--challenge`, putting agents over a written plan, and under `--answer`, recording
the answers to its open questions.

Does NOT handle: choosing between approaches or weighing trade-offs, which is `atk:design-doc` and
ends in a decision somebody approves; splitting work across people, which is `atk:breakdown` and
produces owners and parallel lanes; writing the code, which is `atk:implement`; or reviewing that
code once it exists, which is `atk:review`. This skill plans
one person's stream of work, however many phases it takes. Phases are a sequence in time, not a
split between people: every phase in a plan belongs to whoever owns the plan.

| Skill | The question it answers | Read by | Approved by |
|-------|-------------------------|---------|-------------|
| `atk:design-doc` | How should this be built, and at what cost | TL, BrSE/BA | TL |
| `atk:breakdown` | Who does what, in what order, in which lane | PM, TL, the team | PM or TL |
| `atk:plan` | For this work: which phases, which files, which steps, checked how | Implementer, reviewer | TL, lightly |

An epic passes through all three in that order. A self-contained piece of work needs only the third,
whether it takes an afternoon or three weeks. Work that turns out to touch a schema or a public
contract goes back to the first.

## Roles

The Dev who will implement the work writes it and owns it. The Tech Lead reviews it when the plan
turns out to touch a schema, a public contract, or more than one service, which is the same boundary
that sends a ticket back to `atk:design-doc`. Below that boundary the approver line names who would
look if asked; it does not gate the work. Nobody else appears: a plan with an owner column, on a
step or on a phase, has started doing `atk:breakdown`'s work. See `shared/team-roles.md`.

## Invocation

```bash
/atk:plan <ticket>             # Plan from a ticket in the detected tracker
/atk:plan <design-path>        # Plan from an approved design document
/atk:plan "<description>"      # Plan from a description in the prompt
/atk:plan --layer api          # Restrict the scan to one layer when the ticket is confined to it
/atk:plan --inline             # Called by another skill: summarise and hand back, do not stop
/atk:plan --challenge          # After the read-back, put one agent per lens over the written plan
/atk:plan <plan-path> --challenge   # Challenge a plan already written: step 6, the challenge, stop
/atk:plan --out <path>         # Override the default output path

/atk:plan <plan-path> --answer # Record answers to its open questions, then read it back again
/atk:plan <plan-path> --review # Review a written plan: a directory, one phase file, or a PR
/atk:plan <pr> --review --comment   # Post the findings on the pull request carrying the plan
```

`--review` replaces the workflow below rather than extending it: nothing is planned and no plan file
is edited. `references/plan-review-mode.md` holds it. It needs something to read: with no path,
branch, or pull request, list what is in the plan directory resolved per `shared/artifact-paths.md`,
which is `plans/` unless the project says otherwise, and ask which one rather than guessing at the
most recent. Where that directory is absent or empty, say so and stop; there is no question to ask.

`--out` takes a directory on a planning run and a file under `--review`, because that is what each
one writes.

`--comment` means something only under `--review`. On a planning run it changes nothing, and it is
never consent. How `--inline` and `--layer` behave beside `--review` opens
`references/plan-review-mode.md`. `--review` with `--answer` or `--challenge` is refused in one line
before anything is read: a review edits nothing, and both of those edit the plan.

`.atk/profile.md` is useful but not required. Without it the steps can still be sequenced, but the
per-step checks are guesses about commands this project may not have. Follow the Required-soft rule
in `shared/project-profile.md`: continue, and open the artifact with the sentence it gives.

## Workflow

```
[1. Read the request] -> [2. Scan what exists] -> [3. Phases, then steps] -> [4. Check per step]
  -> [5. Write it] -> [6. Read it back] -> [7. Hand off]
```

Before step 1, read `.atk/overrides/plan.md` when it exists, per rule 7 of `shared/team-roles.md`.

Under `--review` the seven steps do not run and `references/plan-review-mode.md` takes their place.
Under `--answer`, `references/answer-mode.md` does, and ends in step 6 and the step 7 recommendation.
Under `--challenge`, `references/plan-challenge.md` runs after step 6; given a plan path, steps 1 to
5 do not run. With both flags, the answers come first, then the challenge, with no recommendation.
The override is read either way: a team that wrote down what it wants from a plan is describing the
same document whether this skill is writing one or reading one. Under `--review` its `## Before`
applies to the pass and its `## After` to the report, since there are no numbered steps to anchor to.

### 1. Read the request

Take the goal and the acceptance criteria from the ticket and the design it links to, and under
`Contract: first` the contract from the reference documents that design names. Copy them; do not
improve them: a criterion invented here is implemented and reviewed as though somebody agreed to it.

Where the request has no acceptance criteria at all, say so and name who must supply them. That gap
belongs to `atk:intake`, and planning around it produces a plan that cannot be checked.

### 2. Scan what exists

Find the code this work will touch and cite it as `path:line`: the modules, the entities, the
endpoints, the screens, the tests that already cover the area. Use the Layers section of
`.atk/profile.md` to know where to look when it is available.

This section is what makes the plan worth reading twice. When the scan genuinely finds nothing, say
that it found nothing and where it searched: on a greenfield feature that is the real answer, and it
reads differently from a scan that never ran.

### 3. Sequence into phases, then into steps

`references/step-ordering.md` holds both rules, because the work is cut twice.

First into phases. A phase ends where the work could stop for two weeks and nothing would be wrong:
not merely something mergeable, which every step is, but something that costs nobody anything if the
next phase never arrives. Work with one such point is one phase, and a one-phase plan is a normal
result rather than a small one.

Then into steps inside each phase. Order them so the tree works after each one, keep each small
enough to have its own check and large enough to be worth naming, and when two changes genuinely
cannot be separated, keep them in one step and say what forces it.

If two approaches are worth comparing at any point here, stop sequencing. Write what the choice is
and what hangs on it, and point at `atk:design-doc`. A comparison of options inside a plan is a
design decision made by whoever happened to be planning.

### 4. Check per step

Every step carries the check that proves it: a command from the Commands section of
`.atk/profile.md`, a test to write or run, or an observation a person can make. A step whose only
check is "the final tests pass" is not a step, it is part of the last one. Merge it and go back to
sequencing: the check is what draws the boundary, so a step without one is a boundary in the wrong
place rather than a step missing a field.

Without a profile, write the check as an intention rather than a command, and mark the artifact as
holding inferred commands, per the Required-soft rule cited under Invocation.

### 5. Write it

Write the plan directory from `references/plan-template.md`: `plan.md` as the index, one
`phase-NN-<slug>.md` per phase, at `status: DRAFT` with a named approver.

When the design gate fires and there is nothing to sequence, no directory is written. Hand back the
fork, the name of whoever owns it, and a stop: there is no path for the caller to take, and an empty
plan directory would look like one.

### 6. Read it back

`references/plan-self-review.md` holds this pass. It runs on every plan this skill writes, `--inline`
included, and again after any rewrite of the files. It runs at most twice per plan, and a rewrite the
person asked for is a new plan that starts the count again, per the cap in that file.

A plan makes claims it cannot check from inside itself, and the table of claims in that file lists
them. Reopen each against the repository. Fix what the repository settles, and turn what it cannot
settle, and the plan depends on, into an open question naming the person who must answer. A claim
with nothing to run against, because the request carried no acceptance criteria or the project has
no profile, is said in the artifact: left unsaid it reads as a claim that passed.

### 7. Hand off

The directory already exists; step 5 wrote it and step 6 corrected it. What differs here is the
ending, and only the caller knows which applies:

| Called as | Ending |
|-----------|--------|
| `/atk:plan` by a person | Print the directory path and the phase list, stop |
| `--inline`, from a skill | Summarise the phases, ask one confirmation, hand back |

Never assume the inline ending. Without the flag, a person asked for a plan and the plan is the
deliverable. Before either ending, say whether a challenge is worth running, per the table in
`references/plan-challenge.md`, which also says how each caller gets it and when none is made.

What `--inline` hands back is the directory path, the ordered phase list with each phase's file, and
every open question step 6 or a challenge raised, and every objection a challenge left `Open`, each
with the person who must answer it and the phase it blocks.
A question the whole plan rests on blocks every phase, and is handed back saying so: it stops the
work rather than holding one part of it.
The caller can work through the phases without re-reading the index, and must not start a blocked
phase before its question is answered. `atk:implement` goes straight from the confirmation into the
work, so a caller told only about the phases would start writing code against a blocked one.

A no at the confirmation is an instruction to revise, not to abandon: rework the plan, run step 6
over what changed, and ask again. This loop has no count, and does not need one: a person drives each
no, so somebody is deciding each time round, which is what the cap inside step 6 has to substitute
for. Only the caller ends the run, and only when the person says to stop rather than to change
something.

After the handback, the plan is the caller's to keep current. Whoever works through the phases sets
each phase file's `status` as it goes; this skill writes them all as `pending` and does not come
back, except under `--answer`, which records an answer per `references/answer-mode.md`. A phase left
at `pending` after its work is done is a plan nobody will trust twice.

## Output

Written to `plans/<YYMMDD-HHMM>-<slug>/` at the project root per `shared/artifact-paths.md`:
`plan.md` plus one file per phase. Both templates are in `references/plan-template.md`.

Phases that are not a straight line get a Mermaid diagram in the index, per
`shared/diagram-conventions.md`. A line of phases does not: the numbered list already says it.

This is one of the three skills that write outside the docs root; that file says why, and what a
project does when it keeps plans somewhere else.

Planning the same work again makes a new directory, because the name carries the time. Do not leave
the old one looking current: set its index `status` to `SUPERSEDED` and link the replacement, per
the rule at the end of `shared/artifact-paths.md`. Two live plans for one piece of work is worse
than none, because each reader picks a different one.

Putting it where the team can see it is `atk:git`, which follows the artifact section of
`shared/finalize-steps.md`: the branch, the commit, and the judgement about whether this one belongs
in a pull request for its approver to read. Under `--inline` this skill does not run that sequence
itself: the directory exists and is committed by the caller, which reaches `shared/finalize-steps.md`
with the code the plan produced.

Under `--review` no plan file is written at all. The findings go to
`docs/derived/reviews/plan-<slug>-<date>.md`, which is derived: safe to delete, and rebuilt by
running the review again. `--out <path>` moves that file as it moves a plan directory.

## Ticket

Under `--review` this section does not run; the `## Ticket` section of
`references/plan-review-mode.md` applies instead, and what it posts goes to the pull request carrying
the plan rather than to a ticket. Under `--inline`, `--answer` and `<plan-path> --challenge` it does
not run either: the caller of `--inline` reaches `shared/finalize-steps.md` with its own consent
prompts later, and the other two edit a plan whose index was offered when it was written. Asking
again for the same ticket is how a consent prompt stops being read.

Follow `shared/ticket-adapters.md`. The index is offered as a comment on the ticket, shown first and
posted on a yes. Do not create sub-tasks from the phases or the steps: they are one person's
sequence, and turning work into tickets for other people is `atk:breakdown`'s call.

## Definition of done

- [ ] The goal and acceptance criteria came from the request, and anything added is marked added.
- [ ] The current-state section cites at least one real `path:line`, or says what the scan searched
      and why it found nothing.
- [ ] Every step names the files it touches and carries a check of its own.
- [ ] Every step declares what it leaves working, and no step declares it leaves the tree broken.
- [ ] Every phase names the reviewable piece it ends with, and a one-phase plan says so plainly
      rather than inventing a second phase.
- [ ] Phase dependencies are stated, and no phase depends on one that comes after it.
- [ ] No owner column on a step or on a phase: the whole plan belongs to one person.
- [ ] No comparison of approaches appears; any that arose was handed to `atk:design-doc`.
- [ ] `status: DRAFT` with a named approver.
- [ ] Every open question names the person who must answer it.
- [ ] Without a profile, the artifact says which commands are inferred.
- [ ] The written files were read back per step 6, and a fix that changed the sequence earned the one
      further pass the cap allows. Where the cap was reached, the plan says which fixes went out
      unverified.
- [ ] Every claim in the table of `references/plan-self-review.md` was reopened by the method that
      file gives, and one that had nothing to run against says so and names who would change that.
- [ ] Nothing the repository could not settle was dropped silently: it is an open question with a
      name, or the plan no longer depends on it.
- [ ] Under `--inline`, the open questions went back with the phase list, each naming the phase it
      blocks.
- [ ] A challenge was recommended or declined with its reason per `references/plan-challenge.md`,
      or, under `--challenge`, none made; one that ran wrote section 7, every kept objection
      `Changed` or `Open`.
- [ ] Under `--answer`, the definition of done in `references/answer-mode.md` holds instead.

Under `--review` these do not apply. `references/plan-review-mode.md` carries its own list, because
the pass fixes nothing and ends in findings rather than in a plan.