rsc-universal 0.1.1

package/skills/swift-ios/references/concurrency.md

@@ -0,0 +1,132 @@
+# Swift 6 strict concurrency — migration & diagnostics
+
+Load this when the user hits data-race diagnostics, is migrating a target to the Swift 6 language mode, or needs `actor`/`Sendable`/`AsyncStream` patterns. The SKILL body covers the common path; this is the depth.
+
+## Enabling the Swift 6 language mode (per target, staged)
+
+Do it one target at a time. Flip language mode globally and you drown in diagnostics with no way to triage.
+
+1. **Stage with upcoming-feature flags first** (still in Swift 5 mode). In Build Settings add `SWIFT_UPCOMING_FEATURE_*` or, in SwiftPM, `.enableUpcomingFeature(...)`. Useful ones: `StrictConcurrency`, `InferSendableFromCaptures`, `DisableOutwardActorInference`. Resolve the warnings these surface.
+2. **Then set `SWIFT_VERSION = 6`** on that target. Remaining warnings become errors.
+3. Repeat per target, leaf modules first.
+
+```swift
+// Package.swift — staged adoption for one target
+.target(
+    name: "Core",
+    swiftSettings: [
+        .enableUpcomingFeature("StrictConcurrency"),
+        .defaultIsolation(MainActor.self)   // SE-0466, see below
+    ]
+)
+```
+
+## SE-0466 default actor isolation + Approachable Concurrency
+
+For UI-centric apps, set **Default Actor Isolation = MainActor** (build setting `SWIFT_DEFAULT_ACTOR_ISOLATION = MainActor`, or `.defaultIsolation(MainActor.self)` in a SwiftPM target). Unannotated declarations become main-actor-isolated by default — the app is effectively single-threaded until you explicitly opt out with `nonisolated`. This removes the bulk of false-positive data-race warnings.
+
+"Approachable Concurrency" is the umbrella build setting that, alongside this, also flips `InferIsolatedConformances` and `NonisolatedNonsendingByDefault`. Turn it on for new UI apps; turn it off and isolate manually for library code that must stay actor-agnostic.
+
+Opt a hot, pure-compute path back off the main actor:
+
+```swift
+nonisolated func parse(_ data: Data) throws -> Model { /* no UI, no shared state */ }
+```
+
+## The canonical diagnostics
+
+### "Non-Sendable type 'X' crossing actor boundary"
+
+A value that is not safe to share is being passed between isolation domains.
+
+```swift
+// Bad — class with mutable state sent into a Task on another actor
+final class Box { var value = 0 }
+func use(_ b: Box) { Task.detached { print(b.value) } }   // Box is not Sendable
+
+// Good — make it a value type, or an immutable/Sendable type
+struct Box: Sendable { let value: Int }
+```
+
+If the type is genuinely safe but the compiler can't prove it (e.g. it guards its own state with a lock), conform with `@unchecked Sendable` — and only then. `@unchecked` is a promise *you* are now responsible for.
+
+### "Main actor-isolated property cannot be referenced from a nonisolated context"
+
+You touched main-isolated state from somewhere not on the main actor.
+
+```swift
+// Bad
+@MainActor @Observable final class VM { var name = "" }
+func log(_ vm: VM) { print(vm.name) }          // nonisolated function reads main state
+
+// Good — make the access main-isolated, or await it
+@MainActor func log(_ vm: VM) { print(vm.name) }
+// or from async code:
+func log(_ vm: VM) async { print(await vm.name) }
+```
+
+### "Capture of 'self' with non-Sendable type in a `@Sendable` closure"
+
+A `Task.detached`/`@Sendable` closure captured a non-Sendable `self`.
+
+```swift
+// Bad
+func refresh() { Task.detached { await self.reload() } }
+
+// Good — Task {} inherits the actor; self stays on its actor, no crossing
+func refresh() { Task { await self.reload() } }
+```
+
+## `actor` patterns
+
+Use an `actor` for shared mutable state that is **not** UI. Its methods are implicitly async from outside; access is serialized.
+
+```swift
+actor ImageCache {
+    private var store: [URL: Data] = [:]
+    func data(for url: URL) -> Data? { store[url] }
+    func set(_ data: Data, for url: URL) { store[url] = data }
+}
+```
+
+**Reentrancy**: an actor can suspend at an `await` and run another call before the first resumes. Re-check invariants *after* every `await` inside an actor method — do not assume state is unchanged across a suspension point.
+
+## Bridging callbacks with `AsyncStream`
+
+Turn a delegate/callback API into an `AsyncSequence`:
+
+```swift
+func locations() -> AsyncStream<CLLocation> {
+    AsyncStream { continuation in
+        let delegate = LocationDelegate { continuation.yield($0) }
+        continuation.onTermination = { _ in delegate.stop() }
+        delegate.start()
+    }
+}
+// for await loc in locations() { ... }   // ends when the task is cancelled
+```
+
+## Structured parallelism & cancellation
+
+```swift
+// Fan out with async let
+async let a = fetchProfile()
+async let b = fetchPosts()
+let (profile, posts) = try await (a, b)
+
+// Dynamic fan-out with a group, cancellation-aware
+try await withThrowingTaskGroup(of: Item.self) { group in
+    for id in ids { group.addTask { try await fetch(id) } }
+    var out: [Item] = []
+    for try await item in group { out.append(item) }   // throws cancel propagation
+    return out
+}
+
+// In a loop, cooperate with cancellation
+for url in urls {
+    try Task.checkCancellation()
+    _ = try await download(url)
+}
+```
+
+Prefer SwiftUI's `.task {}` for view-lifetime async work — it cancels automatically when the view disappears, so you rarely store a `Task` handle yourself.

package/skills/swift-ios/references/testing.md

@@ -0,0 +1,112 @@
+# Swift Testing — depth
+
+Load this for traits, parameterized matrices, async-event testing, and testing `@MainActor @Observable` models or SwiftData. The SKILL body has the skeleton; this is the rest.
+
+## Suites & traits
+
+A `@Suite` groups tests and can carry traits its tests inherit.
+
+```swift
+@Suite("Checkout", .tags(.payments))
+struct CheckoutTests {
+    @Test(.enabled(if: AppConfig.paymentsEnabled)) func charges() { /* ... */ }
+    @Test(.timeLimit(.minutes(1)))                 func slowPath() async { /* ... */ }
+    @Test(.disabled("flaky on CI — FB12345"))      func legacy() { /* ... */ }
+}
+```
+
+Common traits:
+
+| Trait | Effect |
+| --- | --- |
+| `.tags(.foo)` | Group/filter tests across suites |
+| `.enabled(if:)` / `.disabled(_:)` | Conditional run, with a reason string |
+| `.timeLimit(.minutes(n))` | Fail if the test exceeds the limit |
+| `.serialized` | Run a suite's tests in order, not in parallel |
+| `.bug("URL", "id")` | Link a test to a tracker ticket |
+
+By default tests run **in parallel and in-process**. Mark a suite `.serialized` only when tests share mutable global state you cannot isolate.
+
+## Parameterized matrices
+
+```swift
+// One argument set
+@Test(arguments: [0, 1, 100]) func nonNegative(_ n: Int) { #expect(n >= 0) }
+
+// Two zipped collections (paired, not cartesian)
+@Test(arguments: zip(["a", "bb"], [1, 2]))
+func length(_ s: String, _ len: Int) { #expect(s.count == len) }
+
+// Cartesian product: pass two arguments collections
+@Test(arguments: [1, 2], ["x", "y"])
+func combos(_ n: Int, _ s: String) { /* runs 4 cases */ }
+```
+
+## Async events with `confirmation`
+
+For callback/notification-style work that should fire a known number of times:
+
+```swift
+@Test func emitsThreeEvents() async {
+    await confirmation("got events", expectedCount: 3) { confirm in
+        let stream = makeStream()
+        for await _ in stream.prefix(3) { confirm() }
+    }
+}
+```
+
+WWDC25 additions: **attachments** (attach files/data to a failing test's report) and **exit tests** (assert that a process traps/exits — for testing precondition failures).
+
+## `#expect` vs `#require`
+
+- `#expect(cond)` — soft. Records a failure and keeps running. Use for independent assertions.
+- `try #require(cond)` — hard. Throws and stops the test. Use to unwrap optionals or guard preconditions the rest of the test depends on:
+
+```swift
+let row = try #require(rows.first)   // stop here if empty
+#expect(row.id == 1)
+```
+
+## Testing a `@MainActor @Observable` model
+
+Annotate the test (or suite) `@MainActor` so it shares isolation with the model:
+
+```swift
+@MainActor @Suite struct FeedTests {
+    @Test func loadsItems() async throws {
+        let feed = Feed()
+        try await feed.load()
+        #expect(!feed.items.isEmpty)
+    }
+}
+```
+
+## Testing SwiftData with an in-memory container
+
+Never touch the on-disk store in tests. Build a throwaway container:
+
+```swift
+@MainActor @Test func insertsWorkout() throws {
+    let config = ModelConfiguration(isStoredInMemoryOnly: true)
+    let container = try ModelContainer(for: Workout.self, configurations: config)
+    let context = container.mainContext
+    context.insert(Workout(name: "Run", minutes: 30))
+    let all = try context.fetch(FetchDescriptor<Workout>())
+    #expect(all.count == 1)
+}
+```
+
+## XCTest coexistence / migration
+
+Both frameworks live in the same test target. Migrate logic tests; leave the rest.
+
+| XCTest | Swift Testing | Keep in XCTest? |
+| --- | --- | --- |
+| `XCTAssert`, `XCTAssertEqual` | `#expect(...)` | No — migrate |
+| `XCTUnwrap` | `try #require(...)` | No — migrate |
+| `setUp`/`tearDown` | `init`/`deinit` of the suite type | No — migrate |
+| `XCTestExpectation` | `confirmation { }` | No — migrate |
+| `XCUIApplication` (UI automation) | — | **Yes** — XCTest only |
+| `XCTMetric` / `measure {}` (performance) | — | **Yes** — XCTest only |
+
+Run everything from one command: `xcodebuild test -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 17'`.

package/skills/swift-ios/scripts/verify.sh

@@ -0,0 +1,98 @@
+#!/usr/bin/env bash
+# verify.sh — advisory copy/practice banlist for Swift / SwiftUI files.
+#
+# Pure text checks: no Xcode, no network, no toolchain. Greps emitted .swift
+# (and Package.swift) for stale or footgun patterns and prints file:line on hits.
+#
+# Read-only. Exits 0 when the target is empty/clean (no false failure), 1 on a hit.
+# Greenfield-oriented and ADVISORY: legacy codebases may legitimately match —
+# review hits, do not treat them as hard errors when working in existing code.
+#
+# Usage:
+#   scripts/verify.sh [PATH ...]
+# Defaults to scanning the current directory if no path is given.
+
+set -euo pipefail
+
+# --- collect targets -------------------------------------------------------
+targets=("$@")
+if [ "${#targets[@]}" -eq 0 ]; then
+  targets=(".")
+fi
+
+tmp_list="$(mktemp)"
+trap 'rm -f "$tmp_list"' EXIT
+for t in "${targets[@]}"; do
+  if [ -d "$t" ]; then
+    find "$t" -type f -name '*.swift' 2>/dev/null >> "$tmp_list"
+  elif [ -f "$t" ] && [ "${t%.swift}" != "$t" ]; then
+    printf '%s\n' "$t" >> "$tmp_list"
+  fi
+done
+
+files=()
+while IFS= read -r f; do
+  [ -n "$f" ] && files+=("$f")
+done < <(sort -u "$tmp_list")
+
+# Empty/clean target -> succeed quietly. No false failure.
+if [ "${#files[@]}" -eq 0 ]; then
+  echo "verify.sh: no .swift files to scan — clean."
+  exit 0
+fi
+
+hits=0
+
+# report PATTERN MESSAGE  (egrep across files, prints file:line)
+report() {
+  local pattern="$1" message="$2"
+  local out
+  out="$(grep -REnH "$pattern" "${files[@]}" 2>/dev/null || true)"
+  if [ -n "$out" ]; then
+    echo "FAIL: $message"
+    printf '%s\n' "$out" | sed 's/^/  /'
+    hits=$((hits + 1))
+  fi
+}
+
+# --- global banlist --------------------------------------------------------
+report ': *ObservableObject\b' "ObservableObject in new code — use @Observable (Observation)."
+report '@Published\b'          "@Published in new code — @Observable tracks properties automatically."
+report 'NavigationView\s*[({]'  "NavigationView is deprecated — use NavigationStack + navigationDestination."
+report '@nonisolated\(unsafe\)' "@nonisolated(unsafe) silences isolation instead of fixing it — make the type Sendable or main-isolated."
+
+# --- per-file contextual checks -------------------------------------------
+for f in "${files[@]}"; do
+  # DispatchQueue.main.async inside a file that declares an @Observable model
+  if grep -q '@Observable' "$f" && grep -nE 'DispatchQueue\.main\.async' "$f" >/dev/null 2>&1; then
+    echo "FAIL: DispatchQueue.main.async inside an @Observable model — annotate the model @MainActor: $f"
+    grep -nE 'DispatchQueue\.main\.async' "$f" | sed 's/^/  /'
+    hits=$((hits + 1))
+  fi
+
+  # XCTAssert* in a file that also uses Swift Testing (@Test)
+  if grep -q '@Test' "$f" && grep -nE 'XCTAssert' "$f" >/dev/null 2>&1; then
+    echo "FAIL: XCTAssert in a Swift Testing file — use #expect / #require: $f"
+    grep -nE 'XCTAssert' "$f" | sed 's/^/  /'
+    hits=$((hits + 1))
+  fi
+
+  # Task.detached without an adjacent justification comment (warn)
+  if grep -nE 'Task\.detached\s*[({]' "$f" >/dev/null 2>&1; then
+    while IFS=: read -r ln _; do
+      prev=$((ln - 1))
+      if [ "$prev" -ge 1 ] && sed -n "${prev}p" "$f" | grep -qE '//.*(justif|reason|why|intentional|detach)'; then
+        continue
+      fi
+      echo "WARN: Task.detached without a justification comment (rarely correct — Task {} inherits actor + priority): $f:$ln"
+    done < <(grep -nE 'Task\.detached\s*[({]' "$f")
+  fi
+done
+
+if [ "$hits" -gt 0 ]; then
+  echo "verify.sh: $hits banlist hit(s). Advisory — review before treating as failures."
+  exit 1
+fi
+
+echo "verify.sh: clean."
+exit 0

package/skills/tasks/SKILL.md

@@ -0,0 +1,260 @@
+---
+name: tasks
+description: "Use when you have an approved implementation plan and need to break it into an ordered, independently-verifiable task list before any code is written — the SDD `tasks` phase (GitHub Spec Kit lineage: constitution → specify → clarify → plan → tasks → analyze → implement). Turns a plan into numbered tasks, each with an explicit done-check (the literal command or observation that proves it complete), dependencies, and a parallel-safe marker. Triggers: 'break the plan into tasks', 'make a task list', 'task breakdown', 'descompón el plan en tareas', 'lista de tareas', 'what are the steps to build this', 'turn the plan into a checklist', 'sequence the work', 'which tasks can run in parallel', 'give each task a done-check'. Appends the task list into the plan artifact under 02-DOCS/wiki/sdd/plans/<slug>.md. NOT writing the plan itself (that is `plan`), NOT the consistency gate over the artifacts (that is `analyze`), NOT executing the tasks (that is `implement`)."
+tags: [sdd, tasks, breakdown]
+recommends: [analyze, implement]
+profiles: [core, full]
+origin: risco
+---
+
+# Tasks — turn an approved plan into a verifiable work list
+
+The `tasks` phase is the hinge between *thinking* and *doing*. The plan already
+decided the architecture, the interfaces, and the testing strategy. This phase
+slices that plan into the **smallest units a coding agent can finish, prove, and
+hand off** — each one ordered, each one carrying a *done-check* that a machine or
+a reviewer can run without trusting anyone's word.
+
+A task list is not a to-do list. A to-do list says "build the auth endpoint". A
+task list says "T004: implement `POST /login`; done when `pytest
+tests/auth/test_login.py` is green AND a 401 is returned for a bad password —
+depends on T002, T003; parallel-safe with T005." The difference is that the
+second one can be **handed to a subagent, executed, and verified** with no
+further questions.
+
+This is a process skill. It writes no runtime code. It produces one artifact: an
+ordered, checkable task list appended to the plan it was built from.
+
+## Read the harness profile first
+
+Before producing anything, read `02-DOCS/wiki/harness/user-profile.md` for the
+technical level and the **accompaniment dial**, and adapt:
+
+- **L0 (cavernícola)** — emit the task table, nothing else. No commentary.
+- **L1 (breve)** — one line of *why this slicing* above the table.
+- **L2 (explica decisiones)** — justify the ordering and the parallel markers as
+  you go; flag the risky tasks.
+- **L3 (acompañamiento total)** — explain the slicing method, walk each
+  dependency, and confirm the done-checks make sense to the user before writing.
+
+If no profile exists, assume non-technical + ask the two gauging questions the
+harness defines before slicing. Never invent a level.
+
+## Inputs (refuse to start without them)
+
+You break down a **plan**, not an intent. Before slicing, confirm all three exist:
+
+1. **The plan** — `02-DOCS/wiki/sdd/plans/<slug>.md`, written by the `plan`
+   phase. It must contain the architecture, interfaces, and testing strategy.
+2. **The spec** — `02-DOCS/wiki/sdd/specs/<slug>.md`, so every task traces to a
+   requirement. A task with no spec line behind it is scope you are inventing.
+3. **The constitution** — `02-DOCS/wiki/sdd/constitution.md`, the non-negotiable
+   bars (stack canon, quality gates) every task must respect.
+4. **The SDD config** — `02-DOCS/wiki/sdd/config.yaml`, if present. Use its
+   `review_budget`, `delivery_strategy` and `testing.commands` when writing
+   done-checks and review forecasts. If it is missing on non-trivial work,
+   recommend `sdd-init`.
+
+If the plan is missing, **stop and route to `plan`**. If the plan exists but is
+vague on interfaces or testing, route back to `plan` to tighten it — do not
+paper over a thin plan with guesswork in the task list. That guesswork is the
+exact thing `analyze` will catch next, and you will have wasted the round trip.
+
+## What makes a task well-formed
+
+Every task is one row. A row is well-formed only when all six fields hold:
+
+| Field | Rule |
+| --- | --- |
+| **ID** | `T001`, `T002`, … — sequential, zero-padded, no hyphen (GitHub Spec Kit canon). Stable, never renumbered once written (downstream phases cite it). |
+| **[P]** | A **separate field after the ID**: `[P]` if the task is parallel-safe, blank otherwise. Never fold the marker into the ID. |
+| **Title** | One imperative verb + object. "Implement", "Add", "Wire", "Migrate" — not "Handle" or "Support". |
+| **Done-check** | The **literal** command or observation that proves done. Runnable, not a feeling. See below. |
+| **Depends-on** | The task IDs that must finish first, or `—` for none. Drives the ordering and the parallel markers. |
+| **Trace** | The spec section / acceptance criterion this task satisfies. Every task traces to one; if it can't, it's out of scope. |
+
+Put `[P]` (parallel-safe) in its own field only when the task shares **no files
+and no state** with another unblocked task. When in doubt, leave it blank — a
+false `[P]` causes the merge collisions `parallel` exists to prevent.
+
+## The done-check is the whole point
+
+A done-check has to be **executable evidence**, owned by the stack, not a
+self-graded claim. Delegate the *form* of the check to the relevant stack skill
+and quote the actual command:
+
+- Backend (Python/FastAPI) → a `pytest` invocation; route to `../fastapi/SKILL.md`.
+- Go services → a `go test ./...` target; route to `../go/SKILL.md`.
+- Frontend (Next.js) → a component/e2e test or a typed build; route to `../nextjs/SKILL.md`.
+- Flutter → a `flutter test` target; route to `../flutter/SKILL.md`.
+- Schema/migrations → a migration applies + a query returns expected rows; route to `../postgresdb/SKILL.md`.
+
+```text
+WEAK   done-check: "login works"
+STRONG done-check: pytest tests/auth/test_login.py::test_bad_password_returns_401  → green
+                   AND manual: POST /login {wrong pw} returns 401, no token in body
+```
+
+A done-check you cannot run is not a done-check. If the plan's testing strategy
+doesn't support a runnable check for a slice, that is a **plan gap** — name it
+and send it back, don't write a vague check to keep moving.
+
+## TDD-shaped slicing (default)
+
+The `implement` phase runs red → green → refactor. Slice so it can. For each
+behavioral unit, the natural shape is a test-first pair the implementer executes
+in order:
+
+1. **Txxx (test):** write the failing test for the behavior. *Done when the test
+   exists and fails for the right reason.*
+2. **Txxx+1 (impl):** implement until that test is green. *Done when the test
+   passes and nothing else regresses.*
+
+You don't have to split every task in two, but the done-check of an
+implementation task should always be *a test that was red and is now green*. This
+is where `tasks` and `implement` shake hands: the list you write is the list TDD
+will execute.
+
+## The slicing procedure
+
+```text
+1. WALK the plan top to bottom. List every concrete deliverable
+   (endpoint, model, migration, component, job, config).
+2. For each deliverable, ask: smallest slice that produces a runnable
+   done-check? Split until each task is verifiable on its own.
+3. ORDER by dependency. Foundations first: schema → data layer →
+   service → API → UI. A task never precedes what it depends on.
+4. MARK [P] only on tasks that share no files/state with another
+   unblocked task. Default to sequential.
+5. TRACE each task back to a spec line. No trace → cut it (scope creep)
+   or send the gap to `clarify`/`specify`.
+6. ADD the cross-cutting closers: a final "all done-checks pass" task
+   and a "verify.sh green" task that hands off to `verify`.
+7. ADD a review workload + delivery forecast before implementation.
+8. APPEND the table to the plan artifact (see below). Do not start a
+   new file; the list lives with the plan it came from.
+```
+
+## Where the artifact lives
+
+The task list is **not** a new document. Append it to the existing plan under a
+`## Tasks` heading:
+
+```text
+02-DOCS/wiki/sdd/plans/<slug>.md
+  ├─ ## Architecture        (from plan)
+  ├─ ## Interfaces          (from plan)
+  ├─ ## Testing strategy    (from plan)
+  └─ ## Tasks               ← you append this
+       T001 … T0NN as the table below, + a one-line "generated by tasks on <date>"
+```
+
+Then ensure the plan is indexed in the root `CLAUDE.md` `## Knowledge map` under
+the `sdd/` topic (the `plan` phase usually added the row; confirm it points at
+`02-DOCS/wiki/sdd/plans/<slug>.md`, add it if missing — additive only, never
+delete a user's map entry).
+
+### The table format
+
+```markdown
+## Tasks
+<!-- generated by tasks on 2026-06-01; IDs are stable, do not renumber -->
+
+| ID | [P] | Task | Done-check | Depends-on | Trace |
+| --- | --- | --- | --- | --- | --- |
+| T001 |  | Add `users` table migration | `alembic upgrade head` applies clean; `\d users` shows email UNIQUE | — | spec §3 Data |
+| T002 | [P] | Add `sessions` table migration | migration applies; FK to users present | T001 | spec §3 Data |
+| T003 |  | Write failing test for `POST /login` | `pytest tests/auth/test_login.py` fails: no route | T001 | spec §4 Auth |
+| T004 |  | Implement `POST /login` | T003 test green; bad pw → 401 | T003 | spec §4 Auth |
+| ... | ... | ... | ... | ... | ... |
+| T0NN |  | All done-checks pass + `verify.sh` green | every row above checked; `scripts/verify.sh` exits 0 | all | spec §Acceptance |
+```
+
+## Review workload + delivery strategy forecast
+
+After the task table, append a short forecast. This protects the human reviewer
+before a giant diff exists.
+
+```markdown
+## Review Workload Forecast
+
+| Dimension | Forecast | Why |
+| --- | --- | --- |
+| Estimated changed lines | <number or range> | based on task count + touched areas |
+| Files / areas | <count and names> | modules, migrations, UI, tests, docs |
+| Review risk | low / medium / high | complexity, cross-stack scope, security/data changes |
+| Suggested delivery | single-pr / ask-on-risk / autochain / exception | matched to config.review_budget |
+```
+
+Rules:
+
+- If estimated changed lines exceed `config.sdd.review_budget.line_budget` (default 400), recommend splitting or `ask-on-risk`.
+- If many areas or cross-stack contracts are touched, recommend `autochain` or a feature-track branch.
+- If the change is tiny, recommend `single-pr`.
+- If a deadline or emergency justifies a large review, mark `exception` and require explicit user approval later.
+
+## Anti-patterns → STOP
+
+| Tempting move | Why it's wrong / Fix |
+| --- | --- |
+| "I'll write tasks straight from the user's intent" | You're skipping `plan`. Tasks slice a plan, not a wish. Route to `plan`. |
+| "Done-check: 'feature works'" | Not runnable, not evidence. Quote the literal test/command, or it's not a done-check. |
+| "One giant task: 'build the backend'" | Unverifiable, un-handoffable. Split until each slice has its own runnable check. |
+| "Mark everything `[P]` so it goes faster" | Shared files = merge collisions. `[P]` only when scope is truly disjoint. |
+| "This task has no spec line but we obviously need it" | That's scope creep wearing a hat. Trace it or cut it; if it's real, send it to `clarify`. |
+| "The plan is thin here, I'll guess the slice" | `analyze` will reject the guess next phase. Tighten the plan first. |
+| "I'll start coding the easy task while I list the rest" | This phase writes zero runtime code. Implementation is `implement`. |
+| "Renumber the IDs so they're contiguous" | Downstream phases cite IDs. They're stable once written. Append, don't renumber. |
+
+## Done-of-done for this phase
+
+Before handing off, confirm:
+
+- [ ] Every plan deliverable maps to at least one task.
+- [ ] Every task has a runnable done-check (a command or a checkable observation).
+- [ ] Every task traces to a spec line; no orphan tasks.
+- [ ] Dependencies form a valid order (nothing precedes what it needs).
+- [ ] `[P]` markers only on file/state-disjoint tasks.
+- [ ] The list is appended under `## Tasks` in the plan artifact, indexed in the Knowledge map.
+- [ ] A final closer task gates on all done-checks + `verify.sh`.
+- [ ] Review workload forecast and suggested delivery strategy appended.
+
+## Result envelope
+
+End with:
+
+```json result-envelope
+{
+  "status": "complete",
+  "executive_summary": "Task list and review workload forecast appended to the plan.",
+  "artifact": "02-DOCS/wiki/sdd/plans/<slug>.md",
+  "next_recommended": "analyze",
+  "risk": "low|medium|high",
+  "skill_resolution": {
+    "used": ["tasks"],
+    "missing": [],
+    "fallback": [],
+    "compact_rules": ["Every task needs a runnable done-check.", "Forecast review load before implementation."]
+  },
+  "evidence": ["task table appended", "review workload forecast appended"]
+}
+```
+
+## Next in the SDD chain
+
+The task list is now the contract for the rest of the build. Hand off:
+
+- **→ `analyze`** — the consistency gate. Before any code, cross-check
+  constitution ↔ spec ↔ plan ↔ **tasks** for gaps, contradictions, and scope
+  drift. Orphan tasks and untraceable scope surface here. Report only; the user
+  resolves.
+- then **→ `implement`** — execute the tasks in order, TDD-style (red → green →
+  refactor), using `parallel` for the `[P]` tasks and `worktrees` for isolation.
+
+Do not jump straight to `implement`. The whole point of writing a checkable list
+was to let `analyze` audit it cheaply *before* code exists.
+
+## Orientación (siempre)
+
+Cierra cada turno con el **bloque-brújula** (📍 dónde estás · ✅ qué hiciste · 🧭 por qué · ➡️ siguiente, terminando en pregunta), calibrado al dial de `02-DOCS/wiki/harness/user-profile.md`. **Nunca termines en seco.** Protocolo completo: skill `orient` → `skills/orient/references/orientation-contract.md`. (Defiere a `suggest` el "¿instalo la skill que falta?".)
+

package/skills/tasks/evals/README.md

@@ -0,0 +1,70 @@
+# Eval harness — `tasks` skill
+
+Two things to check: that the skill **triggers** on the right prompts (and stays
+quiet on its SDD neighbours), and that it **measurably improves** the task
+breakdown an agent produces. Cases live in `cases.yaml`. There is no shell
+runner — triggering and breakdown quality are judgment calls, graded by an
+**agent harness** (a Claude Code agent with the skill catalog loaded) plus a
+human spot-check.
+
+## What's in `cases.yaml`
+
+- `should_trigger` — prompts that MUST load `tasks` (incl. Spanish and non-obvious phrasings).
+- `should_not_trigger` — near-misses that must route elsewhere (`route_to`), all on the
+  hard SDD-chain boundaries: `plan` (the step before), `analyze` (the gate after),
+  `implement` (the doing), and the stack skills a single task merely delegates to.
+- `capability` — one scenario with a `must_include` rubric to grade with vs without.
+
+## Triggering eval
+
+Goal: the skill fires when it should and never on a near-miss.
+
+1. Configure an agent with the **full catalog of skill descriptions** available
+   for routing — the other rsc-sdd phases (`sdd`, `constitution`, `specify`,
+   `clarify`, `plan`, `analyze`, `implement`, `verify`, `review`, `ship`,
+   `debug`, `worktrees`, `parallel`) plus the stack/process skills (`fastapi`,
+   `nextjs`, `go`, `postgresdb`, `flutter`, `harness`, …) — so routing competes
+   realistically.
+2. For each `should_trigger` prompt: feed it cold, record whether `tasks` is the
+   skill the agent loads. Run **3–5 trials** per prompt (fresh context each).
+3. For each `should_not_trigger` prompt: confirm `tasks` does NOT load and that
+   the chosen skill matches `route_to`. Same 3–5 trials.
+4. Score: `triggered_correctly / total_trials` across both lists.
+
+**Pass bar: ≥ 90% trigger accuracy** over all prompts and trials, with **zero
+systematic false-positives** on the `plan`/`analyze`/`implement` near-misses.
+Those three are the known traps: a prompt to *write* the plan, to *gate* the
+artifacts, or to *execute* the work must not pull in `tasks`. If `tasks` keeps
+stealing `plan` or `implement` prompts, the description's NOT-clauses need
+sharpening.
+
+## Capability eval
+
+Goal: prove the skill changes the breakdown, not just the routing.
+
+1. For the `capability` scenario, run it **twice**:
+   - **WITHOUT** the skill (base agent, no `tasks` loaded).
+   - **WITH** the `tasks` skill loaded.
+2. Grade each output against the `must_include` checklist — one point per
+   checkable item covered. A human or grading agent marks each present / absent.
+3. Compute coverage = `items_covered / total_items` per run.
+
+**Pass bar: WITH the skill covers ≥ 80% of `must_include`; WITHOUT clearly
+lower** (target a ≥ 30-point gap). The skill must demonstrably add: runnable
+done-checks (not "it works"), dependency ordering, disciplined `[P]` marking,
+spec traces with no orphan tasks, TDD-shaped pairs, appending into the plan
+artifact (not a new file), and the handoff to `analyze`.
+
+## Notes on honesty
+
+- Trials are stochastic; report the raw fraction, not a rounded "pass".
+- The highest-signal capability check is the **done-check quality**: a correct
+  answer never emits a self-graded "feature works" — it quotes the literal
+  command. Treat a tidy-looking but unverifiable list as a **capability
+  failure** even if it reads well.
+- The second-highest signal is **refusing to slice from intent**: if no plan
+  exists, the correct behaviour is to STOP and route to `plan`, not to invent a
+  breakdown. A confident task list built from a fuzzy wish is a failure.
+- Re-run after any edit to `SKILL.md` — wording changes shift both triggering
+  and rubric coverage, especially the NOT-clauses that fence off `plan`/
+  `analyze`/`implement`.