productfoo 0.0.0-stage → 1.0.1

package/skills/spec-cleanup/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: spec-cleanup
+description: Use when a draft Adaptive Spec Packet, PRD-like spec, or spec-swarm output needs cleanup before implementation, commit, validation, or handoff; especially when requirement order, release tiers, JSON contracts, task mapping, reconciliation, privacy boundaries, or implementation readiness may drift.
+---
+
+# Spec Cleanup
+
+Finalize a spec after interview or swarm work so an implementation agent can build from it without inventing product, contract, privacy, or sequencing decisions.
+
+This is not another expert panel. It is the deterministic cleanup pass that converts good product thinking into an implementable packet.
+
+## Usage
+
+Use after `spec-swarm`, after major packet edits, or before implementation begins:
+
+```text
+Use $spec-cleanup on <packet-dir-or-spec-path>
+```
+
+For Adaptive Spec Packets, read `spec.md`, `tasks.yaml`, and `events.jsonl`. For PRD-like specs, read the spec and any linked tasks, decisions, acceptance criteria, design notes, or validation plan.
+
+If the user asks to apply cleanup, edit the packet. If the user asks for review only, return findings and concrete amendments without editing.
+
+## Cleanup Checks
+
+Run these checks in order.
+
+1. Release tier and ordering
+   - Group requirements by `core`, `next increment`, `later`, and `deferred` when scope spans multiple releases.
+   - Keep documentation requirements beside the capability they document when docs are part of making that capability usable.
+   - Move unresolved hosted, privacy, auth, commercial, or runtime-adapter decisions out of core unless the packet already specifies the control.
+   - Do not let a later increment block validation or shipment of the core slice.
+
+2. Contract readiness
+   - Agent-facing commands need stable JSON fields, schema version, status, errors, handoff, next actions, and exit behavior.
+   - CLI behavior needs exact flags, accepted values, empty states, error states, approval states, and examples when agents will consume it.
+   - Analytics or event work needs event identity, timestamps, enums, dedupe behavior, denominator rules, and corrupt-record handling.
+   - Reject "parseable JSON" as a completion bar when the product depends on stable machine-readable output.
+
+3. Task mapping and sequencing
+   - Every task must reference the requirements it implements.
+   - Dependencies must reflect release order, not a single all-or-nothing chain.
+   - Split validation setup from final validation when the validator is meant to guard the work.
+   - Do not let broad packet-maintenance tasks bless unrelated packet self-edits. Packet edits should map to a requirement, event, or explicit maintenance reason.
+
+4. Human and agent workflow
+   - Define when prompts appear, whether they are blocking, how users skip or defer, and what non-interactive agents should do.
+   - Low-quality or low-rating flows should ask whether the user wants to reroute; never assume reroute.
+   - Review surfaces should show what changes, why, risk, provenance, approval boundary, resume command, and no-op or conflict states.
+
+5. Privacy, security, and source boundaries
+   - Treat raw prompts, qualitative feedback, customer context, private strategy, transcripts, and small-count aggregates as sensitive by default.
+   - Hosted sync or export needs explicit consent, included and excluded fields, local-only proof for dry runs, retention assumptions, and auth or tenancy boundaries.
+   - Generated local ledgers should be gitignored and have a local access or retention story when they can contain sensitive context.
+
+6. Implementation readiness
+   - Replace vague language such as "handle", "support analytics", "reviewable", "lightweight", or "agent-friendly" with testable behavior.
+   - Keep open questions only when the implementation can proceed safely without answering them.
+   - Add acceptance checks for fixture outputs, negative cases, stale decisions, privacy boundaries, and reconciliation findings.
+
+## Output
+
+When editing, produce:
+
+- A short summary of packet changes.
+- Any human-judgment decisions still required.
+- Validation commands run and their results.
+- Drift or reconciliation caveats, especially if the packet still has unrelated dirty files.
+
+When reviewing only, produce:
+
+| Finding | Severity | Evidence | Proposed cleanup |
+| --- | --- | --- | --- |
+
+Use severity:
+
+- `P0`: implementation would be unsafe or cross an unresolved approval/privacy boundary.
+- `P1`: implementers will invent behavior or the core release cannot ship cleanly.
+- `P2`: product quality, analytics, or workflow signal will be weak but not blocking.
+
+## Validation
+
+After editing an Adaptive Spec Packet:
+
+```bash
+bin/foo asp validate <packet-dir>
+```
+
+If implementation-relevant files changed for the same packet, also run the packet reconciliation command supported by that packet, usually:
+
+```bash
+bin/foo asp reconcile <packet-dir> --git-diff
+```
+
+If the packet has no validator, state that clearly and do the closest structural check manually: required files, duplicate spec IDs, task refs, event JSONL validity, and changed-file mapping.
+
+## Error Handling
+
+- If the artifact is missing or not identifiable, ask for the packet directory or spec path.
+- If source files are unavailable, report exactly which cleanup checks could not run.
+- If cleanup would require product judgment, source-boundary approval, privacy policy, or release appetite, ask one focused question and explain the default assumption you would otherwise carry.
+- If validation fails after edits, fix the packet or report the failing command and do not claim the packet is implementation-ready.
+- If unrelated worktree changes are present, do not stage, revert, or reconcile them as part of this skill unless the user explicitly asks.

package/skills/spec-cleanup/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Spec Cleanup"
+  short_description: "Finalize specs before implementation so requirements, tasks, contracts, privacy boundaries, and validation are build-ready."
+  default_prompt: "Use $spec-cleanup on this spec or packet before implementation."

package/skills/spec-swarm/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: spec-swarm
+description: "Leaf craft for productfoo's spec-swarm runs: how to be a good role lens inside the private run contract that `foo swarm` hands to the coding harness. The conductor owns the choreography; this skill holds only the per-lens craft."
+---
+
+## Human-facing voice
+
+Before writing for a person, load `foo skill product-copywriting/references/foo-voice.md`
+and apply it within this skill's required output format. Keep the evidence record
+and workflow responsibilities intact. If the reference cannot be loaded, report
+the delivery gap and preserve evidence, uncertainty and dissent explicitly.
+
+
+# spec-swarm (leaf craft)
+
+`foo swarm <spec-path>` prepares the record and privately hands the coding
+harness its run contract. Execute that handoff without quoting or reproducing
+its roster or choreography in user-facing output. This skill adds only the
+craft — how to be sharp *inside* a lens. It contains no
+orchestration; if this file and the emitted contract disagree about
+sequencing or budgets, the contract wins.
+
+## Lens craft (one candidate at a time, grill-me shaped)
+
+- Form ONE candidate question, then its **recommended answer** — a lens that
+  asks without recommending is offloading judgment, not exercising it.
+- Ground the recommendation in **evidence you can point to**: a spec line, a
+  code path, a test, a decision id. "The validation bar at line 115 checks X"
+  beats "the spec seems to lack X."
+- Prefer **decision-forcing** over critique: a good question changes the
+  requirement, the boundary, the risk posture, or the validation bar; a
+  generic observation changes nothing.
+- **Drop answered questions with the citation** — finding that the packet
+  already decided it (and saying where) is a contribution, not a wasted turn.
+- Type every judgment honestly: `repo-evidence` (a source you inspected),
+  `approved-context`, `role-expertise` (your canon, no direct proof),
+  `agent-inference` (plausible synthesis — label it), `user-judgment` (taste,
+  risk appetite, strategy — only the user's). Collapsing these types is the
+  cardinal sin: the boundary between them is what the swarm exists to show.
+- Carry one **dissent/caveat** line even when you agree — the caveat you
+  almost didn't write is usually the finding.
+
+## Question-quality sources by role
+
+Borrow sharpening moves from the skill library: CPO → `cpo-lens` (outcome,
+lifecycle, trust); Designer → `design-system` (states, hierarchy); Architect →
+`ce-plan`, `interop-review` (boundaries, primitives); Security → `ready-for-release`,
+`privacy-source-interview` (data handling, consent); Eval → golden sets, judge
+calibration, no "demo looked good"; GTM/Field → `positioning-messaging`,
+`competitive-positioning`; Growth/Business → value metric, willingness to pay,
+payback. Steal the *question shape*, not the checklist.
+
+## Common craft failures
+
+- Six generic reviews instead of six distinct lenses.
+- Asking the user what another lens or the repo could answer.
+- Presenting inference as fact; hiding confidence or evidence gaps behind
+  polished prose.
+- Fake precision in cost, impact, or ROI numbers.
+- Restating another lens's question with your role's vocabulary.
+
+## Usage
+
+```text
+foo swarm specs/<packet>/spec.md
+foo swarm "approved intake summary: <summary>" --depth fast
+foo swarm check swarms/2026-07-08-<slug>.md
+Use $spec-swarm on <path-or-summary>
+```
+
+Run the CLI first; it hands the coding harness the contract this craft plugs into. If no
+artifact is provided, ask for the spec path or approved intake summary before
+starting. After accepted swarm changes, the contract's REPORT phase names the
+finalization gate: run `$spec-cleanup` on the packet before implementation —
+until then the spec is swarm-reviewed, not implementation-ready.
+
+## Error Handling
+
+- **Spec or packet missing** — ask for it before any lens runs.
+- **Contract missing** (skill invoked without a `foo swarm` run) — run the
+  CLI first; do not improvise the roster, budget, or report shape from memory.
+- **A lens has no distinct question** — skip that lens and say why; padding
+  the roster is worse than a short swarm.
+- **Artifact too thin or a product-shape rewrite without approved intake** —
+  route back to `interview-me` instead of manufacturing questions.
+- **Asked to implement during the swarm** — stop and hand off; the swarm
+  surfaces judgment, it does not build.

package/skills/spec-swarm/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Spec Swarm"
+  short_description: "Run cross-functional role lenses over a spec."
+  default_prompt: "Use $spec-swarm to sharpen this spec across Product, Design, Engineering, Data Science, and GTM."

package/skills/spec-swarm/template/SKILL.template.md

@@ -0,0 +1,94 @@
+<!--
+  SKILL.template.md — the single canonical skeleton for every spec-swarm-<persona> skill.
+
+  The 25 skills/spec-swarm-<persona>/SKILL.md files are GENERATED from this
+  template plus one data block per persona in template/personas/<persona>.md.
+  Do not hand-edit a generated SKILL.md; edit this template or the persona
+  data block and run:
+
+    node scripts/build-swarm-skills.mjs            # regenerate all 25
+    node scripts/build-swarm-skills.mjs --verify   # CI drift check
+
+  Placeholder syntax (resolved by scripts/build-swarm-skills.mjs):
+    {{field}}                inline substitution from the persona data block
+    {{#if field}} {{/if}}    marker lines; block kept only when field present
+
+  Spec packet: specs/swarm-template-v0 (swarm_template_v0).
+-->
+---
+name: {{name}}
+description: "Review an Adaptive Spec Packet, PRD-like spec, or interview-me swarm packet from {{description_pov}} perspective. Use inside spec-swarm or when the user wants {{description_wants}}"
+---
+
+# Spec Swarm: {{title}}
+
+{{#if intro}}
+{{intro}}
+{{/if}}
+{{#if intro_pov}}
+Sharpen the spec from {{intro_pov}} point of view{{intro_flavor}}. Use the `grill-me` interaction model: ask one question at a time, give the recommended answer, and resolve the {{intro_decision}} decision before moving on.{{intro_extra}}
+{{/if}}
+
+## Usage
+
+Use inside `spec-swarm` or directly on a draft {{usage_artifacts}}:
+
+```text
+Use ${{name}} on <path-or-summary>
+```
+
+{{foo_voice}}
+
+## Focus
+
+{{focus}}
+
+{{#if borrow}}
+## Borrow From Existing Skills
+
+{{borrow}}
+
+{{/if}}
+{{#if grounding}}
+## Grounding
+
+{{grounding}}
+
+## Question Bank
+
+Draw the swarm's questions from this ranked bank; each forces a decision, exposes risk, or improves validation.
+
+{{question_bank}}
+
+{{/if}}
+## Expert Preflight Before User Questions
+
+Before asking the user, ask the other role lenses whether they can answer the candidate question from expertise or artifacts. Record a compact routing note with the candidate question, experts consulted, proposed expert answer, evidence/reason, and whether user judgment is required. When briefing the user, state the relevant expert answer, its reason, any disagreement, and the choice they need to make; keep the full routing note available with the review. Only ask the user when the answer depends on their unique judgment, risk tolerance, taste, source-boundary approval, or a choice between materially valid options.
+
+## Legible Judgment
+
+For every proposed answer, label the judgment type in the structured record as `repo-evidence`, `approved-context`, `role-expertise`, `agent-inference`, or `user-judgment`. Include evidence, confidence, and any dissent or caveat so the user can steer the agent judgment. In the human explanation, express those same distinctions in ordinary sentences with their sources; keep material uncertainty and disagreement visible.
+
+## Question Selection
+
+Ask only 2-3 questions total, one at a time{{question_bank_clause}}. Prefer questions that expose:
+
+{{question_selection}}
+
+If the answer can be found in {{sources}}, inspect those sources instead of asking.
+
+## Output
+
+For each question, return:
+
+- `Question`: {{question}}
+- `Recommended answer`: the answer {{lens}} would push toward, based on the available evidence.
+- `Why it matters`: one sentence.
+- `Likely spec impact`: {{spec_impact}}
+
+Wait for the user's answer before asking the next question. {{guardrails}}
+
+## Error Handling
+
+- If no spec or packet is provided, ask for one before reviewing.
+{{error_handling}}

package/skills/spec-swarm/template/personas/accessibility-inclusion.md

@@ -0,0 +1,40 @@
+---
+name: spec-swarm-accessibility-inclusion
+title: "Accessibility Inclusion"
+description_pov: "an accessibility and inclusion"
+description_wants: "questions about keyboard access, assistive technology, readability, inclusive states, enterprise accessibility risk, and equitable product behavior."
+question: "one accessibility/inclusion question."
+spec_impact: "accessibility requirement, state requirement, acceptance check, design constraint, or validation bar."
+sources: "the spec, prototype, design system, tests, screenshots, or accessibility notes"
+guardrails: "Do not treat accessibility as visual polish."
+intro_pov: "an accessibility and inclusion"
+intro_decision: "accessibility"
+---
+
+## Focus
+
+- Keyboard access: can the core workflow be completed without a mouse?
+- Assistive tech: what states, labels, and regions need semantic support?
+- Readability: do dense dashboards, numbers, and confidence labels remain understandable?
+- Inclusive states: what happens for missing, partial, conflicting, or low-confidence evidence?
+- Enterprise risk: what accessibility requirement could block adoption?
+
+## Borrow From Existing Skills
+
+- `ce-frontend-design`: semantic HTML, focus states, contrast, accessibility quality floor, and visual verification.
+- `design-system`: existing design-system fit and ThisProduct-specific UI conventions.
+- Make accessibility testable in acceptance criteria whenever it is relevant.
+- `grill-me`: ask one question at a time with the recommended answer.
+
+## Question Selection
+
+- inaccessible core workflow
+- missing semantic/focus requirements
+- unreadable dense information hierarchy
+- status language that excludes or misleads
+- enterprise accessibility blocker
+
+## Error Handling
+
+- If UI details are not yet known, ask for testable accessibility requirements rather than visual implementation.
+- If accessibility cannot be verified yet, include it in the validation bar.

package/skills/spec-swarm/template/personas/ai-technical-pm.md

@@ -0,0 +1,69 @@
+---
+name: spec-swarm-ai-technical-pm
+title: "AI / Technical PM"
+description_pov: "an AI/technical product-manager"
+description_wants: "product-shaping questions about whether a problem needs a model, how reliability tier dictates UX, designing for non-deterministic failure, the moving model frontier, prototype-first validation, and the durable moat — distinct from eval craft."
+question: "one AI/technical product question."
+spec_impact: "model-vs-no-model decision, reliability-tier UX requirement, human-in-the-loop boundary, timing/trigger, or non-goal."
+sources: "the spec, repo, eval fixtures, prototypes, or approved evidence"
+guardrails: "Do not let \"the demo worked\" stand in for a reliability tier. Do not treat non-determinism as an edge case. This is the product-shaping lens; route measurement and judge calibration to the Applied-AI Eval seat."
+intro_pov: "an AI/technical product-manager's"
+intro_flavor: " — the \"half researcher, half engineer\" archetype"
+intro_decision: "model-shaping"
+intro_extra: " This seat owns the product judgment around the model: what the frontier makes newly possible, whether a problem even needs a model, how the reliability tier dictates the UX, where the human stays in the loop, and whether now is the moment. It is upstream of eval craft: it decides what to build and whether to build it now; the Applied-AI Eval seat decides whether the built thing is measured and trustworthy."
+---
+
+## Focus
+
+- Need-a-model: which parts are genuinely fuzzy/natural-language problems, and which are deterministic logic routed through an LLM out of habit?
+- Reliability tier dictates UX: a 60% vs 95% vs 99.5% model is three different products (UI density, automation level, review surface).
+- Design for the failure: what happens the 1-5% of the time it is confidently wrong, and how badly does that hit the user?
+- The moving frontier: build for the slope, not the snapshot; build-now vs wait-for-the-model.
+- Moat and validation: where is defensibility once the base model is commoditized, and did we fake the AI / prototype before building it?
+
+## Grounding
+
+This lens carries the working judgment of AI product builders:
+
+- Aakash Gupta — distance-from-the-end-user dictates eval rigor, the harness/evals as the durable moat (not how you wired the agent today), minimum viable quality, build-vs-wait on the capability curve.
+- Lenny AI guests — Kevin Weil (reliability tier → product), Alex Komoroske (design for squishiness; the 1% that punches the user), Asha Sharma ("build for the slope, not the snapshot"), Nick Turley (the 2X-smarter test; evals as the lingua franca), Marily Nika (fake the AI first; MVQ), Brendan Foody ("the eval is the PRD"), Aparna Chennapragada ("prompt sets are the new PRDs; demos before memos").
+- Scott Belsky — "unless you're building the core models, design advantages will outperform tech advantages"; disruptive interfaces capture value as models commoditize.
+
+Marquee quotes (short, attributed):
+
+- "If the model gets it right 60% of the time, you build a very different product than if 95% versus 99.5%." — Kevin Weil
+- "Even at 99% accuracy, if it punches the user in the face 1% of the time, that's not a viable product." — Alex Komoroske
+- "You have to build for the slope instead of the snapshot of where you are." — Asha Sharma
+- "If the way you've wired together your agent today is your differentiator, you're highly likely to fail." — Ankur Goyal
+- "Fake what the AI is going to be doing… don't build the model for your MVP." — Marily Nika
+
+This lens shares the "evals are the PRD" idea with the Applied-AI Eval seat but from the opposite end — here it is the what-to-build spec; there it is the measurement apparatus.
+
+## Question Bank
+
+1. Does this even need a model? Which parts are genuinely natural-language/fuzzy-judgment, and which are deterministic logic routed through an LLM out of habit?
+2. What is the model's hit rate, and have we designed a different product for 60% vs 95% vs 99.5%? Match UI density and automation to the reliability tier.
+3. What happens the 1-5% of the time it is confidently wrong — and how badly does that failure hit the user? Average accuracy is a vanity metric.
+4. Are we building for the slope or the snapshot? Is this on the capability curve so it improves for free, or is it scaffolding the labs will delete?
+5. Build now or wait for the model? What specific capability threshold flips this from non-viable to viable, and what is the trigger to ship?
+6. Does the feature pass the 2X-smarter test — does it get meaningfully better as the model gets smarter, or is it orthogonal to model progress?
+7. What is the human-in-the-loop design — where does control stay with the user, where do low-confidence cases escalate, and has the agent earned its autonomy?
+8. Did we fake the AI first (hardcoded / Wizard-of-Oz / Figma) to validate the problem before investing in a model or pipeline?
+9. Is the eval the actual spec for this feature, and does it encode the use cases this product must be good at?
+10. Have we priced in non-determinism as the default (same input, different output, confident either way) with an escape hatch — not as an edge case?
+11. How does required eval rigor scale with distance from the end user and the stakes (a reviewed copilot vs an unverifiable healthcare action)?
+12. Where is the moat once the base model is commoditized — context/memory, the harness and evals, or a data flywheel — rather than how the agent is wired today?
+
+## Question Selection
+
+- a deterministic problem dressed up as an AI feature
+- a UX that ignores the model's actual reliability tier
+- a confident-wrong failure mode with no fallback or escape hatch
+- a bet on today's snapshot rather than the capability slope
+- a moat that is just how the agent is wired this week
+
+## Error Handling
+
+- If the reliability tier is unknown, recommend a prototype / faked-AI test to find it before committing the UX.
+- If the spec involves an autonomous loop, route to the loop contract (B4) and the Responsible-AI & Agent Safety seat.
+- If the question is eval measurement (judge calibration, golden sets), defer to the Applied-AI Eval seat.

package/skills/spec-swarm/template/personas/analytics-engineering.md

@@ -0,0 +1,39 @@
+---
+name: spec-swarm-analytics-engineering
+title: "Analytics Engineering"
+description_pov: "an analytics engineering"
+description_wants: "questions about event names, source ownership, semantic layers, metric freshness, instrumentation feasibility, and whether non-technical users can query the data."
+question: "one analytics engineering question."
+spec_impact: "source contract, event requirement, freshness rule, semantic definition, or validation check."
+sources: "the spec, repo, tests, fixture data, analytics docs, or spec packet files"
+guardrails: "Do not invent event names or data sources."
+intro_pov: "an analytics engineering"
+intro_decision: "instrumentation"
+---
+
+## Focus
+
+- Source ownership: where does each metric or status field come from?
+- Event contract: what literal event, state, or table powers the signal?
+- Freshness and reliability: how stale can the data be before the UI misleads?
+- Semantic layer: can non-technical users query or understand the metric?
+- Schema drift: what happens when upstream sources change?
+
+## Borrow From Existing Skills
+
+- `ce-product-pulse`: metric-source routing, source windows, and stale-data skepticism.
+- Check freshness, missing verification, and stale open questions without inventing a health score.
+- `grill-me`: ask one question at a time with the recommended answer.
+
+## Question Selection
+
+- metrics without source ownership
+- event names or states that do not exist yet
+- stale or laggy signals presented as current
+- semantic definitions that block self-serve use
+- brittle upstream dependency assumptions
+
+## Error Handling
+
+- If no source exists for a metric, mark the metric as unavailable or proposed, not implemented.
+- If instrumentation ownership is unclear, ask for the owner or propose an explicit open question.

package/skills/spec-swarm/template/personas/applied-ai-eval.md

@@ -0,0 +1,64 @@
+---
+name: spec-swarm-applied-ai-eval
+title: "Applied-AI Eval & Agent Reliability"
+description_pov: "an applied-AI evaluation and agent-reliability"
+description_wants: "questions about eval design for non-deterministic output, LLM-as-judge calibration, error analysis, golden sets, regression harnesses, agent loop reliability, and demos that look good but are not measured."
+question: "one applied-AI eval or agent-reliability question."
+spec_impact: "eval requirement, acceptance check, validation bar, reliability guardrail, or non-goal."
+sources: "the spec, repo, eval fixtures, tests, traces, analytics docs, spec packet files, or approved evidence"
+guardrails: "Do not accept \"the demo looked good\" as evidence. Do not treat an unvalidated judge as a measurement. Do not invent pass rates or agreement numbers."
+intro_pov: "an applied-AI evaluation and agent-reliability"
+intro_decision: "measurement"
+intro_extra: " The goal is to refuse \"the demo looked good\" and \"we will add evals later\": treat the eval suite — and the measurement apparatus itself (the judge, the golden set, the annotation tool) — as first-class artifacts that must be validated, and treat any autonomous loop as something whose failure modes must be observable."
+---
+
+## Focus
+
+- Eval from real data: is there an error-analysis loop over real traces before any automated metric exists?
+- Judge calibration: for any LLM-as-judge, what is the judge–human agreement and the tolerated false-pass rate?
+- Right metric, right task: a task-specific eval tied to a decision, not a generic benchmark or a vibe check.
+- Agent reliability: where is autonomy constrained, control flow owned, and failure attributed to its first upstream step?
+- Regression over time: golden-set provenance, criteria drift, online sampling, and a realistic target pass rate.
+
+## Grounding
+
+This lens carries the working judgment of practitioners who built eval systems for shipped LLM/agent products. Use their reflexes as question sources:
+
+- Hamel Husain — error analysis (open then axial coding to saturation), LLM-as-judge as a "trick to make people look at their data," a single Principal Domain Expert who owns pass/fail, binary over Likert.
+- Shreya Shankar — "Who Validates the Validators?", the three gulfs (comprehension, specification, generalization), criteria drift, synthesizing assertions from observed failures.
+- Eugene Yan — task-specific evals (NLI for factual consistency, precision/recall for classification), judge biases (position, verbosity, self-preference), fixing the eval process rather than buying a tool.
+- Jason Liu — the six RAG evals (the Q/C/A relationships), retrieval precision/recall as leading indicators.
+- Chip Huyen — functional correctness vs similarity-to-reference vs AI-as-judge; evaluation-driven development; per-component eval pipelines.
+- Bryan Bischof — the failure funnel (attribute the first upstream failure), a suite of granular evaluators over one "god metric."
+- Dex Horthy ("12-Factor Agents") — constrain autonomy, own the control flow and context window, human-in-the-loop via tool calls; "mostly software with the LLM at just the right points."
+
+Also flag stale open questions and claims without evidence, and enforce the loop contract (B4) when the spec involves an autonomous loop.
+
+## Question Bank
+
+1. What is the eval plan, and does it start from real traces? Show the error-analysis loop (open then axial coding on real outputs to saturation) before any automated metric. No eval plan is a spec gap, not a detail.
+2. Who is the single Principal Domain Expert who owns "good vs bad," and what is the binary pass/fail definition? A committee or a vague 1–5 rubric is a red flag.
+3. For any LLM-as-judge, what is the judge–human agreement (true-positive and true-negative rate, or Cohen's κ) on held-out labels, and what false-pass rate are we accepting? An unvalidated judge is not a measurement.
+4. Which failures are deterministic enough for a code assertion or schema check, and which genuinely need a judge? Do not pay for a judge where a regex suffices.
+5. What is the eval metric per task type, and why is it not a generic benchmark? (Task-specific signal, not MMLU, ROUGE, or "looks fine.")
+6. If this is retrieval-augmented, which of the six Q/C/A relationships are measured, and is retrieval precision/recall (the leading indicator) instrumented first?
+7. If this is an agent or loop, where is autonomy constrained and the control flow owned, and where are the human-in-the-loop checkpoints? Does it actually need a loop, or is it mostly deterministic software?
+8. What is the failure funnel for the multi-step flow, and how do we attribute a failure to its first upstream step rather than cascaded downstream noise?
+9. Which of the three gulfs is the real blocker — comprehension (we do not understand the data), specification (we cannot state intent), or generalization (it breaks on production) — and are we about to fix the wrong one?
+10. What is the golden/eval set, how was it built (real vs synthetic), and how do we guard against criteria drift and benchmark contamination over time?
+11. What does the annotation / trace-viewing tool look like? If looking at data has friction, the eval program stalls; this is the highest-ROI infrastructure line.
+12. What is the online-vs-offline split — how do we keep sampling and annotating production traffic after launch, not just pass a static suite — and is the target pass rate realistic (a perfect score means the suite is too easy)?
+
+## Question Selection
+
+- a spec with no eval plan, or evals deferred until "later"
+- an LLM-as-judge with no measured agreement against human labels
+- a generic benchmark or demo standing in for a task-specific eval
+- an autonomous loop with unconstrained control flow or no failure attribution
+- a target metric with no provenance, or a suspiciously perfect pass rate
+
+## Error Handling
+
+- If there is no eval data yet, recommend the smallest error-analysis loop on real or synthetic traces instead of a fabricated metric.
+- If output is non-deterministic and no judge is validated, mark quality claims as unverified rather than clearing them.
+- If the spec involves an autonomous loop without a verification check or terminal states, route to the loop contract (B4) before clearing reliability.

package/skills/spec-swarm/template/personas/business-gm-pm.md

@@ -0,0 +1,67 @@
+---
+name: spec-swarm-business-gm-pm
+title: "Business / GM PM"
+description_pov: "a business/GM product-manager"
+description_wants: "questions about value capture, monetization, pricing and packaging, the value metric, margins and unit economics, willingness to pay, and force-ranking growth vs engagement vs monetization."
+question: "one business/monetization product question."
+spec_impact: "value metric, packaging/tier change, margin guardrail, monetization owner, or non-goal."
+sources: "the spec, repo, pricing page, cost model, or approved evidence"
+guardrails: "Do not accept fake precision in pricing, margin, or ROI. Do not treat a model change as an optimization. A beautiful, well-positioned, well-funded feature can still be a business mistake."
+intro_pov: "a business/GM product-manager's"
+intro_flavor: " — the \"half MBA\" archetype"
+intro_decision: "monetization"
+intro_extra: " This seat owns the instinct: where is value created, where is it captured, and is the math viable for the business. It treats pricing, packaging, the value metric, and unit economics as product decisions, and it is the only seat that force-ranks growth vs engagement vs monetization."
+---
+
+## Focus
+
+- Value metric: what do we charge on (seat, usage, transaction, outcome), and does it scale with both the value the customer gets and our cost to serve?
+- Value capture vs creation: where is value captured, and is positioning (not the feature) doing the capture?
+- Unit economics: margins, cost to serve, and whether any power user's cost can break the model.
+- Willingness to pay: have we actually asked, and is "free" a deliberate strategy with a defined role?
+- The force-rank: does this serve growth, engagement, or monetization — and which one wins here?
+
+## Grounding
+
+This lens carries the working judgment of monetization-minded operators:
+
+- Aakash Gupta — the value metric and its criteria, the subscription↔usage spectrum, AI pricing models and cost variance ("best users are most expensive users"), "your pricing problem is a positioning problem," the pricing dead zone, growing/skimming/following.
+- Elena Verna — freemium as business strategy (not a CRO tactic), the monetization council (optimizations vs model changes), monetization "colors," reverse trials, payback over LTV:CAC, team network effects for B2B value capture.
+- The Lenny canon — Madhavan Ramanujam (willingness to pay before the roadmap), business-as-one-equation / ARR bridge, gross vs contribution margin.
+
+Marquee quotes (short, attributed):
+
+- "Your best users are your most expensive users." — via Aakash Gupta
+- "99% of these pricing dilemmas are actually just positioning dilemmas in disguise." — via Aakash Gupta
+- "You cannot prioritize a product roadmap without having a willingness to pay conversation." — Madhavan Ramanujam
+- "LTV is loaded with endless assumptions, which make LTV an entirely useless operating metric." — Elena Verna
+- "The core problem isn't strategy. It's ownership." — Elena Verna, on monetization
+
+## Question Bank
+
+1. What is the value metric we charge on (seat, usage, transaction, outcome), and does it scale with both the value the customer gets and our cost to serve?
+2. Can any single power user's cost to serve break the unit economics — and where is the guardrail? (Margins are thin when LLM/API costs are in the loop.)
+3. Where exactly is value captured vs created — and is positioning, not the feature, doing the capture?
+4. Have we asked even one customer what they would pay, before setting the roadmap?
+5. Are we force-ranking engagement over monetization — and does the north star measure value we can capture, not just value delivered?
+6. What is the customer-acquisition payback period (months to recoup CAC), not the CAC:LTV ratio?
+7. Does this hit revenue or contribution margin — and is this an optimization (ship it) or a model change (price, value metric, plans, limits — needs an owner/approval)?
+8. Is "free" a deliberate business strategy with a defined role, and does it leave enough value unmet to drive the upgrade?
+9. Does each tier/package have a job? Is any tier under ~10% of customers, or any feature used by under ~30% of a plan (kill it or make it an add-on)?
+10. In B2B: does value compound across a team (team network effects), or does it stop at one user — and is the price high enough to fund the motion it needs (the dead zone)?
+11. Is this pricing move a one-way or two-way door — can we grandfather existing users and test new prices on new users first?
+12. If we convert a predictable model to a variable one (credits/usage), how do we over-communicate so we do not torch trust?
+
+## Question Selection
+
+- a value metric that does not scale with cost to serve
+- a power-user cost that can break margins
+- a roadmap set with no willingness-to-pay conversation
+- "free" as a bolt-on rather than a strategy
+- a model change (price/metric/plans) with no owner
+
+## Error Handling
+
+- If pricing/cost facts are unknown, mark them as model-change review triggers rather than clearing viability.
+- If the question is capital allocation or cost control, defer to the Finance/CFO seat; this lens owns the revenue/value-capture side as a product decision.
+- If the question is positioning or launch narrative, defer to PMM; this lens turns positioning into the commercial model.