satellite-provider/.cursor/skills/new-task/SKILL.md

name, description, category, tags, disable-model-invocation

name	description	category	tags	disable-model-invocation
new-task	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"	build	task feature interactive planning work-items	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)
4. 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