task-scope-and-spec

name

task-scope-and-spec

description

Scope a loose engineering task into a tight, testable spec list. Use when the user gives background for a piece of work and wants the requirements narrowed down before implementation. Trigger phrases include: "scope this", "what are the specs", "what's involved", "what would it take", "what's left for this task", "port this to", "bring this logic to", and "spec this ticket/issue". This skill defines WHAT must be true when the work is done — it does not produce an implementation plan, task ordering, or execution steps. For sequencing the specs into ordered, verifiable tasks, use planning-and-task-decomposition instead.

task-scope-and-spec

Purpose

Turn loose task context — a description, ticket, link, branch, diff, or existing code — into a small, accurate spec list. Gather the relevant context, judge what the change touches, and report only what changes what must be built, finished, or decided.

The output is a decision aid, not a design doc.

Core principle

Narrow, don't expand. Investigate broadly, report tightly. If a detail does not change the implementation target or acceptance criteria, leave it out. The failure mode to avoid is a comprehensive, low-signal architecture summary.

Triage Gate

Before investigating, judge how much context-gathering the task actually needs. The expensive step is investigation (step 2) — skip it when it would tell you nothing new.

• Self-contained (a clear ticket or description that already states the requirements, with no codebase claim to verify): go straight to the spec list from the given text. Do not open files speculatively.
• Code-grounded (references a branch, diff, PR, "what's left", porting to a module, or any spec that depends on the current state of the code): run the full workflow below — here the investigation is the value.

When in doubt, do a shallow investigation first; expand only if what you find changes the specs.

Workflow (internal — do not narrate)

1. Resolve inputs

Identify what context the task references (description, ticket, PR/diff, branch, file path, pasted notes, existing code) and gather what's reachable using whatever tools are available. Stay tool-agnostic — don't assume or require a specific one. If a referenced source can't be reached, note it briefly in the output and proceed; only stall if the missing source would materially change the specs.

2. Investigate

Read enough to understand affected modules, current vs. desired behavior, data shapes/contracts, callers and downstream consumers, existing tests, and similar implementations.

3. Classify task shape

• New work — specs are what must be built.
• In-progress work — specs are what's left to satisfy.
• Porting work — specs are the delta. Compare explicitly: source behavior → target current state → what's missing in target → what must adapt because the target differs (contracts, deps, tests).
• Unclear/stale work — specs are what can be inferred, plus the mismatch.

4. Judge blast radius

Exactly one of local (one module), cross-cutting (several modules/contracts/tests), or structural (shared interfaces, data flow, persistence, architecture boundary).

5. Reconcile intent vs. reality

Tag each requirement's basis: observed (in the context), implied (a reasonable inference), or needs decision. Never present an inference as fact, and never invent a requirement the context doesn't support. Surface a mismatch only when it changes the specs — e.g. the ask is already done, the ticket is stale, or the code implies extra work.

Output contract

Return only this structure, one screen or less:

**Goal:** <one sentence>

**Scope:** <local | cross-cutting | structural> — <one sentence on what it touches>

**Specs:**
- <concrete, testable requirement — what must be true when done>
- ...

**Note:**
- <only if stated intent and observed context diverge>

**Needs a decision:**
- <only if a real blocker remains, phrased as a question>

Omit Note and Needs a decision when not needed.

Specs should: state observable behavior, name contracts only when necessary, include compatibility/test expectations only when they define required confidence, and stay free of implementation steps unless the step is the requirement.

Aim for 3–8 specs. Split the task when it exceeds ~10 specs or when specs span unrelated goals — group by user-visible outcome or contract boundary, and say so.

Anti-patterns (do not)

• No preamble, "here's what I found", or restating the user's background.
• No generic checklists, vague engineering advice, or architecture essays.
• No implementation plan unless explicitly requested.
• No speculative nice-to-haves or duplicate restatements of one requirement.
• No tool names unless the user supplied them or the source itself matters.

Clarifying questions

Ask at most one, and only if the answer would materially change the specs. If enough context exists for a useful partial spec, produce that instead of asking.