to-tasks

Files (1)

• SKILL.md

SKILL.md (first lines)

# To Tasks

Break a plan into sequential tracer-bullet task files, checked into `.tasks/`.

Tasks are **always sequential** — no parallel work. Each task is worked one at a time via `/next-task`, with the context cleared between tasks to keep the agent from getting overwhelmed.

Only one feature at a time — `.tasks/` holds the current feature's plan and is deleted when the feature is done.

## Asking questions

Whenever you put a question to the user — the quiz in step 5, or an ad-hoc question when something is unclear or has drifted (a stale roadmap brief, a plan that conflicts with the code) — ask it and wait for their answer before carrying on.

Drift found in step 2 or 3 is worth a question, but don't ask as you find it: finish grounding the plan, then ask the drift questions alongside step 5's quiz.

## Process

### 1. Check for an existing plan

If `.tasks/` already exists and contains task files, stop and tell the user. Either they need to finish the current feature (via `/next-task`) or explicitly discard it before starting a new plan.

### 2. Gather context

Work from whatever is already in the conversation context. If the user passes a plan/spec/PRD reference (path, URL), read it in full.

**Roadmap stage briefs**: if the input is a stage brief from a `/to-roadmap` roadmap (`docs/roadmaps/<name>/NN-*.md`), also read the roadmap's `ROADMAP.md` and whatever the brief's "Decisions in force" references. The brief's "Proposed tasks" section is the *draft* breakdown for step 4 — but it was written ahead of time, so before trusting it, check every item under the brief's "Re-verify at start" against the actual codebase and adjust the breakdown for drift. In step 5, present what changed relative to the brief rather than inventing from scratch. In step 7, record the stage in `TODO.md` via the `Roadmap stage:` line (see the template) so `/next-task` can mark the stage complete at the finish gate. In step 8, include any `ROADMAP.md` status updates in the plan commit.

### 3. Explore the codebase (optional)

If you have not already explored the codebase, do so to ground the plan in the current code. Task titles and descriptions should use the project's domain glossary vocabulary and respect ADRs in the area you're touching.

### 4. Draft sequential tasks

Break the plan into **sequential tracer-bullet tasks**. Each task is a thin vertical slice that cuts through ALL integration layers end-to-end, NOT a horizontal slice of one layer.

<rules>
- Tasks are ordered — later tasks may depend on earlier ones
- Each task must be small enough to fit comfortably in one focused context window
- Each task delivers demonstrable end-to-end behavior on its own
- Prefer many thin slices over few thick ones
- Do NOT identify parallel work or "blocked by" relationships — the order IS the dependency
</rules>

### 5. Quiz the user

Present the proposed breakdown as a numbered list. For each task, show:

- **Title**: short descriptive name
- **What**: one-line description
- **Key acceptance criteria**: 2-3 bullets

The breakdown is the context the questions need. Then ask:

- Does the granularity feel right? (too coarse / too fine)
- Should any tasks be merged, split, or reordered?
- Is anything missing?

Iterate until the user approves the breakdown.

### 6. Set up the feature branch

Pick a short kebab-case feature name (e.g. `credential-storage`, `add-model-wizard`) — used for the branch and for `TODO.md`'s heading.

Work out the branch name first, whether or not it turns out to be needed:

1. Read the `## Branch naming` section of `docs/agents/git-workflow.md` for a `Pattern:` line. If the file or that section is missing, invoke `/setup-tobico-skills` scoped to branch naming to configure it, then re-read.
2. Substitute the pattern's tokens: `<feature>` = the kebab-case feature name above. If the pattern contains `<handle>`, read the developer handle from `git config --global tobico.handle`; if it's unset, invoke `/setup-tobico-skills` (it will capture and store the handle), then re-read.

Then check where you are:

    git branch --show-current

**On `main`, `master`, or `develop`** — switch to the branch name from above. Done.

**On a non-main branch** — decide whether it's yours to work on or someone else's finished work you're about to squat on:

- **A caller handed you a branching decision** (`/next-stage` does this) — follow it. To stack onto a named predecessor, use the `### Stacking roadmap stages` block under `## Review process` in `docs/agents/git-workflow.md`: it records the project's mechanism, and the branch it creates must still match the pattern above. To branch off the default branch instead, switch there first, then create the branch.
- **No decision was handed down, and this branch already has an open PR** (on GitHub: `gh pr view --json state --jq .state` prints `OPEN`; a non-zero exit means no PR) — it is a finished feature waiting to land, not a workspace. Say so and ask the user: stack a new branch on top (only offer this if the `### Stacking roadmap stages` block exists), branch off the default branch, or stay here deliberately. Wait for the answer.
- **Otherwise** — stay on it. The user picked this branch deliberately.

Never create the new stage's tasks on a branch whose PR is already open — that lands two features in one PR.

### 7. Write the task files

Create `.tasks/` and write:

- `TODO.md` — feature overview and checkbox list of tasks
- `NN-<slug>.md` — one file per task, zero-padded numbers (`01`, `02`, ...)

<todo-template>
# <Feature name>

<1-2 paragraph description of what's being built and why.>

<If planning from a roadmap stage brief, include this line exactly (it is how
/next-task finds the stage to mark complete); omit it otherwise:>
Roadmap stage: [NN: <stage title>](<repo-root-relative path to the stage brief>)

## Tasks

- [ ] 01: <title> — [details](01-<slug>.md)
- [ ] 02: <title> — [details](02-<slug>.md)
- ...
</todo-template>

<task-file-template>
# NN. <Task title>

## What to build

Concise description of this vertical slice. Describe end-to-end behavior, not layer-by-layer implementation.

Avoid specific file paths or code snippets — they go stale fast. Exception: if a prototype produced a snippet that encodes a decision more precisely than prose can (state machine, reducer, schema, type shape), inline the decision-rich parts.

## Acceptance criteria

- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Criterion 3
</task-file-template>

From tobico/tobico-skills, MIT.

More from tobico/tobico-skills