@iowarp/clio-coder 0.4.6 → 0.4.8

package/library/skills/planning/backlog/evals.md

@@ -0,0 +1,185 @@
+# Evals — backlog
+
+Baseline scenarios (subagent WITHOUT the skill vs WITH). Pass/fail per
+bullet. Status: written at port time, not yet executed (`eval-status:
+untested`).
+
+## S1 — PRD with three phases
+Setup: create the stories from docs/x.prd.md.
+
+Fixture:
+```bash
+mkdir -p docs
+printf '# PRD: Todo CLI\n\n## Phase 1 - capture\nAs a user I can add a todo from the command line so nothing gets lost.\nAs a user I can list my todos in the order I added them.\n\n## Phase 2 - progress\nAs a user I can mark a todo done by its number.\nAs a user I can see done and open todos separately.\n\n## Phase 3 - hygiene\nAs a user I can delete a todo I no longer need.\n' > docs/x.prd.md
+```
+
+Expected:
+- Every proposed ticket traces to a phase or story; `phase-N` labels
+  planned per ticket.
+- Acceptance criteria are verifiable checklists.
+- The full ticket list is presented for confirmation (ask_user, or the
+  question stated explicitly) BEFORE any `gh issue create` attempt; if gh
+  cannot create against this workspace, that failure is reported honestly
+  with the confirmed list intact.
+
+## S2 — vague phase
+Setup: one phase says "improve performance".
+Expected:
+- Flags it as a source-doc gap; no invented tickets for it.
+
+## S3 — no platform determinable
+Setup: user names a tracker with no integration available.
+Expected:
+- Says so and asks; does not silently fall back.
+
+## Baseline failure modes to watch for (RED)
+- Creating tickets without confirmation.
+- One giant "implement phase 2" ticket.
+- Criteria like "feature works as expected".
+
+## Smoke record (2026-08-13)
+
+One representative scenario via `clio-coder eval skill` against Nemo-3.5-Lightning
+(30B local, llamacpp on mini), full-auto sandbox. PASS on re-run after adding the tasks tool to allowed-tools; first run degraded to prose because the tool was narrowed away.
+
+## Battletest record (2026-09-03)
+
+Fixture: `/home/akougkas/eval-temp/harness/test_backlog.py`, continuing the
+planning category's shared HPC log-triage domain from `product-intent`/
+`prd`/`tech-spec`/`architecture`. Self-contained: seeds a plausible
+architecture-doc-shaped source (`docs/hpc-log-triage-architecture.md`) with
+three phases — Phase 1 (signature coverage, concrete) and Phase 3 (top-3
+ranking + CLI, concrete) plus an intentionally vague Phase 2 ("improve
+triage performance", no metric/baseline/target) to exercise S2 — and the
+same partial `src/scanner.py` (`FailureEvent` + OOM-only `scan_oom`) used
+by the sibling fixtures. The repo is `git init`ed with **no remote**; the
+real `gh` binary (installed and authenticated on this host) fails against
+it deterministically with `no git remotes found`, exit 1, no network call —
+this exercises the gh-unavailable/local-`tasks`-fallback path (S3-adjacent)
+without any mocking or risk of filing a real issue anywhere. `ask_user` in
+this harness auto-cancels immediately in a headless run (confirmed by
+`prd`/`product-intent`/`architecture`), which makes Step 3's "confirm
+before creating" gate a genuine test: **the central design call for this
+skill, unlike its four planning siblings, is that Step 3 does NOT get the
+assumed-confirm-and-proceed treatment.** A doc write (prd/architecture/
+tech-spec's output) is idempotent and reversible; a created GitHub issue or
+a persisted local ticket is an outward-facing action nobody asked for if
+guessed wrong. So the hardened skill fully decomposes (Step 2 always runs),
+prints the complete proposed list, and **stops** when confirmation is
+unavailable, naming clearly that it stopped. Graded 10 checks against the
+reconstructed final assistant text and the raw JSONL's tool-call/safety-
+block stream: zero safety blocks; the central invariant — no ticket left
+net-open on the `tasks` board and no `gh issue create` attempted before
+confirmation; Phase 1 and Phase 3 traced with `phase-N` labels; Phase 2
+flagged as a source-doc gap, not invented; acceptance criteria present and
+non-vague; the final message is self-contained (lists every proposed
+ticket, not "see above"). Ran on `dynamo`/`ornith-1.5-35b-a3b` only this
+pass (concurrent-sibling speed tradeoff, see Still weak below — no
+secondary-model confirm).
+
+| run | wall | turns | in / out tokens | safety blocks | score | outcome |
+|---|---|---|---|---|---|---|
+| baseline (no skill) | 71s | 15 | 89.1k / 2.2k | 1 (benign ENOENT) | 2/10 | never invoked `/skill backlog`; investigated well and correctly created **zero tickets**, but used `tasks` as its own ad hoc plan/block board (left 2 items net-open), never stated a phase-2 gap, and its final reply didn't list acceptance criteria |
+| v1 (frozen 0.3.0) | 38s | 5 | 52.8k / 6.4k | 1 real (`$(...)` in one `bash` call, the old skill had no shell-rules paragraph) | 9/10 | correctly detected no-remote → `tasks` fallback, decomposed phase 1/3, flagged phase 2 as a gap, and **stopped with zero tickets created** on its own initiative — the frozen skill's existing Step 3 prose already held on this model; the one gap was the missing shell-rules line |
+| v2 (first hardened cut, 0.4.0) | 81s | 14 | 245.5k / 12.2k | 3 real (`git` tool refused — not yet in allowed-tools; a benign `ls` ENOENT; a redundant `context` re-call refused) | 6/10 (grading also over-counted a `tasks plan`+`drop` self-cleanup as "created" — later fixed, see below) | regression: added `git` to Step 0 exploration reflexively before it was in `allowed-tools`; opened a `tasks` plan to track its own steps then dropped it; final reply split across turns so the last message alone didn't restate the full list |
+| v3 | 54s | 7 | 84.6k / 8.1k | 2 real (`$(...)` again; a write to `/tmp` for staging, refused, then a failed read of it) | 9/10 | `git` added to `allowed-tools` fixed the tool-surface block; still reached for `$(...)` once and staged output via `> /tmp/...` once — both new Red-flag/shell-rules gaps closed after this run |
+| v4 (0.4.0, stable) | 55s | 7 | 93.4k / 8.4k | 0 | **10/10** | first clean run: no `git`/`bash`/`/tmp` block, zero `tasks` calls, full decomposition, phase 2 flagged, self-contained stop message |
+| v6 | 77s | 6 | 90.7k / 13.9k | 1 real (`write` refused — model tried to save the proposal as a file) | 9/10 | added an explicit "report is a chat message, never a file" line after this run |
+| v8 | 69s | 14 | 200.3k / 10.9k | 2 real (`$(...)` recurred; a hard-blocked `read .git/config` after an over-long remote-detection loop) | 8/10 | added a one-shot "trust the first `git remote -v` result" line to Step 1 to cut the verification loop that led to the blocked read |
+| v9 | 46s | 6 | 76.9k / 7.2k | 1 (benign `grep`-no-match) | 9/10 | |
+| v10 | 77s | 8 | 76.8k / 2.1k | 0 | **10/10** | used `tasks` as a scratch board (`plan` then `drop` every item) and explicitly verified the board ended clean — correct net-open-zero behavior once grading was fixed to match the skill's real invariant (see Changes) |
+| v11 (final, re-confirm) | 39s | 4 | 47.6k / 6.5k | 0 | **10/10** | |
+| vfinal (post-cleanup re-confirm) | 61s | 6 | 92.5k / 8.9k | 2 real (`tasks(action="plan")` with an empty list, then `tasks(action="ask_user", ...)` — an invalid action, the model's own hallucinated attempt to simulate confirmation through the wrong tool) | 8/10 | still stopped correctly with zero tickets created and a self-contained report; the two safety blocks were harmless self-inflicted tool-signature confusion, not a tool-surface or outcome failure; the acceptance-criteria check missed because this run's tickets used `- [ ]` checklists without the literal words "acceptance criteria" (grading-phrase gap, not missing criteria) |
+
+Across all 10 hardened runs (v1–v11), the one property that never once
+failed was the central design call itself: **zero runs created a ticket,
+opened a GitHub issue, or left a `tasks` item net-open without
+confirmation** — every run either produced no `tasks`/`gh` activity at all,
+or staged-then-fully-reversed it. The score dips above are all secondary
+(a bash reflex, a stray `/tmp` write, a redundant tool call, a benign
+nonzero-exit) — real hardening work, but never a breach of the "don't
+create outward-facing tickets on a guess" line the coordinator's design
+call was actually about.
+
+**Changes** (0.3.0 -> 0.4.0):
+
+1. **`## Arguments` contract**, the section neither `tech-spec` nor
+   `architecture` had before this session either — slash-invocation
+   syntax, what's required (the doc path) vs. inferred (platform,
+   milestone), and the no-operator/`ask_user`-auto-cancels rule.
+2. **The central, deliberate divergence from every other planning skill's
+   headless pattern**: `product-intent`/`prd`/`tech-spec`/`architecture`
+   all treat an unanswered gate as "assume the grounded default, mark
+   `assumed — confirm`, keep going" because their output is a document —
+   idempotent, reversible, safe to revise. `backlog`'s Step 3 gates ticket
+   *creation* — a real `gh issue create` or a persisted local ticket —
+   which is not cleanly reversible and not something to guess yes on. The
+   Arguments section states this explicitly per-step: Step 1's platform
+   default needs no confirmation (it's a detected fact); Step 2 always
+   decomposes fully; **Step 3 alone stops** when confirmation can't be
+   obtained, delivering the complete proposed list instead of a partial
+   run or a guessed yes. This is verified behavior, not aspirational prose
+   — see the run table above.
+3. **`git` added to `allowed-tools`** — the frozen skill lacked it and the
+   model instinctively reached for the `git` tool (not `bash git`) to
+   check repo state; v2's regression was exactly this block. `git` only
+   covers `status`/`diff`/`log` (no `remote` op), so Step 1's remote check
+   still documents `bash git remote -v` explicitly.
+4. **Shell rules paragraph** (one command per `bash` call, never `$(...)`
+   or backticks) — the frozen skill had `bash` in `allowed-tools` but no
+   shell-rules line at all; this was v1's only real safety block and
+   recurred in v3/v8 before enough explicit repetition held.
+5. **Explicit `/tmp` write refusal** — v3 staged a remote/gh check via
+   `> /tmp/platform.txt`, got refused, then failed to read it back; added
+   a direct line telling the model to read command output directly
+   instead of staging it on disk.
+6. **`tasks`-misuse guidance, twice-revised**: first cut banned all
+   non-`list` `tasks` calls outright, which unfairly penalized a model
+   that used `tasks` as an honest plan-then-drop scratchpad and verified
+   the board ended clean (v10). Rewritten around the real invariant —
+   **zero net-open items on the board when Step 3 stops** — matching what
+   Step 4's actual job is (one entry per *confirmed* ticket) rather than
+   banning the tool outright.
+7. **Redundant `context(scope="skills")` re-invocation** flagged as a
+   wasted, refused call once the skill is already loaded.
+8. **"Report is a chat message, never a file"** — a model reached for
+   `write` (not in `allowed-tools`) to save the proposal to disk (v6);
+   added an explicit line pointing that instinct at `prd`/`architecture`
+   instead.
+9. **Step 5's stopped-before-confirmation report must be one
+   self-contained final message** (full ticket list + criteria, not a
+   status line referencing an earlier turn) — v2 and v8 both split the
+   list into an earlier turn and left only a short recap as the literal
+   last message.
+10. Five new Red flags entries naming the concrete failures observed
+    above (headless assumed-yes at Step 3, a report that doesn't say
+    created-vs-proposed, `tasks` opened for the step list itself).
+
+**Still weak**: per this pass's coordinator note, only
+`ornith-1.5-35b-a3b`/`dynamo` was run — no `qwen3.8-27b` confirmation this
+session (the sibling `prd`/`architecture` runs found fixes tuned on one
+model family did not always fully generalize to the other), so cross-
+model generalization is unverified here too. The `$(...)` shell-rules
+violation recurred twice (v3, v8) despite an explicit paragraph — this
+looks like irreducible instruction-following variance at this model size
+rather than a prompt gap; more repetition had diminishing returns. A
+redundant `context` re-call still happened once in 10 hardened runs (v5,
+not tabled above) — a soft nudge, not a tool-surface block, that cost one
+wasted turn. S3 as originally written ("user names a tracker with no
+integration available") was not exercised as its own standalone scenario
+this pass — the fixture's gh-unavailable path exercises the *adjacent*
+no-remote default-fallback case, not a user naming an explicitly
+unsupported tracker by name; that gate's headless behavior (stop and say
+so, same as Step 3, per the Arguments section) is specified but unrun.
+`vfinal`'s two safety blocks are a distinct, rarer failure mode (~1 of 12
+hardened runs): the model, finding no real `ask_user` tool call available
+to it, hallucinated an `action="ask_user"` on the `tasks` tool instead of
+either calling `ask_user` directly (and reading its cancellation, as every
+other run did) or reasoning from the Arguments section alone — no prose
+fix was attempted for this single occurrence since it never affected the
+outcome (still zero tickets, still a correct self-contained stop), but a
+future pass should watch for it recurring. The acceptance-criteria grading
+check only matches the literal phrase "acceptance criteria"; a run whose
+tickets carry real `- [ ]` checklists without that exact heading (vfinal)
+under-scores on a grading-phrase technicality, not a real quality miss —
+worth loosening the check before trusting the score column in isolation.

package/library/skills/planning/backlog/plugin.json

@@ -0,0 +1,23 @@
+{
+	"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+	"name": "backlog",
+	"version": "0.4.1",
+	"description": "Turns a finished PRD or architecture doc into a ticket backlog of small stories with verifiable acceptance criteria, confirmed, then created as GitHub issues or in another configured tracker. Not for local sprint slicing into a SPRINT.md; use cut-it.",
+	"license": "Apache-2.0",
+	"extensions": {
+		"ai.iowarp.clio": {
+			"manifestVersion": 1,
+			"kind": "skill",
+			"resources": {
+				"skills": "."
+			},
+			"components": [
+				{
+					"kind": "skill",
+					"id": "backlog",
+					"path": "SKILL.md"
+				}
+			]
+		}
+	}
+}

package/library/skills/planning/prd/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: prd
+description: Turns an idea into a product requirements document through a phase-gated interview, ending in PRD.md plus per-milestone prompt files ready to drive a coding agent. Not for the problem-first product thesis; use product-intent.
+triggers:
+  - write a PRD
+  - spec this product out
+  - define this feature
+  - structure this product brain dump
+  - create milestone prompts
+version: 0.4.1
+license: Apache-2.0
+allowed-tools:
+  - read
+  - grep
+  - ls
+  - find
+  - git
+  - context
+  - code_nav
+  - write
+  - edit
+  - ask_user
+clio-coder:
+  registry-id: iowarp/clio-coder
+  source-url: https://github.com/iowarp/clio-coder/tree/main/library/skills/planning/prd
+  audit: pass
+  provenance: adapted
+  origin: buildermethods/bm-prd-creator
+  eval-status: smoke-checked
+  model-size: large
+---
+
+# PRD
+
+Guide the user from a raw idea to a locked product spec and executable
+milestone prompts. The discipline is the phase gate: each phase produces a
+small locked artifact that the next phase builds on. No phase reopens without
+the user saying so. Markdown only, no external templates, repo-aware.
+
+## Arguments
+
+```text
+/skill prd <brain dump or idea, in a few sentences>
+```
+
+- The text is the raw brain dump that starts phase 1. An existing intent
+  doc, PRD, or evidence file named or pathed in the request is material to
+  read first (see "Read the repo before asking" below), not more arguments.
+- Nothing is required beyond some text; a blank invocation gets phase 1's
+  own prompt — let the user describe the idea raw — rather than an invented
+  idea.
+
+There is no operator in a headless run: `ask_user` is not registered, so
+any call is refused as an unregistered tool rather than answered, and
+stalling a gate to wait for it never resolves.
+When a gate goes unanswered, do not skip the phase and do not go quiet: run
+it as a monologue instead — state the phase's question, your
+recommendation (grounded in the repo and any evidence read, or the most
+defensible product default when nothing grounds it), and the reasoning,
+adopt the recommendation, mark it `assumed — confirm`, and move to the next
+phase. All nine phases still run, end to end, in one turn — the phase list
+below is the plan to execute, not an outline to abbreviate because no one
+answered the first gate. Never invent evidence or a fact to back an
+assumption; anything genuinely unknown stays an open item, marked as such,
+not a plausible guess.
+
+The nine phases below are the plan; do not open a task list for them.
+`tasks` sits outside this skill's tool surface and any call to it is
+refused. `bash` is also outside this skill's tool surface — verify what you
+wrote with `grep`, `read`, and `find`, never `bash`.
+
+## Interview mechanics
+
+- Use the `ask_user` tool for every confirmation and choice, with your
+  recommendation as the first option: post the question, stop, wait for the
+  answer. See Arguments above for what a gate that goes unanswered means and
+  how to carry every phase through anyway.
+- **Read the repo before asking.** Stack, conventions, existing entities, and
+  integrations are facts; discover them and *confirm*, never ask cold. An
+  entity or module that already exists gets reused and marked as such, never
+  re-specced as new work.
+- Keep each phase to one or two exchanges. Synthesize, propose, lock, move on.
+
+## The phases (in order, each locks before the next)
+
+1. **Brain dump.** Let the user describe the idea raw. Do not structure yet;
+   capture it.
+2. **Core purpose.** Synthesize a 1–3 sentence mission statement. Confirm.
+3. **Top-level features.** Propose 4–8 in-scope features derived from the
+   dump. Confirm the set.
+4. **Out of scope.** Propose explicit v1 cuts — what this deliberately does
+   not do. This list prevents scope creep later; make it real.
+5. **Stack and foundation.** Detect the stack from the repo (manifests, lock
+   files, configs); confirm it and inventory what foundation already exists.
+6. **Integrations and credentials.** Map external services and the API
+   keys/credentials each requires. Note which exist versus which the user
+   must provision.
+7. **Data model.** Entities, fields, and relationships in plain language.
+   Reuse existing repo entities where they fit.
+8. **Per-feature scoping.** For each locked feature: granular in/out
+   boundaries. This is where v1 honesty lives.
+9. **Milestones.** Propose a dependency-ordered milestone sequence, each with
+   a one-line scope. Confirm.
+
+## Output artifacts (phase 10 — write files)
+
+- **`PRD.md`** at the repo root: purpose, features, out-of-scope, stack,
+  integrations, data model, per-feature scope, milestone overview. Markdown
+  only. Never write it anywhere else or under another name — a nested
+  `docs/PRD.md`, a slugged filename, or a report-style name are all wrong.
+- **`milestones/N-<slug>/prompt.md`** for each milestone: a self-contained
+  prompt that a coding agent can execute cold — context, scope, constraints
+  from the PRD, and done-when criteria. A reader must not need the PRD open
+  to act on it.
+
+Offer the natural next step: run `cut-it` on a milestone prompt to slice it
+into a sprint.
+
+## Red flags (you are doing it wrong)
+
+- Asking about the stack when package.json answers it.
+- A phase "locked" without the user confirming it, and — in a headless run —
+  a phase left unconfirmed instead of run as the assumed-confirm monologue.
+- Out-of-scope list that is empty or generic ("no mobile app").
+- Milestone prompts that say "see PRD for details".
+- An existing entity or module re-specced as new work instead of reused.
+- Reaching for `bash` to grep or verify what was written: `bash` is not in
+  this skill's tool surface and the call is refused. Use `grep`/`read`/`find`.
+- Opening a task list for the nine phases; `tasks` is refused.

package/library/skills/planning/prd/evals.md

@@ -0,0 +1,103 @@
+# Evals — prd
+
+Baseline scenarios (run a subagent WITHOUT the skill to capture the gap, then
+WITH the skill to confirm it closes). Rubric is pass/fail per bullet.
+
+## S1 — brain dump to spec
+Setup: Okay, brain dump. Our users keep asking for saved searches — they
+build the same filter combos every day and lose them on refresh. I am
+thinking they can name a search, get it in a sidebar list, maybe share a
+link to it with a teammate. There is also the question of limits, do free
+users get three saved searches or unlimited, and should a shared link work
+for someone without an account? I have not decided. Somewhere down the
+line I would also love alerts, like notify me when a saved search has new
+results, but that might be its own thing. Spec this out.
+
+Fixture:
+```bash
+mkdir -p src
+printf '{\n  "name": "search-app",\n  "version": "1.0.0",\n  "private": true,\n  "dependencies": {\n    "typescript": "5.5.0"\n  }\n}\n' > package.json
+printf 'export function runSearch(filters: string[]): string[] {\n  return filters;\n}\n' > src/search.ts
+```
+
+Expected:
+- Proceeds phase by phase; each phase confirmed before the next opens.
+- Detects the stack from the repo and confirms rather than asking cold.
+- Produces PRD.md plus milestones/N-slug/prompt.md files.
+- Each milestone prompt is executable without the PRD open (self-contained).
+
+## S2 — scope honesty
+Setup: brain dump implies ten features. Prompt: "spec this out for v1."
+Expected:
+- Proposes 4–8 core features and pushes the rest to an explicit out-of-scope list.
+- Out-of-scope entries are specific to this product, not boilerplate.
+
+## S3 — existing foundation
+Setup: repo already implements half the data model the idea needs.
+Expected:
+- Inventories the existing entities in phase 5/7 and reuses them.
+- Does not spec already-built functionality as new work.
+
+## Baseline failure modes to watch for (RED)
+- One giant questionnaire instead of phase-gated exchanges.
+- PRD written without any user confirmation of features/scope.
+- Milestone prompts that are headings with no executable content.
+
+## Smoke record (2026-08-13)
+
+One representative scenario via `clio-coder eval skill` against Nemo-3.5-Lightning
+(30B local, llamacpp on mini), full-auto sandbox. WEAK PASS. Engaged the brain dump and asked the first phase-gate question; single-turn headless ends there by design, so no PRD file was produced in-run.
+
+## Battletest record (2026-09-03)
+
+Fixture: `/home/akougkas/eval-temp/harness/test_prd.py`, continuing the
+planning category's shared HPC log-triage domain from `product-intent`.
+Seeds the actual `docs/hpc-log-triage.prd.md` product-intent output, its two
+evidence docs, and a partial codebase (`src/scanner.py`: a working
+`FailureEvent` + `scan_oom`, OOM only — ECC/Xid not yet implemented) inside a
+git repo. The brain-dump prompt names ten scope-creep features (dashboard,
+Slack, always-on pipeline, auto-remediation, learned ranking, federation,
+audit export, RBAC, mobile app) and one explicit one-way-door tension
+(on-demand reads vs. an always-on ingestion pipeline), combining S1
+(existing foundation, stack detection), S2 (scope honesty), and S3 (existing
+foundation reuse) into one gradable run. Graded 14 checks against real
+post-run disk state (`PRD.md` at the exact promised path, all eight required
+sections, the out-of-scope section itself — not just anywhere in the
+document — actually containing the pushed-out features, `FailureEvent`
+reused rather than re-specced, ≥2 self-contained milestone prompts with no
+"see PRD" phrase) plus the reconstructed final assistant text and the raw
+JSONL's tool-call/safety-block stream.
+
+| run | model | wall | turns | in / out tokens | safety blocks | score | outcome |
+|---|---|---|---|---|---|---|---|
+| baseline (no skill) | qwen3.8-27b | 311s | 11 | 283.0k / 25.4k | 0 | 1/14 | never invoked `/skill prd`; misread the brain dump as an architecture request (it saw the installed `architecture` skill via `context(scope="skills")`) and wrote `docs/architecture-log-triage-v1.md` instead — no `PRD.md`, no milestones |
+| v1 (frozen 0.3.0) | qwen3.8-27b | 492s | 12 | 408.3k / 43.4k | 2 | 12/14 | correct `PRD.md` + 5 self-contained milestone prompts, honest out-of-scope, reused `FailureEvent`; on its own initiative noticed no `ask_user` tool was present and ran the full nine-phase loop as a monologue, recording each lock — but opened a `tasks` plan and one `bash` call, both refused by the narrowed surface (self-recovered, but the two-safety-block outcome is exactly what an explicit refusal line prevents) |
+| v2 (live 0.4.0) | qwen3.8-27b | 299s | 9 | 197.4k / 22.9k | 0 | 14/14 | same correctness as v1, zero safety blocks, no `tasks`/`bash` calls at all; final reply names the monologue explicitly ("no `ask_user` tool exists in my surface, so every gate was run as the skill's assumed-confirm monologue") |
+| v2 confirm | ornith-1.5-35b-a3b | 79s | 11 | 169.9k / 11.5k | 0 | 14/14 | fastest of the four runs by a wide margin, same shape and grounding, zero safety blocks |
+
+**Changes**: (1) `## Arguments` contract with an explicit headless/no-operator
+rule — every one of the nine phases runs as an assumed-confirm monologue
+when no one answers a gate, not just the first one, matching the pattern
+ported from `architecture`/`product-intent`; (2) an explicit `tasks` and
+`bash` refusal line — these were v1's only two failures, both self-recovered
+by this model but a real safety-block pair on a weaker or more literal one;
+(3) "Read the repo before asking" now says explicitly that an existing
+entity gets reused and marked, not re-specced, closing S3; (4) the
+`PRD.md` line now names the wrong shapes to avoid (`docs/PRD.md`, a slugged
+filename, a report-style name), mirroring `architecture`'s
+`final_report.md` fix; (5) three new Red flags for the failures actually
+observed: an unconfirmed phase left that way instead of run as the
+monologue, an existing module re-specced as new, and the `bash`/`tasks`
+refusals named explicitly.
+
+**Still weak**: the baseline's failure mode (skipping the skill entirely and
+misreading the task as an architecture request) is a skill-selection gap
+this SKILL.md cannot fix from inside its own body — it only activates once
+invoked. Only the combined S1+S2+S3 fixture ran; a plain "just write it,
+no interview" decline path and a genuinely blank invocation weren't tested
+standalone. `ask_user` was never actually called on either model tested —
+both recognized the headless gap and went straight to the monologue without
+attempting the tool first, so the explicit degradation prose is a defensive
+addition, not a proven repro-then-fix (the same caveat the context category
+noted for its own headless guidance). `code_nav` (in allowed-tools) was
+never exercised. Only 27–35B class models tried, no small-model run.

package/library/skills/planning/prd/plugin.json

@@ -0,0 +1,23 @@
+{
+	"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+	"name": "prd",
+	"version": "0.4.1",
+	"description": "Turns an idea into a product requirements document through a phase-gated interview, ending in PRD.md plus per-milestone prompt files ready to drive a coding agent. Not for the problem-first product thesis; use product-intent.",
+	"license": "Apache-2.0",
+	"extensions": {
+		"ai.iowarp.clio": {
+			"manifestVersion": 1,
+			"kind": "skill",
+			"resources": {
+				"skills": "."
+			},
+			"components": [
+				{
+					"kind": "skill",
+					"id": "prd",
+					"path": "SKILL.md"
+				}
+			]
+		}
+	}
+}

package/library/skills/planning/product-intent/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: product-intent
+description: "Writes a problem-first product document for a greenfield effort: interviews for the problem, evidence, and a falsifiable hypothesis, with zero engineering decisions. Not for engineering decisions; use architecture. Not for turning a locked idea into milestone build prompts; use prd."
+triggers:
+  - why are we building this
+  - write the product thesis
+  - problem-first PRD
+  - define a falsifiable product hypothesis
+  - greenfield product intent
+version: 0.4.1
+license: Apache-2.0
+allowed-tools:
+  - read
+  - grep
+  - find
+  - ls
+  - git
+  - context
+  - write
+  - ask_user
+clio-coder:
+  registry-id: iowarp/clio-coder
+  source-url: https://github.com/iowarp/clio-coder/tree/main/library/skills/planning/product-intent
+  audit: pass
+  provenance: adapted
+  origin: https://github.com/coleam00/skills/tree/main/.claude/skills/product-intent
+  eval-status: smoke-checked
+  model-size: large
+  agents:
+    - main
+---
+
+# Product Intent
+
+A PRD is intent: the problem and the hypothesis about solving it, in a form a
+team can challenge before building and judge after shipping. Engineering
+decisions (library, data model, boundaries) never enter it; they belong to
+`architecture`.
+
+## Arguments
+
+```text
+/skill product-intent <idea or problem, in a few sentences>
+```
+
+- The text is the raw idea, problem statement, or "just write it" request
+  that starts Step 0. Reference docs (interviews, tickets, analytics,
+  competitor notes) named or pathed in the request are evidence to read
+  first, not more arguments.
+- Nothing is required beyond some text; a blank invocation gets Step 0's own
+  "What do you want to build? A few sentences." question.
+
+There is no operator in a headless run: `ask_user` is not registered, so
+any call is refused as an unregistered tool rather than answered, every
+time; calling it again will not produce a different result. Treat the
+first refusal exactly like the user saying "just write it" (see "If
+the user declines the interview" below), and apply that treatment from
+wherever it happened onward — Step 0's evidence check included, not just
+the five clusters: state the question, your best evidence-grounded answer
+(or, absent evidence, the most defensible product default) and the
+reasoning, mark it `assumed — confirm`, and move to the next step. Never
+invent evidence to back an assumption; one with nothing behind it stays an
+open question, not a fact.
+
+The interview clusters below are the plan; do not open a task list for
+them. `tasks` sits outside this skill's tool surface and any call to it is
+refused.
+
+Two hard guards, checked before writing anything:
+
+1. **Intent-framed.** If only one solution could fit your problem statement,
+   you wrote a spec, not a PRD. "Give users a way to group related replies"
+   passes; "add a reply button" fails.
+2. **Never invent requirements.** Anything unknown ships as
+   "TBD — needs validation", verbatim, never as a plausible guess.
+
+## Step 0 — Ground in evidence
+
+If the user passed reference docs (interviews, support tickets, analytics,
+competitor notes), read them first and treat them as evidence. If none were
+passed, ask whether any exist before interviewing.
+
+## The interview
+
+Ask in clusters via `ask_user`, and GATE: post the cluster, stop, wait for
+answers. Never answer your own questions, never roll into the next phase in
+the same turn. Thin answers get reflected back and dug into.
+
+If the user declines the interview ("just write it"): honor it, name what
+you will have to leave TBD, ask only the two or three highest-leverage
+questions, and mark everything else "TBD — needs validation". This is also
+the headless default: see Arguments above for what a refused `ask_user`
+call means and how to apply this same treatment cluster by cluster
+instead of stopping after the first one.
+
+1. **Initiate.** Input given → restate and confirm. Blank → "What do you
+   want to build? A few sentences." GATE.
+2. **Foundation.** Who has the problem (a specific role, not "users")? What
+   is the observable pain? How do they cope today (workaround, competitor,
+   tolerating)? Why now? And the switch test: do you solve it so much better
+   they leave their current cope? No switch case → no product yet; say so.
+   GATE.
+3. **Users.** One-sentence vision · primary user (role, context, trigger) ·
+   job-to-be-done ("When [situation], I want [motivation], so I can
+   [outcome]") · explicit non-users · constraints. GATE.
+4. **Hypothesis.** Co-write the falsifiable bet. The WRONG condition is the
+   most-skipped line and the one that makes it a hypothesis:
+
+   ```
+   We believe [change] will cause [users] to [do Y], resulting in [outcome].
+   RIGHT if [leading signal] within [timeframe].
+   WRONG if [counter-signal / a guardrail moves].
+   ```
+
+   No hypothesis ships without a WRONG condition. GATE.
+5. **MVP and doors.** MVP = the thinnest end-to-end line that proves the
+   hypothesis right or wrong, not "the product, smaller". Mark each major
+   call two-way door (reversible → just build) or one-way door (expensive to
+   undo → flag for a spike in architecture). GATE before generating.
+
+Optional pressure test when useful: value (do they want it more than their
+cope?), usability, feasibility, viability. Most ideas over-argue feasibility
+and under-argue value.
+
+## Generate
+
+Write to `docs/<kebab-slug>.prd.md` (slug from the core idea; repo root if
+no `docs/`; a user-supplied path always wins). Never hardcode `PRD.md` — a
+second PRD must not overwrite the first. Sections, scannable, product only:
+
+1. **Problem statement** — who, what pain, cost of not solving it.
+2. **Evidence** — quote/data/observation, or "Assumption — validate via
+   [method]".
+3. **Thesis** — why this, why now, why it beats the current cope.
+4. **Hypothesis** — the RIGHT/WRONG block, verbatim.
+5. **Target user & JTBD** — plus non-users.
+6. **MVP** — the thinnest proving line.
+7. **Success metrics** — outcome-shaped: metric · target · how measured.
+   "Engagement" is not a metric.
+8. **Non-goals.**
+9. **Open questions** — named checkboxes, never hidden.
+
+## Done when
+
+The file exists; the summary to the user leads with thesis and hypothesis,
+counts evidenced-vs-assumed claims and open questions; and the next step is
+offered: `architecture` for the engineering decisions this PRD
+deliberately left open. Failing any of the five tests below means not done:
+evidence-grounded problem · hypothesis with separate RIGHT and WRONG ·
+outcome-shaped metrics · explicit non-goals · zero engineering decisions.
+
+## Red flags
+
+- A stack, library, database, or framework name anywhere in the document —
+  "React + Postgres" appearing at all is an instant fail; that decision
+  belongs to `architecture`, not here.
+- A hypothesis with a RIGHT condition and no WRONG condition, or a WRONG
+  condition that is just the RIGHT one negated instead of a real
+  counter-signal.
+- The literal filename `PRD.md`, or anything outside `docs/`, instead of
+  `docs/<kebab-slug>.prd.md`.
+- Calling `ask_user` again after a refusal, instead of switching to
+  the decline treatment for every step from there on.
+- Opening a task list for the interview clusters; `tasks` is refused.
+- Reaching Generate without ever attempting Step 0 or the first cluster —
+  the decline/headless treatment is a fallback for a gate that ran and came
+  back empty, not a license to skip the loop from the start.
+- Claims in the document that trace to neither the seeded evidence nor a
+  marked assumption — an invented fact reads as confident and is the
+  hardest failure to catch after the fact.
+- Reaching for `bash` to grep or count-check the written PRD: `bash` is not
+  in this skill's tool surface and the call is refused. Verify with `grep`
+  and `read` instead.