gps-denied-onboard/.cursor/skills/new-task/SKILL.md

---
name: new-task
description: |
  Interactive skill for adding new functionality to an existing codebase.
  Guides the user through describing the feature, assessing complexity,
  optionally running research, analyzing the codebase for insertion points,
  validating assumptions with the user, and producing a task spec with work item ticket.
  Supports a loop — the user can add multiple tasks in one session.
  Trigger phrases:
  - "new task", "add feature", "new functionality"
  - "I want to add", "new component", "extend"
category: build
tags: [task, feature, interactive, planning, work-items]
disable-model-invocation: true
---

# New Task (Interactive Feature Planning)

Guide the user through defining new functionality for an existing codebase. Produces one or more task specifications with work item tickets, optionally running deep research for complex features.

## Core Principles

- **User-driven**: every task starts with the user's description; never invent requirements
- **Right-size research**: only invoke the research skill when the change is big enough to warrant it
- **Validate before committing**: surface all assumptions and uncertainties to the user before writing the task file
- **Save immediately**: write task files to disk as soon as they are ready; never accumulate unsaved work
- **Ask, don't assume**: when scope, insertion point, or approach is unclear, STOP and ask the user

## Context Resolution

Fixed paths:

- TASKS_DIR: `_docs/02_tasks/`
- TASKS_TODO: `_docs/02_tasks/todo/`
- PLANS_DIR: `_docs/02_task_plans/`
- DOCUMENT_DIR: `_docs/02_document/`
- DEPENDENCIES_TABLE: `_docs/02_tasks/_dependencies_table.md`

Create TASKS_DIR, TASKS_TODO, and PLANS_DIR if they don't exist.

If TASKS_DIR already contains task files (scan `todo/`, `backlog/`, and `done/`), use them to determine the next numeric prefix for temporary file naming.

## Workflow

The skill runs as a loop. Each iteration produces one task. After each task the user chooses to add another or finish.

---

### Step 1: Gather Feature Description

**Role**: Product analyst
**Goal**: Get a clear, detailed description of the new functionality from the user.

Ask the user:

```
══════════════════════════════════════
 NEW TASK: Describe the functionality
══════════════════════════════════════
 Please describe in detail the new functionality you want to add:
 - What should it do?
 - Who is it for?
 - Any specific requirements or constraints?
══════════════════════════════════════
```

**BLOCKING**: Do NOT proceed until the user provides a description.

Record the description verbatim for use in subsequent steps.

---

### Step 2: Analyze Complexity

**Role**: Technical analyst
**Goal**: Determine whether deep research is needed.

Read the user's description and the existing codebase documentation from DOCUMENT_DIR (architecture.md including its `## Architecture Vision` section, glossary.md, components/, system-flows.md). Use `glossary.md` to keep the new task's name, acceptance-criteria wording, and component references aligned with the user's confirmed vocabulary; flag the task to the user if the request appears to violate an Architecture Vision principle, do not silently allow it.

**Consult LESSONS.md**: if `_docs/LESSONS.md` exists, read it and look for entries in categories `estimation`, `architecture`, `dependencies` that might apply to the task under consideration. If a relevant lesson exists (e.g., "estimation: auth-related changes historically take 2x estimate"), bias the classification and recommendation accordingly. Note in the output which lessons (if any) were applied.

Assess the change along these dimensions:
- **Scope**: how many components/files are affected?
- **Novelty**: does it involve libraries, protocols, or patterns not already in the codebase?
- **Risk**: could it break existing functionality or require architectural changes?

### 2a. Complexity-Points Estimate

Project policy (per the workspace user-rule on ADO points): aim for tasks at 2–3 points (rarely 5). Tasks at 8 points are high risk; tasks at 13 are too complex and MUST be broken down. The new-task skill enforces this here, before producing a single-file task spec.

Map the Scope/Novelty/Risk profile to a points estimate using this table:

| Profile | Points | Examples |
|---------|--------|----------|
| All three low | **1–2** | One-line config change; trivial CRUD field addition |
| Two low + one medium | **3** | Localized refactor; add one well-understood endpoint |
| One low + two medium, OR all medium | **5** | New small feature touching 2–3 components; integration with a known library |
| Any high, OR two medium + one high | **8** | Cross-cutting concern across 4+ components; integration with an unfamiliar protocol; significant architectural change |
| Two or three high | **13** | New subsystem; unfamiliar tech across the stack; multiple unknown unknowns |

If a relevant LESSONS.md entry biases the estimate (e.g., "auth-related changes historically take 2× estimate"), apply the multiplier and round up to the next discrete point on the scale (1, 2, 3, 5, 8, 13).

### 2b. Routing by Complexity

| Estimate | Default routing | Override path |
|----------|-----------------|---------------|
| **1–5** | Continue this skill at Step 3 (Research) or Step 4 (Codebase Analysis) — see classification below | — |
| **8** | **STOP this skill and recommend handoff to `/decompose @<feature_description>`** (single-component decompose mode if the affected scope fits inside one component, default mode if it does not). The user may override and proceed in `/new-task`, but the override must be explicitly chosen. | C) Proceed in /new-task anyway with the user's acknowledgement that the resulting task is high-risk and may need to be re-decomposed mid-implementation |
| **13** | **STOP this skill — auto-handoff is mandatory.** A 13-point feature cannot be a single task spec. Invoke `/decompose @<feature_description>` (default mode) before writing any task file. Surface the handoff to the user with no override path; this is a hard policy gate. | None — must decompose |

For the auto-handoff path:

1. Render a one-paragraph description of the feature suitable to feed `/decompose` (combine Step 1's verbatim user description with the complexity-points reasoning).
2. Save it to `_docs/02_task_plans/<feature_slug>/feature-description.md` so the decompose skill has a stable input file.
3. Either (a) directly auto-chain into `.cursor/skills/decompose/SKILL.md` in default mode with this file as input, or (b) report the handoff to the user along with the exact `/decompose` invocation and stop. Pick (a) only if the user has explicitly enabled auto-chain across skills (e.g., we are inside an `/autodev` invocation); otherwise pick (b).

### 2c. Research vs Skip Research (only for ≤5 estimates)

Classification (independent of points; runs only when points ≤ 5 and Step 2b chose Continue):

| Category | Criteria | Action |
|----------|----------|--------|
| **Needs research** | New libraries/frameworks, unfamiliar protocols, multiple unknowns | Proceed to Step 3 (Research) |
| **Skip research** | Extends existing functionality, uses patterns already in codebase, straightforward new component with known tech | Skip to Step 4 (Codebase Analysis) |

Present the full assessment to the user:

```
══════════════════════════════════════
 COMPLEXITY ASSESSMENT
══════════════════════════════════════
 Scope:    [low / medium / high]
 Novelty:  [low / medium / high]
 Risk:     [low / medium / high]
 Points:   [1 / 2 / 3 / 5 / 8 / 13]   (project aim: 2–3, rarely 5)
 Routing:  [Continue in /new-task | Hand off to /decompose]
══════════════════════════════════════
 Recommendation: [Research needed | Skip research | Decompose required]
 Reason: [one-line justification, including any LESSONS.md influence]
══════════════════════════════════════
```

**BLOCKING**:
- If points ≤ 5 → ask the user to confirm or override the research recommendation before proceeding.
- If points = 8 → ask the user to choose between hand-off to /decompose (recommended) and continuing in /new-task with explicit risk acknowledgement.
- If points = 13 → STOP and present the handoff plan; do not offer a continue-anyway override.

---

### Step 3: Research (conditional)

**Role**: Researcher
**Goal**: Investigate unknowns before task specification.

This step only runs if Step 2 determined research is needed.

1. Create a problem description file at `PLANS_DIR/<task_slug>/problem.md` summarizing the feature request and the specific unknowns to investigate
2. Invoke `.cursor/skills/research/SKILL.md` in standalone mode:
   - INPUT_FILE: `PLANS_DIR/<task_slug>/problem.md`
   - BASE_DIR: `PLANS_DIR/<task_slug>/`
3. After research completes, read the latest solution draft from `PLANS_DIR/<task_slug>/01_solution/` (highest-numbered `solution_draft*.md`)
4. Extract the key findings relevant to the task specification

The `<task_slug>` is a short kebab-case name derived from the feature description (e.g., `auth-provider-integration`, `real-time-notifications`).

---

### Step 4: Codebase Analysis

**Role**: Software architect
**Goal**: Determine where and how to insert the new functionality, and whether existing tests cover the new requirements.

1. Read the codebase documentation from DOCUMENT_DIR:
   - `architecture.md` — overall structure (the `## Architecture Vision` H2 is user-confirmed intent and must not be violated by the new task without explicit approval)
   - `glossary.md` — project terminology; reuse the user's vocabulary in task names, AC, and component references
   - `components/` — component specs
   - `system-flows.md` — data flows (if exists)
   - `data_model.md` — data model (if exists)
2. If research was performed (Step 3), incorporate findings
3. Analyze and determine:
   - Which existing components are affected
   - Where new code should be inserted (which layers, modules, files)
   - What interfaces need to change
   - What new interfaces or models are needed
   - How data flows through the change
4. If the change is complex enough, read the actual source files (not just docs) to verify insertion points
5. **Test coverage gap analysis**: Read existing test files that cover the affected components. For each acceptance criterion from Step 1, determine whether an existing test already validates it. Classify each AC as:
   - **Covered**: an existing test directly validates this behavior
   - **Partially covered**: an existing test exercises the code path but doesn't assert the new requirement
   - **Not covered**: no existing test validates this behavior — a new test is required

Present the analysis:

```
══════════════════════════════════════
 CODEBASE ANALYSIS
══════════════════════════════════════
 Affected components: [list]
 Insertion points:    [list of modules/layers]
 Interface changes:   [list or "None"]
 New interfaces:      [list or "None"]
 Data flow impact:    [summary]
 ─────────────────────────────────────
 TEST COVERAGE GAP ANALYSIS
 ─────────────────────────────────────
 AC-1: [Covered / Partially covered / Not covered]
       [existing test name or "needs new test"]
 AC-2: [Covered / Partially covered / Not covered]
       [existing test name or "needs new test"]
 ...
 ─────────────────────────────────────
 New tests needed:  [count]
 Existing tests to update: [count or "None"]
══════════════════════════════════════
```

When gaps are found, the task spec (Step 6) MUST include the missing tests in the Scope (Included) section and the Unit/Blackbox Tests tables. Tests are not optional — if an AC is not covered by an existing test, the task must deliver a test for it.

---

### Step 4.5: Contract & Layout Check

**Role**: Architect
**Goal**: Prevent silent public-API drift and keep `module-layout.md` consistent before implementation locks file ownership.

Apply the four shared-task triggers from `.cursor/skills/decompose/SKILL.md` Step 2 rule #10 (shared/*, Scope mentions interface/DTO/schema/event/contract/API/shared-model, parent epic is cross-cutting, ≥2 consumers) and classify the task:

- **Producer** — any trigger fires, OR the task changes a public signature / invariant / serialization / error variant of an existing symbol:
  1. Check for an existing contract at `_docs/02_document/contracts/<component>/<name>.md`.
  2. If present → decide version bump (patch / minor / major per the contract's Versioning Rules) and add the Change Log entry to the task's deliverables.
  3. If absent → add creation of the contract file (using `.cursor/skills/decompose/templates/api-contract.md`) to the task's Scope.Included; add a `## Contract` section to the task spec.
  4. List every currently-known consumer (from Codebase Analysis Step 4) and add them to the contract's Consumer tasks field.

- **Consumer** — the task imports or calls a public API belonging to another component:
  1. Resolve the component's contract file; add it to the task's `### Document Dependencies` section.
  2. If the cross-component interface has no contract file, Choose: **A)** create a retroactive contract now as a prerequisite task, **B)** proceed without (logs an explicit coupling risk in the task's Risks & Mitigation).

- **Layout delta** — the task introduces a new component OR changes an existing component's Public API surface:
  1. Draft the Per-Component Mapping entry (or the Public API diff) against `_docs/02_document/module-layout.md` using `.cursor/skills/decompose/templates/module-layout.md` format.
  2. Add the layout edit to the task's deliverables; the implementer writes it alongside the code change.
  3. If `module-layout.md` does not exist, STOP and instruct the user to run `/document` first (existing-code flow) or `/decompose` default mode (greenfield). Do not guess.

- **ADR cross-check** — runs unconditionally for every new-task in any of the three classifications above:
  1. If `_docs/02_document/adr/` exists, scan every `Status: Accepted` ADR. For each, ask: "would the proposed task either contradict this ADR's `Decision` or materially affect its `Consequences`?"
  2. **Conflict** (task contradicts an Accepted ADR) → STOP and Choose A/B/C: **A)** Re-scope the task to comply with the ADR, **B)** Propose superseding the ADR — the task spec then includes a deliverable to invoke `/plan --adr-only` (or the next `/plan` cycle's Step 4.5) with `Supersedes: ADR-NNN`, and the new task does NOT proceed until that supersede ADR is `Accepted`, **C)** Park the task in `backlog/` with a `Blocked-By: ADR-NNN review` note. Do not silently approve a contradictory task.
  3. **Drift** (task changes assumptions an ADR depends on but does not directly contradict it) → record the affected ADR(s) under a new `### ADR Impact` section in the task spec with `> Affects ADR NNN_<slug>: <one-line summary>`. The implementer surfaces this at code-review Phase 7 (which then classifies it as ADR-Drift if not addressed).
  4. **Aligned** (task implements something an Accepted ADR mandates) → cite the ADR(s) under `### ADR Compliance` in the task spec with `> Implements ADR NNN_<slug>`. Code-review Phase 7 then expects matching evidence in the implemented code.

Record the classification, any contract/layout deliverables, and any ADR cross-check outcomes in the working notes; they feed Step 5 (Validate Assumptions) and Step 6 (Create Task).

**BLOCKING**: none — this step surfaces findings; the user confirms them in Step 5.

---

### Step 5: Validate Assumptions

**Role**: Quality gate
**Goal**: Surface every uncertainty and get user confirmation.

Review all decisions and assumptions made in Steps 2–4. For each uncertainty:
1. State the assumption clearly
2. Propose a solution or approach
3. List alternatives if they exist

Present using the Choose format for each decision that has meaningful alternatives:

```
══════════════════════════════════════
 ASSUMPTION VALIDATION
══════════════════════════════════════
 1. [Assumption]: [proposed approach]
    Alternative: [other option, if any]
 2. [Assumption]: [proposed approach]
    Alternative: [other option, if any]
 ...
══════════════════════════════════════
 Please confirm or correct these assumptions.
══════════════════════════════════════
```

**BLOCKING**: Do NOT proceed until the user confirms or corrects all assumptions.

---

### Step 6: Create Task

**Role**: Technical writer
**Goal**: Produce the task specification file.

1. Determine the next numeric prefix by scanning all TASKS_DIR subfolders (`todo/`, `backlog/`, `done/`) for existing files
2. If research was performed (Step 3), the research artifacts live in `PLANS_DIR/<task_slug>/` — reference them from the task spec where relevant
3. Write the task file using `.cursor/skills/decompose/templates/task.md`:
   - Fill all fields from the gathered information
   - Set **Complexity** based on the assessment from Step 2
   - Set **Dependencies** by cross-referencing existing tasks in TASKS_DIR subfolders
   - Set **Tracker** and **Epic** to `pending` (filled in Step 7)
3. Save as `TASKS_TODO/[##]_[short_name].md`

**Self-verification**:
- [ ] Problem section clearly describes the user need
- [ ] Acceptance criteria are testable (Gherkin format)
- [ ] Scope boundaries are explicit
- [ ] Complexity points match the assessment
- [ ] Dependencies reference existing task tracker IDs where applicable
- [ ] No implementation details leaked into the spec
- [ ] If Step 4.5 classified the task as producer, the `## Contract` section exists and points at a contract file
- [ ] If Step 4.5 classified the task as consumer, `### Document Dependencies` lists the relevant contract file
- [ ] If Step 4.5 flagged a layout delta, the task's Scope.Included names the `module-layout.md` edit
- [ ] If Step 4.5 flagged an ADR conflict, the task is either re-scoped (A), explicitly blocked on a supersede ADR (B), or parked in backlog (C) — never silently bypassed
- [ ] If Step 4.5 flagged ADR drift, the task spec has an `### ADR Impact` section listing the affected ADR(s)
- [ ] If Step 4.5 flagged ADR alignment, the task spec has an `### ADR Compliance` section citing the implemented ADR(s)

---

### Step 7: Work Item Ticket

**Role**: Project coordinator
**Goal**: Create a work item ticket and link it to the task file.

1. Create a ticket via the configured work item tracker (see `autodev/protocols.md` for tracker detection):
   - Summary: the task's **Name** field
   - Description: the task's **Problem** and **Acceptance Criteria** sections
   - Story points: the task's **Complexity** value
   - Link to the appropriate epic (ask user if unclear which epic)
2. Write the ticket ID and Epic ID back into the task file header:
   - Update **Task** field: `[TICKET-ID]_[short_name]`
   - Update **Tracker** field: `[TICKET-ID]`
   - Update **Epic** field: `[EPIC-ID]`
3. Rename the file from `[##]_[short_name].md` to `[TICKET-ID]_[short_name].md`

If the work item tracker is not authenticated or unavailable, follow `.cursor/rules/tracker.mdc` before continuing. Only if the user explicitly chooses `tracker: local`:
- Keep the numeric prefix
- Set **Tracker** to `pending`
- Set **Epic** to `pending`
- The task is still valid and can be implemented; tracker sync happens later

---

### Step 8: Loop Gate

Ask the user:

```
══════════════════════════════════════
 Task created: [TRACKER-ID or ##] — [task name]
══════════════════════════════════════
 A) Add another task
 B) Done — finish and update dependencies
══════════════════════════════════════
```

- If **A** → loop back to Step 1
- If **B** → proceed to Finalize

---

### Finalize

After the user chooses **Done**:

1. Update (or create) `DEPENDENCIES_TABLE` — add all newly created tasks to the dependencies table
2. Present a summary of all tasks created in this session:

```
══════════════════════════════════════
 NEW TASK SUMMARY
══════════════════════════════════════
 Tasks created: N
 Total complexity: M points
 ─────────────────────────────────────
 [TRACKER-ID] [name] ([complexity] pts)
 [TRACKER-ID] [name] ([complexity] pts)
 ...
══════════════════════════════════════
```

## Escalation Rules

| Situation | Action |
|-----------|--------|
| User description is vague or incomplete | **ASK** for more detail — do not guess |
| Unclear which epic to link to | **ASK** user for the epic |
| Research skill hits a blocker | Follow research skill's own escalation rules |
| Codebase analysis reveals conflicting architectures | **ASK** user which pattern to follow |
| Complexity exceeds 5 points | **WARN** user and suggest splitting into multiple tasks |
| Work item tracker MCP unavailable | Follow `.cursor/rules/tracker.mdc`; do not continue in local mode unless the user explicitly chooses it |

## Trigger Conditions

When the user wants to:
- Add new functionality to an existing codebase
- Plan a new feature or component
- Create task specifications for upcoming work

**Keywords**: "new task", "add feature", "new functionality", "extend", "I want to add"

**Differentiation**:
- User wants to decompose an existing plan into tasks → use `/decompose`
- User wants to research a topic without creating tasks → use `/research`
- User wants to refactor existing code → use `/refactor`
- User wants to define and plan a new feature → use this skill