---
name: task
description: |
  Generate a task entry that fully defines a unit of work — motivation,
  boundaries, verification, and observability — so any session can
  implement it without further conversation. Use when asked to "task it",
  "create a task", "write a task file", or when the user describes work
  that should be captured before a sprint.
allowed-tools:
  - Read
  - Write
  - Glob
  - Grep
  - Bash
  - AskUserQuestion
---

# Task Generation

## What this skill produces

A single task entry that fully defines a unit of work — its motivation,
boundaries, verification strategy, and deployment observability — so that
any session can implement it without further conversation.

The entry is written through the **task surface of the environment this
install exposes**. The surface resolution below decides where; the
structure, principles, and precision pass below are identical regardless
of surface.

---

## Task surface (where tasks live in this environment)

Before searching prior work or writing the deliverable, resolve where
tasks live in the current install. Check in this order; use the first
one that exists:

1. **Graph tasks (deployed maxy).** If the `work-*` MCP tools are
   available — `work-list` and `work-get` for prior-work search,
   `work-create` to write the deliverable (it persists `:Task` nodes in
   Neo4j and **owns the identifier — no number scan**) — tasks live in
   the graph. Use those tools. The plugin is `work`, not `tasks` —
   renamed to avoid colliding with Claude Code's built-in `Task*` family.
2. **Local `.tasks/` directory.** If the repo has a `.tasks/` directory
   (optionally with `archive/`, `in-progress/`, `parked/`, `backlog/`
   subdirs and a `LANES.md`), tasks live on disk as
   `.tasks/<N>-<slug>.md`.
3. **Neither.** State this explicitly: "No task surface detected — this
   install has no `work-*` graph tools and no `.tasks/` directory. The
   deliverable will be a written report only."

Throughout this skill, "search prior tasks" and "write the task" mean:
use the resolved surface. Operate inside whatever tree/surface the
install exposes; never hard-code paths.

## Before generating

1. **Determine the next identifier.**
   - **Graph surface:** `work-create` assigns the identifier on write —
     no number scan, no manual numbering. For prior-work search use
     `work-list` / `work-get`.
   - **Local `.tasks/` surface:** scan `.tasks/`, `.tasks/in-progress/`,
     `.tasks/archive/`, and `.tasks/parked/` for the highest existing
     `<N>-<slug>.md` and increment by one. Never invent a numbering
     convention not already in use in this tree.
   - **No surface:** skip — the deliverable is a report.

2. **Read the task tracker, if one exists.**
   - **Local `.tasks/` surface:** read `.tasks/LANES.md` (if present) to
     understand active lanes and file contention; the new task's lane
     assignment and touches must be checked against in-progress work.
   - **Graph surface:** skip — there is no `LANES.md` on a graph surface.

3. **Gather context from the user.** If the user's description is
   ambiguous or missing critical information (what's broken, what success
   looks like, what's excluded), ask via AskUserQuestion — one focused
   question at a time.

## Task structure

Every task contains these sections. Each section has a purpose — if the
purpose can't be fulfilled, the section should say why (e.g., "No
existing logs cover this path — observability must be added as part of
the implementation").

### Title and metadata

```markdown
# Task <N> — <Descriptive title>

**Lane:** <lane from the tracker, or proposed new lane>
**Status:** Open
**Touches:** <precise file paths or graph node types this task will modify>
```

Optional metadata when relevant: `**Depends on:**`, `**Blocks:**`,
`**Sequencing:**`, `**Priority:**`

### Problem

What is wrong, missing, or suboptimal — grounded in evidence. Include log
extracts, reproduction steps, or code references when available. The
problem section answers "why does this task exist?" not "what will we
build?"

### What success looks like

Observable outcomes that define completion. Each criterion is
verifiable — someone reading this section can confirm whether the task is
done without knowing the implementation details.

### Scope boundaries

Two subsections, always paired:

- **In scope** — the specific changes, files, and behaviours this task
  covers. Precise file paths and line ranges when known. **100% coverage
  rule:** if the task delivers a capability that should apply uniformly
  across a known set of surfaces (every brand JSON, every plugin
  manifest, every specialist template, every IDENTITY.md, every CRM
  connector, etc.), the in-scope list must enumerate **every member of
  that set** — not a representative subset. A task that ships the
  capability to 1-of-N surfaces and defers the rest is incomplete by
  construction; the deferred N-1 surfaces become silent regressions
  because the capability is "shipped" in the changelog while most users
  never see it. If the set is genuinely large enough that staged rollout
  is required, the task is split into N sibling tasks, each covering
  one surface end-to-end — never one task covering one surface with the
  others listed as "out of scope" or "future work".
- **Out of scope** — adjacent work that is explicitly excluded. This
  prevents scope creep and makes the boundary between this task and
  future tasks unambiguous. **Out of scope cannot be used to defer
  members of a coverage set** (see 100% coverage rule above) — only
  genuinely adjacent work (different capability, different layer,
  different concern).

### Verification

How the implementation will be proven correct. This section is mandatory
— a task without a verification strategy is incomplete.

The verification section addresses:

- **What is tested** — which behaviours, edge cases, and failure modes
  have automated or manual verification. Not "write tests" but
  specifically what the tests prove.
- **How to reproduce** — for bug fixes, the exact reproduction steps
  that should fail before the fix and pass after. For features, the
  user-visible scenario that demonstrates the new capability.
- **Regression boundary** — what existing behaviour must remain
  unchanged and how that's confirmed (e.g., "existing tests pass",
  "manual smoke test of X").

If the project has no test infrastructure for the affected area, the
verification section must acknowledge this and define what manual
verification is required.

### Observability

How the change will be monitored once deployed. This section is
mandatory — code that cannot be observed in production is incomplete
code.

**Derive it first, adversarially — do not write this section last.**
Observability designed after the fix inherits the fix's blind spots;
designed first, it forces the fix to expose what would otherwise stay
hidden. Before writing prose, name **every way the change can fail**,
and treat the failures that emit *no event and do not reproduce on
demand* as first-class — they are the ones routinely missed. For
**each** failure mode, answer one forcing question and write the answer
in:

> **What signal reveals this failure — and does it fire (a) without
> reproducing the failure and (b) without waiting for unrelated future
> activity?**

The two clauses are the part repeatedly gotten wrong:

- **Presence ≠ adequacy.** A section that merely has "what to log /
  signals / diagnostic path" passes a presence check while still being
  blind. The test is not "is there a section" but "is every failure
  mode answered by the forcing question."
- **Event-driven logging is structurally blind to no-event failures.**
  A failure that triggers no action produces no log line, and re-running
  the code will not surface it. Any such failure REQUIRES a **standing
  check — an independent periodic audit that reconciles expected state
  against actual** — not a log hung on some action. A task that names a
  no-event failure mode but specifies no standing check to detect it is
  inadequate by construction.
- **Verify outcomes, don't log intentions.** "Called the cleanup" is
  not "the resource was freed." Log the *verified* post-condition (a
  measured delta, the resource absent from the live set), and never
  swallow the failure branch.

The observability section addresses:

- **What to log** — the specific events, state transitions, or error
  conditions that must produce log output. Each log point should carry
  enough structured context to diagnose failures without reproducing
  them locally.
- **What signals confirm correct behaviour** — the log patterns,
  metrics, or observable states that indicate the feature is working
  as intended in deployment. An operator reading the logs should be
  able to answer "is this working?" without reading the source code.
- **What signals indicate failure** — the absence patterns, error
  signatures, or anomalous states that indicate something is wrong.
  The absence of an expected log entry is as important a signal as the
  presence of an error.
- **Diagnostic path** — given a failure signal, what targeted grep or
  log query surfaces the cause. On a deployed install, this means
  log-accessible forensics with specific tag/field patterns to search
  for.

If existing observability already covers the change adequately, the
section should state what to look for in existing logs rather than
adding new instrumentation.

### Touches

Precise file paths (local-`.tasks/` surface) or graph node/edge types
(graph surface) the task will modify. Used for lane contention checks
on the local-`.tasks/` surface.

**Documentation triple-target (local-`.tasks/` surface with a
`task-commit-gate` only).** When the task modifies source files under
`platform/` and the repo enforces a `task-commit-gate` hook that
mechanically requires all three documentation targets to be updated
before any commit is allowed, include the applicable targets in the
Touches list so the author scopes documentation work upfront:

- `.docs/` — developer and architecture reference
- `platform/plugins/docs/references/` — user guide shipped to device,
  loaded by admin agent
- `.tasks/LANES.md` — task tracker reflecting what changed

A graph task surface has no `LANES.md`, and the commit-gate hook
governs only on-disk `platform/` commits — on a graph-only install
this paragraph does not apply.

### Dependencies (when relevant)

What must exist or be true before this task can start. If nothing, omit
the section entirely rather than writing "None."

## Principles

- **Evidence before prescription.** The problem section contains
  observed facts. The success criteria describe verifiable outcomes.
  Neither section prescribes implementation steps.

- **Scope is defined by exclusion.** What's out of scope is as important
  as what's in scope. Adjacent improvements, refactors, and "while
  we're here" changes are explicitly out of scope unless the user says
  otherwise.

- **Coverage is defined by enumeration.** When a task delivers a
  capability to a known set of surfaces, the in-scope list enumerates
  every member of that set. Shipping to 1-of-N and deferring the rest
  is incomplete by construction — the deferred members become silent
  regressions. See § Scope boundaries / 100% coverage rule.

- **Testing is not optional.** Every task defines how its implementation
  will be verified. "It works when I try it" is not verification —
  it's anecdote.

- **Observability is not optional.** Every task defines how its
  implementation will be monitored in deployment. If you can't tell
  whether it's working from the logs, the task isn't done. If current
  observability is insufficient to monitor the change, adding
  observability is in-scope for the task.

- **Precision over brevity.** File paths are exact. Line ranges are
  included when known. Error messages are quoted, not paraphrased.
  Vague tasks produce vague implementations.

## Precision pass (mandatory final step before commit)

After drafting the task and before staging it, compress it to ~25% of
its initial length (75% reduction) without losing informative value.
This step is non-optional — tasks are read by every sprint, indexed by
every learning extraction, and paid for in every context window that
loads them. Bloat compounds.

- **Strip:** planning narrative, restated repository context already in
  linked docs, ceremonial framing, prose that paraphrases section
  headings, redundant motivation, and verbose phrasing. Replace
  multi-sentence explanations with single declarative lines.
- **Preserve:** every file path, line range, log extract quotation,
  scope boundary item (in and out), verification criterion,
  observability hook, error signature, dependency, and link. Precision
  data is incompressible.
- **Verify:** re-read the compressed task once. Every detail an
  implementer would need to execute the task without further
  conversation must still be present. If a fact was lost, restore it;
  if it wasn't needed, the original was bloated.

The same "additions require deletions" doctrine that governs
`CLAUDE.md` applies here.

## After generating

1. Confirm the task was written through the resolved surface and that
   the precision pass has been applied.
2. **Local `.tasks/` surface only:** stage and commit the task file with
   message `task: add Task <N> — <title>` and the co-author trailer. If
   `LANES.md` was updated (new lane or touches entry), include it in
   the same commit. Report any lane contention found in `LANES.md`
   (files touched by both this task and an in-progress task).
3. **Graph surface:** the `work-create` write is the commit-equivalent;
   no git step. If a project surface is implied by the work, set it on
   the node at write time.
4. Do not implement. The task entry is the deliverable. Implementation
   is a separate step that goes through the sprint workflow.
