--- 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 Invoked by the admin agent directly. ## 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/-.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 `-.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 — **Lane:** **Status:** Open **Touches:** ``` 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 — ` 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.