Prospec Tasks

---
name: prospec-tasks
description: "Break Down Tasks - Decompose implementation plan into an actionable task checklist (tasks.md). Triggers: break down, tasks, task list, work items, how to split, 拆解, 任務, 任務清單, 工作項目, 如何拆分"
---
<!-- Generated by `prospec agent sync`. Do not edit — this file is regenerated on every sync. -->

# Prospec Tasks Skill

## Activation

When triggered, briefly describe:
- That you'll read plan.md and delta-spec.md to understand the implementation scope
- Tasks will be organized by architecture layer following the project's conventions (see [`references/tasks-format.md`](references/tasks-format.md))
- Non-code tasks carry a `[M]`/`[V]` kind marker; complexity estimates and `[P]` markers are optional

## Language Policy

Write each generated document in the language the Constitution's Language Policy rule assigns to **its path** — change artifacts and their archived summaries in the project's artifact language, the trust zone (Knowledge base, Feature Specs, index) in English. One skill run may write both. Keep code, identifiers, technical terms, and git commit messages in English.
## CLI Prerequisite (required)

> The prospec CLI is a required file for this skill — its deterministic steps call `prospec`
> commands. Probe BEFORE any other step; there is no manual fallback.

1. Run `prospec --version` (Bash).
2. **Command not found / not executable** → STOP. Ask the user to install the prospec standalone
   executable — the one-click installer script from the project README (macOS/Linux `install.sh`,
   Windows `install.ps1`) or a release binary from GitHub Releases; prospec is NOT published to
   npm. Then re-run this skill.
3. **Version older than 2.0.0** → STOP. Report the installed vs required version
   and ask the user to upgrade, then re-run this skill.

Hand-executing a CLI-owned mutation is NEVER the fallback — that re-introduces the
nondeterministic serialization this contract exists to remove.

## Startup Loading

1. [STABLE] Read `prospec/CONSTITUTION.md` — prepare test coverage check
2. [STABLE] **MANDATORY** — Read [`references/tasks-format.md`](references/tasks-format.md) for tasks.md format
3. [DYNAMIC] Read `.prospec/changes/[name]/plan.md` — parse implementation steps
4. [DYNAMIC] Read `.prospec/changes/[name]/delta-spec.md` — parse file changes and specifications
5. [DYNAMIC] Read `.prospec/changes/[name]/design-spec.md` (if exists) — identify UI components for task decomposition
6. [DYNAMIC] Read related module `README.md` from `prospec/ai-knowledge/modules/` (and any `{sub-module}.md` it links) — confirm architecture layers and dependency directions for task ordering

## Entry Gate

> Blocking precondition check before this skill runs. If any item FAILs, stop and tell the user what is missing — do not proceed.

- plan.md and delta-spec.md exist. **Exception — `metadata.scale: quick`**: only proposal.md is required (a quick change legitimately has no plan/delta-spec); decompose directly from proposal.md and advance status `story → tasks` (the legal quick transition — see `prospec/ai-knowledge/_status-lifecycle.md`).
- Prior unresolved WARN: surface the `warn:` lines `prospec status` prints for this change.

## Core Workflow

### Phase 1: Parse Planning Documents

Auto-identify current change, read plan.md and delta-spec.md, summarize implementation phases, file changes, and spec count.

> **Phase 1 Gate** — proceed when:
> - [ ] current change name resolved and plan.md + delta-spec.md (or proposal.md for `scale: quick`) read
> - [ ] implementation phases, file changes, and spec/REQ count summarized

### Phase 2: Create Scaffolding

| Scenario | Action |
|----------|--------|
| tasks.md doesn't exist | Run `prospec change tasks [--change <name>]` (Bash) — the CLI scaffolds `tasks.md` and advances `metadata.yaml` status → `tasks` (including the legal quick `story → tasks` transition) |
| Already exists | Read and populate |

> **Phase 2 Gate** — proceed when:
> - [ ] `tasks.md` exists (created or read)
> - [ ] `metadata.yaml` status is `tasks` (CLI-written — never edit it by hand)

### Phase 3: Decompose by Architecture Layer

Organize tasks following the layer order the project defines — see [`references/tasks-format.md`](references/tasks-format.md), whose Dynamic Architecture Adaptation note lists examples (e.g. `Domain → Ports → Adapters → Tests`, `Models → Services → Controllers → Tests`) and forbids hardcoding a fixed framework topology.

Task format: `- [ ] [description]`. A `~{lines} lines` estimate and a `[P]` parallelization marker are **optional** — no skill or service *gates* on them. Add them only when they aid the reader; never gate on their presence.

**Task kind tagging:** mark each non-code task with its kind — `[M]` (manual) or `[V]` (verification); leave code tasks unmarked. The kind schema is frozen in `references/tasks-format.md` (Task Kind Markers) — cite it, do not restate. This is the one **required** marker class: in subsequent stages, verify counts only code tasks in the completion rate and archive warns on unchecked tasks by kind.

**Decomposition principles:**
- Single responsibility (one task does one thing)
- Verifiable with clear completion criteria
- Right-sized (ideal 15-25 tasks, 20-100 lines each)
- Dependency direction: follow project conventions (lower layers first)
- UI tasks (when `design-spec.md` exists): reference component names and annotate with adapter MCP measurement instructions

> **Phase 3 Gate** — proceed when:
> - [ ] tasks written to `tasks.md`, grouped by architecture layer per the project's conventions (see [`references/tasks-format.md`](references/tasks-format.md))
> - [ ] non-code tasks carry `[M]`/`[V]` kind markers (the one required marker class; `~lines`/`[P]` are optional)

### Phase 4 (Optional): Mark Parallelization Opportunities

Optionally mark dependency-free tasks with `[P]` when it helps a human split the work.

> **Phase 4 Gate** — proceed when:
> - [ ] (if any `[P]` markers were added) none sits on a task that depends on a lower layer

### Phase 5: Generate Summary

Add a Total Tasks count at end of file; Parallelizable Tasks / Total Estimated Lines are optional (include only if `[P]`/`~lines` were used).

> **Phase 5 Gate** — proceed when:
> - [ ] a Total Tasks count is appended at end of `tasks.md`
> - [ ] Total Tasks count reconciles with the checkboxes in the file

### Phase 6: Task Contract & Verifier Audit (site-specific: TDD & dependency/layering)

Run an independent task contract verification of `tasks.md` against `delta-spec.md` (or `proposal.md` under `scale: quick`) and `plan.md` before proceeding to implementation.

**Step 1 — Load Rubric & Rules:**
Read [`references/tasks-verifier-rubric.md`](references/tasks-verifier-rubric.md) **on demand at this step** (In-Phase On-Demand read; NEVER in Startup Loading). Dynamically inspect the project's `prospec/CONSTITUTION.md`, `prospec/ai-knowledge/_conventions.md`, and `module-map.yaml` to evaluate the 4 orthogonal dimensions:
1. **Bidirectional Contract Coverage**: 100% forward coverage of `delta-spec.md` REQ-IDs (or `proposal.md` acceptance scenarios for `scale: quick`) in `tasks.md`, and 100% backward traceability of tasks to `plan.md` steps.
2. **DAG Dependency & Layering Topological Order**: Tasks strictly sequenced from lowest dependency (core domain, models, shared libs) to highest dependency (services, handlers, entry points, CLI, UI).
3. **TDD Module Test Closure**: Every modified or added module in `plan.md` (or `delta-spec.md`) has at least 1 corresponding test task in the `Tests` section.
4. **Task Sizing & Schema Compliance**: `[M]`/`[V]` kind markers on non-code tasks, granularity 20–100 lines.

**Step 2 — Verifier Execution, Receipt Verification & Harness Degradation:**
**Harness capabilities** (resolved by `prospec agent sync` from this agent's registry entry — act on them, do not re-derive them at runtime): `can_spawn_subagent`: yes · `can_worktree`: no · `can_background`: yes

Sub-agents are available here, so take the sub-agent path. Should a spawn fail at runtime anyway, degrade — degrade to a two-phase prompt isolation in this context, invoking an independent Task Verifier persona to audit tasks.md against delta-spec.md and plan.md, and explicitly notify the developer of the degraded path — and name the path you took. A degraded path is never a silent skip: the developer is told which path ran, every time.

Audit `tasks.md` against `delta-spec.md` and `plan.md` in an independent, fresh verification context (Task Verifier persona).

- **Physical Receipt Verification**: The orchestrator MUST verify that the verifier's JSON report exists as a readable regular file on disk, has `size > 0` bytes, and matches the 4-dimension schema before acting on findings.
- **Lifecycle Probe & Await**: If the report file is missing when a subagent claims completion, inspect abstract subagent lifecycle state or transcript logs and await completion.
- **Explicit Degradation**: On crash, timeout, or spawn failure, execute in degraded single-context mode and honestly disclose the in-session mode (never claiming fresh-subagent PASS).

**Step 3 — Verdict Handling & Break-Glass Override:**
- **PASS**: All 4 dimensions satisfied. Proceed.
- **WARN**: Advisory concerns identified (e.g. minor sizing note). Record to `metadata.yaml` `quality_log` via `prospec change log --skill prospec-tasks --result WARN --warning "<warning detail>"`.
- **FLAWS**: Missing REQ coverage, inverted dependency ordering, missing test tasks for affected modules, or missing kind markers. Revise `tasks.md` to fix the issue, OR apply **Break-Glass Override**: if the finding is a false positive, the developer may supply an explicit rationale to bypass, logged via `prospec change log --skill prospec-tasks --result WARN --warning "Manual override: <rationale>"`.

> **Phase 6 Gate** — proceed when:
> - [ ] Task Verifier audit completed against the 4 orthogonal dimensions (or documented manual override provided)
> - [ ] Any discovered warnings/overrides recorded in metadata.yaml quality_log

### Phase 7: Knowledge Quality Gate

Confirm the decomposition against Knowledge in **one line**: layer order matches the module dependency graph, task file paths exist or are clearly new, and every new/modified module has a test task. Any gap → WARN with a clarification note on the affected task (non-blocking); record to `metadata.yaml` `quality_log`. (The full per-station Quality-Gate table lives only in `prospec-verify`.)

> **Phase 7 Gate** — proceed when:
> - [ ] the one-line Knowledge check is recorded PASS or WARN (with a clarification note per WARN)

### Phase 8: Summary + Next Steps

Suggest: `prospec-implement` or manual review.

## Output Contract

> After running, self-assess and emit a concise Output Summary. Every Success Criterion must be objectively checkable (file existence / grep / test result / count) — no subjective adjectives.

### Success Criteria
- [ ] tasks cover every delta-spec REQ (quick: every proposal acceptance scenario — no delta-spec by contract)
- [ ] tasks grouped by architecture layer
- [ ] non-code tasks carry a `[M]`/`[V]` kind marker
- [ ] every new/modified module has a test task

### Failure Conditions
- no plan.md present (does not apply to `scale: quick`)
- > 30 tasks, or a modified module has no test task

### Output Summary
Emit one line: `Met N/M | Unmet: <items> | Overall: PASS|WARN|FAIL | Next: <one-line>`

### Exit Gate (Constitution)

Verify the output against this skill's **site-specific** Constitution rule (**TDD / test coverage**) and the Task Verifier rubric — not the full Constitution; the every-principle audit is `prospec-verify` V3/5 only. When the rule carries RFC-2119 severity, grade by weight — MUST→FAIL, SHOULD→WARN, MAY→informational (the grade vocabulary stays PASS/WARN/FAIL). A free-text Constitution falls back to judgment-based grading. Record each WARN/FAIL via `prospec change log --skill <station> --result WARN|FAIL --warning "<detail>"` — the CLI owns the `quality_log` serialization; `result` stays the gate three-state, never a grade. Advisory — surface issues, do not hard-block.

## NEVER

- **NEVER** produce more than 30 tasks — indicates Story scope creep; large task lists overwhelm AI context and lose coherence
- **NEVER** create overly fine-grained tasks (<10 lines) — micro-tasks inflate task count and add checkbox overhead without meaningful progress tracking
- **NEVER** create overly coarse tasks (>200 lines) — unverifiable; if a 200-line task fails, the entire block must be debugged and reworked
- **NEVER** hand-edit metadata.yaml — scaffolding and the status advance go through `prospec change tasks`; `quality_log` through `prospec change log` (full lifecycle: `prospec/ai-knowledge/_status-lifecycle.md`)
- **NEVER** start decomposition without plan.md — tasks without architecture context produce random file edits instead of layered implementation (`scale: quick` is the exception: decompose from proposal.md, there is no plan by contract)
- **NEVER** skip test tasks — Constitution requires test coverage; untested modules are deployment blockers in Verify phase
- **NEVER** gate on `[P]` or `~lines` — both are optional reader aids that no skill gates on (nothing reads `~lines`; implement's `[P]` reminder is best-effort and executes sequentially anyway); if you do add an estimate, use `~{lines} lines`, not S/M/L
- **NEVER** omit a non-code task's `[M]`/`[V]` kind marker — verify's completion rate and archive's unchecked-task warnings depend on it (this is the one required marker)
- **NEVER** proceed on verbal completion claims or promises without physical receipt verification of the verifier report file — trusting prose without file inspection masks execution errors
- **NEVER** fabricate mock report files, dummy outputs, or synthetic PASS when a receipt file is missing or unreadable — fail closed with concrete diagnostic errors
- **NEVER** add `references/tasks-verifier-rubric.md` to Startup Loading or the stable prefix — it is an in-phase, on-demand read only (preserves cache stability)
- **NEVER** hardcode specific layer architectures in the verifier audit — dynamically resolve rules from the project's Constitution and conventions
- **NEVER** proceed past Phase 6 on unresolved FLAWS without a documented Break-Glass Override

## Error Handling

| Scenario | Action |
|----------|--------|
| plan.md not found | `scale: quick`: expected — decompose from proposal.md. Otherwise guide user to run `prospec-plan` first |
| Task count exceeds 30 | Suggest splitting the Story or merging fine-grained tasks |
| Insufficient test coverage | Offer options: add test tasks / document test debt |

## Next-Step Handoff

After the Output Summary, recommend the next step in the SDD workflow order
(`story → plan → tasks → implement → review → verify → knowledge-update → archive`, then periodic `learn`) — read
`metadata.yaml` status and `prospec/ai-knowledge/_status-lifecycle.md` (review and learn own no
status transition, so follow this order, not status alone). Provide the direct, actionable Skill
identity or CLI command for the next step (e.g. `prospec-plan`), allowing smooth continuation
without blocking on a separate confirmation turn. If the stage is terminal (`archived`), the linear
flow is complete — point to periodic `prospec-learn` rather than a workflow successor. If the result
does not advance (e.g. verify grade B/C/D), say so and point to the corrective step instead of
offering the next skill.