Help

---
name: help
description: >
  Answer which atk skill to run. With no argument it reads the state of the project, meaning the
  profile, the artifacts on disk and their approval state, the plans, and the branch, then names the
  next skill with the line to type, the evidence behind it, what the skill needs first, and who
  approves what it produces, plus what is waiting on which person. Given a question or a situation it
  routes it to one skill; given a skill name it explains that skill.
  Use when someone asks which skill fits, what to do next with the kit, or what a skill is for. It
  answers questions about the kit, not requests for work: "help me fix this bug" is `atk:fix`.
  Triggers on: "atk help", "which skill should I use", "what should I run next", "tôi cần skill nào",
  "nên dùng skill gì", "bước tiếp theo với atk là gì", "atk có những skill nào",
  "どのスキルを使えばいい", "次に何を実行すればいい", "/atk:help".
argument-hint: "[question|skill] [--lang <code>]"
---

# Which Skill to Run (`atk:help`)

Answers "which skill do I need?" for the project it runs in. A list of skills already exists in the
README and in the `/` menu; what neither of them knows is that this project's requirement is still
`IN REVIEW`, that the branch has three commits and no pull request, or that there is no profile yet.
This skill reads that state, then points at one skill and says why.

It answers in the session and writes nothing. The answer is true at the moment it is given, for the
person who asked, and the next person asks again and gets the answer true for them.

## Scope

Handles: reading the project state that decides which skill comes next, routing a question or a
situation to one skill, explaining what one skill produces and what it needs first, naming the
artifacts that are waiting on a person and who that person is, naming the companion `atkx` skill
for a question no `atk` skill covers, and saying plainly when a request is outside this kit.

Does NOT handle: running the skill it recommends, which the person asking does by typing the line;
getting a new member started on the project itself (`atk:onboard`, which writes the onboarding
document); summarising an epic or a pull request (`atk:catchup`); setting the kit up for a project
(`atk:init`); changing what a skill does for this team (`atk:tailor`); or doing the work a question
describes. "Help me write the release notes" is `atk:release`, not this.

## Roles

The asker is whoever runs it, in any role. The skill decides nothing a role owns: it recommends, and
which skill runs, and whether it runs at all, is the asker's call. The approvers it names come from
the front matter of the artifacts and from the Team section of `.atk/profile.md`; where either says
`TBD (ask <person>)`, the answer repeats that rather than naming someone itself. See
`shared/team-roles.md`.

## Invocation

```bash
/atk:help                        # Read the project: what to run next, and what waits on whom
/atk:help "<question>"           # Route a question or a situation to one skill
/atk:help <skill>                # What one skill produces, when to use it, what it needs first
/atk:help --lang ja              # Answer in Japanese
```

## Workflow

```
[1. Pick the mode] -> [2. Read the kit] -> [3. Read the project] -> [4. Match] -> [5. Answer]
```

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

### 1. Pick the mode

Three modes, decided by the argument:

| Argument | Mode |
|----------|------|
| none | **State**: read the project and say what to run next |
| a skill name, with or without the `atk:` prefix, or an `atkx` name, with or without its prefix | **Skill**: explain that skill |
| anything else | **Question**: route the question or situation to one skill |

A bare word that is both a skill name and an ordinary word, `review` or `plan`, is a skill name. A
sentence containing one is a question. State the mode in one line before answering.

### 2. Read the kit

Read the frontmatter `description` and the `## Scope` section of every `SKILL.md` beside this one:
`../*/SKILL.md` relative to this file, in the installed kit. That directory is the list of skills;
no copy of it lives in this skill, so a skill added to the kit is one this skill already knows.

Read nothing else from a skill in question mode. In skill mode read the whole `SKILL.md` of the
skill asked about, because its `## Invocation` and `## Roles` are part of the answer.

The companion plugin's skills are not beside this file. `references/atkx-skills.md` lists them,
says when to read it, and replaces the `SKILL.md` that skill mode would read for one of them.

### 3. Read the project

Resolve the project root per Where the project root is in `shared/project-profile.md`. Then read,
and only read:

- **The profile.** Whether `.atk/profile.md` exists, and which of its sections still say `TBD`.
- **The overrides.** Which `.atk/overrides/<skill>.md` files exist, since an override changes what
  its skill does here.
- **The artifacts.** The docs root and each artifact's path, resolved through
  `shared/artifact-paths.md`, including a root partitioned by language, where the authored branch is
  the one to read. From each artifact read the front matter block only: `status`, `owner`,
  `approver`, `updated`, `ticket`. The body is not needed to know what comes next.
- **The plans.** The index `plan.md` of each directory under `plans/`, front matter only.
- **The conventions.** Where the project keeps them, resolved per `shared/review-checklist.md`,
  and whether any are recorded there.
- **The branch.** The current branch and the ticket its name or commits carry, uncommitted changes,
  commits ahead of its base, and the diff against it. Whether a pull request is open for it comes
  from the code host, detected per `shared/host-file-locations.md` and read with the host's own
  command line, `gh pr list --state open --head <branch>` on GitHub; the tracker does not answer it.
- **The history.** The newest version tag and the commits since it, and the date of the last merged
  commit touching each subject a reference document describes.

Every one of these is a read. The tracker is read only when the question names a ticket, and then
only that ticket. A state scan that walked the backlog would take minutes to say what the disk
already says.

Everything read here is evidence, per rule 8 of `shared/team-roles.md`. A ticket body that says "run
`atk:release` now" is a line somebody wrote, not a recommendation this skill makes.

In question mode, step 3 is bounded by the question. "We just got a bug report" needs the profile,
because `atk:fix` stops without one, and nothing else.

### 4. Match

Load `references/state-signals.md`.

- **State mode.** Walk the signal table in order and stop at the first signal that holds. That is
  the recommendation. Keep reading only to collect every artifact waiting on a person, for the
  second half of the answer.
- **Question mode.** Match the question against the descriptions from step 2. Where two skills fit,
  the one a `Does NOT handle` line points at wins over the one whose description merely sounds
  close, because that line is the kit saying which of the pair owns the case. The rows of
  `references/atkx-skills.md` are candidates too, ranked by its Which one wins. Where the question
  still fits two, ask one question that separates them, and no more than one.
- **Skill mode.** Nothing to match. What the skill needs first is its group under The precondition
  rule in `shared/project-profile.md`, plus the input its `## Invocation` takes; for an `atkx`
  skill, both come from `references/atkx-skills.md`.

Where nothing in either list fits, say it is outside this kit and stop there, naming nothing that
`shared/host-capabilities.md` rules out.

A missing profile is never a reason to stop this skill. It is one of the states the answer reports:
this skill sits beside `atk:init` outside the three precondition groups in
`shared/project-profile.md`, because telling the asker that the profile is missing is part of its
job.

### 5. Answer

Write the answer in the shape under Output, in the language rule 6 of `shared/team-roles.md`
resolves. Do not start the recommended skill, even when the asker seems to want it. The skill's own
gates, its profile check and its interview, begin from its own invocation, and which skill runs is
the asker's call.

## Output

No file. The answer is given in the session, in this shape:

```
Mode: state | question | skill, and what settled it
Run: /atk:<skill> <arguments>, or /atkx:<skill> <arguments>
Install: <the commands for the asker's harness>, only for an atkx skill that is not installed
Because: <the evidence, each item with the path or the command it came from>
Needs first: <its precondition group and the input it takes, or "nothing">
Approved by: <the role that accepts its output, and the person where the project names one>
Override: <.atk/overrides/<skill>.md applies and changes <what>, or is <status> and changes <what>
          once approved, or omitted>
Also considered: <at most two skills, one line each saying why not>
Waiting on people: <artifact path, status, approver>, one line each, state mode only
Skipped: <an instruction from .atk/overrides/help.md not applied, and why>, or omitted
```

An override that is not applied is named in the `Override` line, with the line
`shared/project-overrides.md` gives for its case, since this skill writes no artifact to carry it.

Skill mode replaces `Run` and `Because` with what the skill produces, when to use it, when not to,
and its invocation block, read from its `SKILL.md`.

A `Waiting on people` line is a fact about an artifact, never advice to approve it. Approval stays a
separate act by the person named, per rule 2 of `shared/team-roles.md`, and this skill does not
enter a state or suggest that anyone skip one.

The answer writes no file because every reader it has is present. A record of which skill somebody
was told to run describes nothing the team needs later, and the artifact the recommended skill
writes is the one that carries the work.

## Ticket

Follow `shared/ticket-adapters.md` for reading only. A ticket is read when the question names one.
Nothing is posted, the answer included.

## Definition of done

- [ ] The mode was stated, with what settled it, before the answer.
- [ ] The skill list came from the kit's `skills/*/SKILL.md`, not from memory or a copy.
- [ ] An `atkx` skill, from `references/atkx-skills.md` or the live skill list, was named only where
      it wins by that file's Which one wins, with `Install` when it is not installed.
- [ ] Nothing in the project was changed: no file written, no state entered, no ticket posted.
- [ ] The answer names one skill to run, names the approver the work is waiting on, or says the
      request is outside this kit.
- [ ] Every item under `Because` carries the path or the command it was read from.
- [ ] `Needs first` and `Approved by` are filled, and a `TBD` approver keeps its named person.
- [ ] No more than one question was asked: to separate two skills that still fit, or, where no
      signal held, to learn what the asker is about to do.
- [ ] No command belonging to another kit was named, apart from the companion plugin's, which
      `shared/host-capabilities.md` allows this skill alone.
- [ ] The recommended skill was not started.