--- name: scorpio-next-task description: Inspect product-grounding artifacts, current implementation, and backlog state to choose one bounded next slice and emit canonical planning artifacts for scorpio-task-plan. --- # Product Analyze Next Task Use this skill when the operator wants Scorpio to decide what should be built next from product artifacts and current code state without manually choosing feature, bug, or improvement first. This is an analysis-only producer. It must not write `{docs.tasks}/**`. Its job is to choose one bounded slice, explain why it won, prove it is not already covered, and emit the planning artifacts that let `scorpio-task-plan` create the actual task pack. ## Required Inputs Read: 1. `docs/PROJECT-CONTEXT.md` when present, or enough local project structure to avoid guessing 2. Active task files under `{docs.tasks}/` 3. Recent completion reports and done tasks under `{docs.tasks}/done/` 4. Relevant planning docs under `{docs.planning}/` 5. Current implementation code for the surfaces under consideration Also inspect Scorpio task lifecycle state when that control-plane data is available in the invoking environment. ## Product Source Discovery Prefer an explicit source manifest when available. ### Primary manifest Use `{docs.planning}/PRODUCT-SOURCES.json` by default. If the runtime provides an override path, treat that manifest as authoritative for the run and report the override in the selection summary. ### Fallback discovery If no manifest exists, fall back to convention-based discovery: 1. Load `{docs.planning}/PRD.md`, `MVP-SCOPE.md`, and `IMPLEMENTATION-PLAN.md` when present 2. Load advisor artifacts when `docs/advisor-reports/` exists 3. Load common product-reference directories when present, such as `design/`, `designs/`, `mockups/`, `screenshots/`, and `references/` A missing manifest is not an error by itself. The skill must explicitly report whether it used a manifest or fallback discovery. ## Goals 1. Compare intended product behavior against current implementation. 2. Generate several bounded candidate slices rather than jumping to the first idea. 3. Reject candidates already covered by active or recently completed work. 4. Select the highest-value single-session slice that can safely route into task generation. 5. Emit durable planning artifacts plus a normalized `TASK-PLAN-HANDOFF.json`. ## Required Outputs Write: 1. `{docs.planning}/NEXT-TASK-CANDIDATES.json` 2. `{docs.planning}/NEXT-TASK-SELECTION.md` 3. `{docs.planning}/TASK-PLAN-HANDOFF.json` If the runtime provides a run-local decisions directory such as `.scorpio/runs//decisions/`, mirror the candidate and selection artifacts there after writing the canonical planning files. ## Workflow ### Phase 1: Inventory Build a grounded source list before deciding anything. Capture: - which product artifacts were used - which code surfaces were inspected - which backlog inputs were checked - whether selection used an explicit manifest or fallback discovery Stop and report if there is not enough artifact evidence to make a grounded selection beyond generic code inspection. ### Phase 2: Candidate generation Generate multiple candidate slices by comparing: 1. intended behavior from product artifacts 2. actual behavior in code 3. backlog coverage from active and recently completed tasks Each candidate must be a bounded slice. Favor: - missing or fake core interactions before polish - user-flow gaps before aesthetic drift - artifact-backed behavior gaps before speculative ideas - slices that unlock follow-on work - work that can be implemented and verified in one focused session Reject: - wording-only or tiny polish changes - purely aesthetic drift without behavior impact - obvious epics that need multiple sessions - work already covered by pending or in-progress tasks - work recently completed unless the evidence shows it is still incorrect or incomplete ### Phase 3: Duplicate screening For every serious candidate, compare it against: 1. root task files in `{docs.tasks}/*.md` 2. Scorpio task lifecycle state when available 3. recent completions under `{docs.tasks}/done/` Mark each candidate with a duplicate status such as: - `clear` - `duplicate_existing_task` - `recently_completed` - `needs_operator_review` If a materially equivalent task already exists, do not emit a handoff for that candidate. Record the matching task IDs or report paths and move to the next viable candidate. If all strong candidates are already covered, stop with a no-op result: - still write `NEXT-TASK-CANDIDATES.json` - still write `NEXT-TASK-SELECTION.md` - do not fabricate a new task slice just to keep the workflow moving ### Phase 4: Selection Rank the non-duplicate candidates and choose exactly one slice. The selection must answer: 1. Why this candidate outranked nearby alternatives 2. What user-visible outcome it unlocks 3. What evidence justified the selection 4. What verification should prove the slice complete If the best candidate is too large, split it to the smallest material slice and only continue if that slice remains coherent and meaningful. If no bounded slice exists, fail rather than emitting an epic. ### Phase 5: Artifact emission Write the required artifacts using the contracts below. ## Artifact Contracts ### 1. `{docs.planning}/NEXT-TASK-CANDIDATES.json` Include: - `version` - `generated_at` - `source_skill` - `selection_mode` - `selected_candidate_id` - `candidates` Each candidate should include: - `id` - `title` - `classification` - `priority_score` - `boundedness` - `duplicate_status` - `why_selected` or `why_rejected` - `matching_task_refs` when duplicate-screened - `evidence` ### 2. `{docs.planning}/NEXT-TASK-SELECTION.md` Required sections: 1. Selection summary 2. Why this outranked nearby candidates 3. Evidence used 4. Duplicate checks performed 5. Intended user-visible outcome 6. Expected verification Also state: - whether a manifest or fallback discovery was used - whether control-plane backlog state was available - whether the run ended in `selected`, `duplicate-covered no-op`, or `unbounded failure` ### 3. `{docs.planning}/TASK-PLAN-HANDOFF.json` Use the normalized operational contract consumed by `scorpio-task-plan`. Required top-level fields: - `source_skill` - `source_artifact` - `feature_name` - `scope_summary` - `slices` - `constraints` - `test_strategy` Required slice fields: - `title` - `type` - `estimate` - `description` - `files_to_modify` - `acceptance_criteria` - `depends_on` Optional top-level field: - `metadata` The selected candidate becomes the sole slice input for task generation. ## Guardrails 1. Do not write `{docs.tasks}/**`. 2. Do not choose from existing tasks as the primary candidate pool; use them for duplicate prevention. 3. Do not emit more than one selected slice. 4. Do not route unbounded or weakly evidenced work into `TASK-PLAN-HANDOFF.json`. 5. Do not guess at product intent when artifact evidence is missing; call out uncertainty. ## Failure Behavior ### Duplicate-covered candidate set This is a no-op outcome, not a hard failure. Required behavior: - preserve the candidate and selection artifacts - explain which existing tasks or reports already cover the work - do not emit a new handoff that would trigger duplicate task generation ### Unbounded selection This is a hard failure. Required behavior: - preserve the candidate and selection artifacts - explain why the candidate could not be reduced to a safe slice - do not emit a handoff that would force downstream guessing ### Invalid handoff JSON This is a hard failure. Required behavior: - preserve the analysis artifacts - identify the missing or invalid fields - do not ask `scorpio-task-plan` to infer the schema ## Verification Checklist Before finishing, confirm: 1. The chosen slice is bounded to one focused implementation session. 2. The candidate clearly outranks nearby alternatives using artifact-backed evidence. 3. Duplicate checks covered tasks, lifecycle state when available, and recent completions. 4. The selection summary and handoff tell the same story. 5. No task files were created directly by this skill. ## Example Triggers - "Look at the specs and the current app and tell me the next real thing we should build." - "Use the product artifacts and backlog to pick the next bounded task." - "Run next-task selection before task generation."