whetstonehq 0.3.0__tar.gz

whetstonehq-0.3.0/.claude/skills/prd-generator/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: prd-generator
+description: Generate, critique, and refine PRDs, spec files, and roadmaps for initiative-level planning. Use to pressure-test and strengthen a PRD before planning. Triggers on "prd-generator", "prd generator".
+tags:
+  - documentation
+  - planning
+metadata:
+  status: trial
+---
+
+# PRD Generator
+
+## Philosophy
+
+This skill is framework-neutral. When coaching, always present multiple applicable frameworks, explain tradeoffs between them, and let the user choose. Never prescribe a single "right" methodology — pick the right tool for the context.
+
+Default to **critical feedback over validation**. A coach that just agrees is useless. Always identify gaps, challenge assumptions, and ask hard questions — then offer constructive paths forward.
+
+## Context
+
+This skill supports planning at initiative scope — features, epics, or projects spanning one or more cycles. In the `whetstone-begin-fast` pipeline it is Phase 4: refine and self-critique the `prd.md` that `prd-interview` produced, then surface the gaps before the review gate.
+
+For collaborative PRD creation from a brief, use the `prd-interview` skill.
+Planning artifacts live in `docs/planning/{slug}/` — see `prd-interview` for the directory convention.
+
+## Capabilities
+
+| Capability | Trigger Phrases | Output |
+|-----------|----------------|--------|
+| **Critique PRDs/Specs** | "review my PRD", "critique this spec", "what's missing" | Structured critique with severity ratings |
+| **Generate PRDs** | "write a PRD for", "create a spec", "draft requirements" | Complete PRD document (markdown) |
+| **Coach on Frameworks** | "how should I prioritize", "explain RICE", "opportunity sizing" | Framework comparison with worked examples |
+| **Review Roadmaps** | "review my roadmap", "prioritization feedback", "sequencing" | Prioritization analysis with alternative orderings |
+
+## Workflow 1: Critique PRDs/Specs
+
+When the user provides a PRD or spec for review:
+
+### Step 1 — Read the full document
+
+If a file is referenced, read it completely before responding. Never critique based on partial reads.
+
+### Step 2 — Score across dimensions
+
+Rate each dimension as 🔴 Critical Gap, 🟡 Needs Work, or 🟢 Strong:
+
+1. **Problem Definition** — Is the problem clearly stated? Is there evidence it's real and worth solving?
+2. **User Understanding** — Are target users defined? Are their needs validated, not assumed?
+3. **Success Metrics** — Are KPIs defined? Are they measurable, time-bound, and tied to outcomes? Is the held-out set they'd be measured on named?
+4. **Scope Clarity** — Is the boundary between in-scope and out-of-scope explicit? Hidden assumptions?
+5. **Edge Cases & Risks** — Are failure modes, dependencies, and technical risks identified?
+6. **Stakeholder Alignment** — Is it clear who approves, who builds, and who is impacted?
+7. **Feasibility Signal** — Has the engineering reality been considered? Rough effort estimates?
+8. **Reward Integrity & Never-Regress** *(Whetstone-specific)* — Does the reward stay execution-grounded (deterministic re-execution, observed-vs-claimed state) rather than resting on any model's opinion? Does the PRD say how a policy would try to cheat this, and why it can't? Does the promotion gate still require a proven gain on a held-out verified set, with an explicit `UNVERIFIED` path that is never counted as a win? Does the work stay local, and does it get *better* as open base models improve rather than being made redundant by them?
+
+### Step 3 — Identify the top 3 gaps
+
+Rank the most critical issues. For each: state what's missing or weak, explain WHY it matters (what goes wrong if not addressed), and suggest a specific fix or question to answer.
+
+### Step 4 — Ask the hard question
+
+End every critique with ONE pointed question the author probably hasn't considered. Frame it as: "The question I'd want answered before greenlighting this..."
+
+## Workflow 2: Generate PRDs
+
+When asked to generate a PRD, use progressive disclosure — ask clarifying questions first, then generate.
+
+### Step 1 — Gather inputs (minimum viable context)
+
+Ask the user for (skip any already provided): what problem, for whom; what success looks like (metrics/outcomes); known constraints (timeline, tech, dependencies); any prior art or competitive context.
+
+### Step 2 — Select PRD depth
+
+Offer the user a choice based on context:
+
+| Template | Best For | Depth |
+|----------|----------|-------|
+| **Lightweight Brief** | Small features, experiments, internal tools | 1-2 pages |
+| **Standard PRD** | Mid-size features shipping to users | 3-5 pages |
+| **Full Spec** | Large initiatives, platform changes, new products | 5-10+ pages |
+
+All three share the same section spine — they differ in depth, not structure:
+Problem Statement → Goals & Success Metrics → Users & Scenarios → Requirements (must/should/nice) → Technical Considerations (incl. reward integrity / promotion-gate impact) → Risks & Mitigations → Out of Scope. The Lightweight Brief collapses these to one-liners; the Full Spec adds Data Model, Task/Reward/Checkpoint Contracts, and Non-Functional Requirements.
+
+### Step 3 — Generate the PRD
+
+Write it following the chosen depth. Always include: explicit assumptions (labeled as such), open questions that still need answers (don't paper over gaps), and a "Risks & Mitigations" section (never skip this). Name the core-loop element (① verifier, ② nightly loop, ③ promotion gate, ④ morning report, ⑤ local/private — `CLAUDE.md`) the work belongs to, and place it in `docs/ROADMAP.md` once that file exists (it doesn't yet — say so rather than inventing a phase).
+
+**Never invent a number.** Targets are labeled as targets; only the verifier produces a result. `CLAUDE.md` lists the grounded external facts available to cite — anything beyond those is unverified and must be labeled as such.
+
+### Step 4 — Self-critique
+
+After generating, run the Critique workflow (Workflow 1) against your own output. Flag any 🔴 or 🟡 areas and note them at the end as "Areas to strengthen before sharing." In the `whetstone-begin-fast` pipeline these flagged gaps are exactly what you present at the ⛔ review gate.
+
+## Workflow 3: Coach on Frameworks
+
+When the user asks about frameworks or needs help choosing an approach:
+
+1. **Understand the decision context** — ask what decision they're trying to make.
+2. **Present relevant frameworks (always 2-3 minimum)** — for each: what it is (one sentence), when it shines, what to watch out for, and a worked example on their actual situation.
+3. **Recommend (but don't prescribe)** — state which you'd lean toward and why, framed as a recommendation.
+
+Quick index to draw from:
+
+- **Prioritization:** RICE, ICE, MoSCoW, Kano, Weighted Scoring, Cost of Delay / WSJF
+- **Problem discovery:** Jobs-to-Be-Done, Opportunity Solution Trees, Double Diamond, Problem Stack Ranking
+- **Strategy:** Porter's Five Forces, Blue Ocean, Playing to Win, Wardley Mapping
+- **Sizing:** TAM/SAM/SOM, Bottom-up opportunity sizing, Fermi estimation
+
+## Workflow 4: Review Roadmaps & Prioritization
+
+1. **Understand context** — time horizon, top goals/OKRs, constraints (team size, dependencies, deadlines).
+2. **Analyze current prioritization** — per item: alignment to a stated goal, sequencing logic (dependencies, "why now"), portfolio balance (quick wins / strategic / tech debt / experiments), and what's missing.
+3. **Propose alternative orderings** — at least 2:
+
+| Approach | Optimizes For | Tradeoff |
+|----------|--------------|----------|
+| **Impact-first** | Maximum outcome per unit time | May defer foundational work |
+| **De-risk first** | Reduce uncertainty early | Slower visible progress |
+| **Quick wins first** | Momentum and confidence | May delay strategic bets |
+| **Dependencies-first** | Unblock parallel work | Front-loads less exciting work |
+
+4. **Challenge the roadmap** — "What happens if you cut the bottom 20%?", "Which item are you least confident about, and why is it still on the list?", "If you could only ship ONE thing this cycle, which?"
+
+## Visual-First Preview (Always Do This)
+
+Before generating any document or detailed analysis, produce a compact visual preview first so the user can validate structure before committing to a full document. A PRD-structure tree is usually enough:
+
+```
+PRD: {slug}
+├─ Problem ........... {one line}
+├─ Goals/Metrics ..... {one line}
+├─ Users/Scenarios ... {one line}
+├─ Requirements ...... must:{n}  should:{n}  nice:{n}
+├─ Technical ......... {reward/gate impact in a phrase}
+├─ Risks ............. {top risk}
+└─ Out of scope ...... {one line}
+```
+
+Rules: show the visual BEFORE the full document; wait for confirmation/adjustments; keep it to one screen; use it as a conversation starter, then generate the full document.
+
+## Output Format
+
+- Default document format is **markdown** (`.md`) into `docs/planning/{slug}/`.
+- Keep coaching responses focused and actionable — avoid walls of text.
+- Use tables for comparisons and severity indicators (🔴🟡🟢) for assessments.
+- Always end coaching responses with a clear next step or question.
+
+## Anti-Patterns (Never Do These)
+
+1. **Never just validate** — if the PRD is solid, say so, but still find at least one area to push on.
+2. **Never prescribe a single framework** — always present alternatives with tradeoffs.
+3. **Never generate a PRD without flagging its own gaps** — self-critique is mandatory.
+4. **Never give generic advice** — tie everything to the user's specific context.
+5. **Never skip the hard question** — every review ends with a challenging, specific question.
+6. **Never wave through base-model drift** — if a PRD's core value is training a frontier base model rather than sharpening an open one on the user's tasks, flag it against the `CLAUDE.md` wedge before approving.
+7. **Never wave through a judge dressed as a reward** — if a PRD's reward rests on a model's opinion rather than deterministic re-execution, or lets the gate promote on an unproven gain, or renders `UNVERIFIED` as a win, that's a 🔴 regardless of how good the rest is.
+8. **Never wave through a number the verifier didn't produce** — a projected gain presented as a result is a 🔴, and so is a success metric with no named held-out set behind it.

whetstonehq-0.3.0/.claude/skills/prd-interview/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: prd-interview
+description: Conduct a collaborative product requirements interview between PM and engineering. Use when turning a brief or feature idea into a structured PRD and aspect-level specs through guided discovery and pressure-testing. Triggers on "prd interview", "requirements interview", "prd-interview".
+tags:
+  - documentation
+  - planning
+metadata:
+  status: trial
+---
+
+# PRD Interview
+
+Conduct a structured product requirements interview to turn a brief or feature idea into a complete PRD.
+This is a collaborative exercise — the PM hat brings product context, the engineering hat brings technical reality.
+Challenge assumptions. Pressure-test scope. Document what survives.
+
+Do not create files until the Document phase.
+If the tool supports a read-only or plan mode, switch to it now.
+
+## Context
+
+This skill is the first step in the brief-to-code pipeline (it's Phase 3 of `whetstone-begin-fast`).
+Input is typically the gathered issue/brief dump at `docs/planning/_card/issue.md` plus the deep-dig understanding note.
+Output is a structured PRD plus aspect-level specs that feed directly into `tech-plan`.
+
+**Whetstone guardrail:** before documenting, sanity-check the work against `CLAUDE.md`. The moat is the **verified self-improvement loop** — the execution-grounded verifier, the never-regress promotion gate, and the accumulated verified-improvement data. It is **not** a frontier base model (we sharpen an open base on the user's tasks), and it is **not** an LLM judge (a model may help *distill*; only execution may *reward*). If the requirements drift toward training a base model, toward scoring the policy by a model's opinion, or toward anything that needs the user's data or training to leave the machine, flag it in the interview, not after.
+
+## Discover & Challenge
+
+Read the user's input — the issue dump, brief, or pasted requirements.
+Read key files to understand the current architecture. Whetstone is **greenfield**: today that means `CLAUDE.md` (the wedge, the five core-loop elements, the guardrails) and `VISION.md`. `docs/ROADMAP.md`, `docs/technical/ARCHITECTURE.md`, and `docs/product/PRODUCT_SPEC.md` are named in `CLAUDE.md` but **not yet written** — read them if they now exist, and say plainly that they don't if they don't. The loop will live under `src/whetstone/` once it exists.
+Ask if the user is aware of prior art or similar internal/external solutions — offer to search if not.
+
+Then pressure-test. Do not soften these. Frame as collaborative due diligence, not criticism.
+
+- "What happens if we don't build this?"
+- "Imagine this launched 6 months ago and failed. What went wrong?"
+- "What are we choosing NOT to build if we build this?"
+- "How would a policy cheat at this?" — the reward-hacking question. Ask it about any work that touches the reward, and treat "it can't" as an unfinished answer.
+
+If the user has heard the challenge and wants to proceed, proceed.
+
+Fill remaining gaps with focused questions, 2-3 at a time, grouped by topic:
+
+- **Users & Problem**: Who has this problem? What's the cost of the status quo?
+- **Success**: How will we measure it? Target numbers? What is the held-out set the number comes from?
+- **Scope**: What is explicitly out of scope?
+- **Requirements**: Must-have vs. should-have vs. nice-to-have?
+- **Technical Fit**: Stack constraints? Which core-loop element does this belong to (① verifiable task family + verifier, ② nightly improvement loop, ③ never-regress promotion gate, ④ signed morning report, ⑤ local + private), and are its dependencies built? Where does it sit in the tasks → rollouts → reward → distillation → gate → report pipeline?
+- **Reward & gate impact**: Does this change what the reward measures, or what the gate will promote on? If it touches the reward, how does the reward stay execution-grounded — what is *re-executed*, and what observed-vs-claimed state is compared? If it touches the gate, what counts as a win, and what is the explicit `UNVERIFIED` path when the gain can't be evaluated? (`UNVERIFIED` is never a win.)
+- **Locality**: Does anything about this design require the user's tasks, data, or training to leave the box? A BYOK cloud teacher is allowed for distillation only.
+
+Skip what you can infer.
+Challenge vague answers — ask for examples, numbers, edge cases.
+Flag technical pitfalls from the code/docs you read — don't wait to be asked.
+
+**Stop when** the problem is clear without guessing, success metrics are measurable, must-haves have testable criteria, out-of-scope is explicit, and major technical risks are identified.
+
+## Confirm
+
+Summarize: the problem, proposed approach, scope, success criteria, risks, and unresolved concerns.
+If the challenge raised serious doubts, say so directly. The user decides, but with eyes open.
+Ask the user to confirm before writing.
+Confirm the feature slug for the directory name (e.g., `task-verifier`, `promotion-gate`). Do not name the slug `<type>-<id>` — the id lives in the branch/PR.
+
+## Document
+
+Omit sections that don't apply — do not write "Not applicable."
+
+**Filename:** `prd.md`
+**Location:** `docs/planning/{slug}/` — slug is the feature name confirmed during the Confirm phase.
+Create the directory if needed. User can override location.
+Examples: `docs/planning/task-verifier/prd.md`, `docs/planning/promotion-gate/prd.md`.
+
+The feature directory is the workspace for all planning artifacts.
+This skill can continue into aspect decomposition and create `spec.md` files.
+`tech-plan` then creates implementation plans inside those aspect directories:
+
+```
+docs/planning/{slug}/
+├── prd.md                        ← this skill's output
+├── {aspect}/                     ← one directory per aspect
+│   ├── spec.md                   ← this skill's decomposition output
+│   ├── plan_YYYYMMDD.md          ← tech-plan output
+│   └── ...                       ← team additions
+└── ...                           ← research, design, ADRs, etc.
+```
+
+### PRD structure
+
+- **Problem Statement**: What problem are we solving? For whom? Evidence it's real.
+- **Goals & Success Metrics**: What does success look like? How will it be measured, and on what held-out set? Label any target as a target, never as a result.
+- **User Personas & Scenarios**: Who uses this and in what context? (Whetstone ICP: the engineer who wants a model that's measurably better at *their* tasks by morning, privately, and who won't trust a gain they can't check.)
+- **Requirements**: Core features and behaviors, prioritized as must-have, should-have, nice-to-have.
+- **Technical Considerations**: Architecture fit, constraints, dependencies, integration points. Call out reward-hacking surface and promotion-gate impact explicitly, and name the core-loop element (①–⑤) this belongs to.
+- **Risks & Open Questions**: Unresolved items, potential blockers, what could go wrong. Include the reward-hacking risk explicitly for anything touching the reward.
+- **Out of Scope**: Explicitly excluded features or concerns.
+
+Include when relevant: Data Model, Task/Reward/Checkpoint Contracts, Non-Functional Requirements.
+
+After writing, surface open questions and unresolved risks.
+Then offer to continue immediately into aspect decomposition (below).
+
+## Aspect Decomposition Mode (same skill)
+
+Use this mode after the PRD is confirmed, or when a user comes back later with an existing PRD and asks to break it down.
+
+1. Propose aspect candidates (typically 2-8), each with a one-line boundary.
+2. Confirm aspect names with the user (`kebab-case` directory names).
+3. For each confirmed aspect, write or update `docs/planning/{slug}/{aspect}/spec.md`.
+4. Keep each spec focused and buildable by one engineer (or agent) at a time.
+
+Each `spec.md` should include:
+
+- Problem slice and user outcome for this aspect
+- In-scope requirements
+- Out-of-scope boundaries
+- Acceptance criteria (testable — the repo is test-first, so these become the failing tests written before the code). For verifier work, include at least one **adversarial** criterion: a case a reward-hacking policy would pass under a weaker check and must fail under this one.
+- Dependencies and sequencing notes
+- Open questions or risks specific to this aspect
+
+If the user only wants the PRD now, stop after `prd.md`.
+`tech-plan` can pick up later and request aspect selection if specs are still missing.
+
+## Edge Cases
+
+- **Update existing PRD**: Read the file, ask what changed, update in place.
+- **Existing PRD, no aspect specs yet**: Run Aspect Decomposition Mode without re-running full discovery.
+- **User starts with prd-interview only (no prd-generator)**: Continue normally; this skill can produce both `prd.md` and aspect `spec.md` files.
+- **User says "just write it"**: Write from what you have, but flag gaps in Open Questions and still include at least one challenge question.
+- **Detailed spec already provided**: Review against structure, focus on the challenge phase, skip covered sections.
+- **No brief exists**: Run full discovery from conversation. Note that the PRD is based on discussion rather than an artifact.
+- **Greenfield with no code to read**: Expected today. Ground the technical section in `CLAUDE.md` and `VISION.md` and say plainly that no implementation exists yet rather than describing one that doesn't.
+- **No roadmap to place the work in**: `docs/ROADMAP.md` isn't written yet. Place the work on the core loop (①–⑤) instead, and note the missing roadmap as an open question rather than inventing a phase.

whetstonehq-0.3.0/.claude/skills/tech-plan/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: tech-plan
+description: Create a phased technical implementation plan from planning artifacts in docs/planning (PRD + aspect spec). Use after prd-interview when ready to execute a specific aspect. Triggers on "tech plan", "implementation plan", "plan from PRD".
+tags:
+  - planning
+  - documentation
+metadata:
+  status: trial
+---
+
+Create a phased technical implementation plan from planning artifacts under `docs/planning/{slug}/`.
+Inputs can come directly from `prd-interview`; do not require `prd-generator`.
+This is Phase 5 of `whetstone-begin-fast` — the plan it produces is executed in Phase 6 through the agents team under strict TDD.
+
+If the user provided artifacts in context (attached file, pasted content, or referenced path), use them directly.
+Otherwise, search the workspace for:
+
+- PRDs matching `docs/planning/*/prd.md`
+- Aspect specs matching `docs/planning/*/*/spec.md`
+
+Analyze the current codebase, then create a detailed **Implementation Plan** optimized for autonomous agent execution.
+Whetstone is **greenfield**: today the authoritative reading is `CLAUDE.md` (the wedge, the five core-loop elements, the guardrails) and `VISION.md`. `docs/ROADMAP.md`, `docs/technical/ARCHITECTURE.md`, and `docs/product/PRODUCT_SPEC.md` are named in `CLAUDE.md` but not yet written — read them if they now exist and say plainly that they don't if they don't. The loop will live under `src/whetstone/`.
+The plan should be structured so the agent team can work through it systematically with minimal human intervention.
+
+## Handoff Contract
+
+- **Feature requirements source:** `docs/planning/{slug}/prd.md`
+- **Aspect requirements source (preferred):** `docs/planning/{slug}/{aspect}/spec.md`
+- **Plan output (required):** `docs/planning/{slug}/{aspect}/plan_YYYYMMDD.md`
+
+Plan one aspect at a time. If a feature has multiple aspects, create one plan file per aspect.
+
+**Filename:** `plan_YYYYMMDD.md` (YYYYMMDD is today's date, e.g., `plan_20260726.md`)
+**Location:** the aspect directory (e.g., `docs/planning/task-verifier/reward-contract/plan_20260726.md`). Create it if needed.
+If the user provided an aspect spec from a different location, write the plan alongside that spec.
+If only a PRD is provided (no aspect spec), ask which aspect to plan, create or update `spec.md` for that aspect, then write the plan in that aspect directory.
+If the PRD was pasted or attached (no file path), ask the user to confirm both feature slug and aspect name, then write to `docs/planning/{slug}/{aspect}/plan_YYYYMMDD.md`.
+
+## Deliverables
+
+### 1. Project Setup Checklist
+
+- Directory/module structure to create (under `src/whetstone/`, `tests/`, or the dashboard once it exists)
+- Configuration needed (pyproject entries, env, pinned tool versions and pinned model/runtime versions for reproducible training and eval)
+- Dependencies to add (with specific versions where critical) — Python via `uv add`, dashboard via `npm install`
+- **Greenfield:** if `pyproject.toml` / `uv.lock` / `src/` don't exist yet, scaffolding them is part of the plan's first phase — say so explicitly rather than assuming `uv sync` works. Test-first still holds: the failing test comes before the package.
+
+### 2. Implementation Phases
+
+Break the build into sequential phases that can be executed autonomously. For each phase:
+
+**Phase N: [Name]**
+
+- **Goal:** What this phase accomplishes
+- **Prerequisites:** What must exist before starting
+- **Files to create/modify:** Explicit list
+- **Validation:** How to verify the phase is complete (`uv run pytest <path>`, expected outputs; the dashboard's test/build commands for UI work)
+- **Commit message:** Suggested commit message for this phase
+
+Each phase is a unit the agents team can own end-to-end under TDD (RED → GREEN → REFACTOR).
+
+### 3. File-by-File Build Order
+
+Ordered list of every file to create, with: filepath, one-line purpose, key functions/components it exports, and dependencies on other files.
+
+### 4. Testing Strategy
+
+- Unit tests to write (mapped to implementation phases) — these are written **first** in Phase 6
+- Integration tests
+- Manual verification steps
+- Test commands: `uv run pytest` (Python core), dashboard test/build commands for UI
+- **Adversarial tests are mandatory for anything touching the reward.** A verifier is worth what it rejects. For each reward or gate change, plan the test that a cheating policy would pass under a weaker check and must fail under this one — degenerate solutions, edited timers/asserts, mutated fixtures, claimed-but-not-observed state. "Accepts a correct answer" is half a test.
+- **Tests are deterministic and run with no network.** Fixed seeds, fixed task inputs, no wall-clock dependence. Any model call (the BYOK teacher used in distillation) sits behind an injectable seam and never runs in CI. A test whose result depends on a live model is not a test.
+- Lift acceptance criteria from the aspect `spec.md` rather than inventing parallel ones.
+
+### 5. Environment, Determinism & Locality
+
+- Environment variables needed (BYOK teacher keys, if any — for distillation only, never for the reward)
+- External tools/services to configure (and how they're pinned): local runtime (Ollama / vLLM / transformers), model weights and revisions
+- Local setup: `uv sync`; dashboard `npm install`
+- Note determinism requirements explicitly — a reported gain has to be reproducible or it isn't a gain. Pin seeds, model revisions, and task sets; record them alongside any result. A number produced by an unpinned run is `UNVERIFIED`.
+- **Note the train/held-out boundary.** State which data the phase touches and confirm nothing from the held-out verified set can reach training. Leakage is silent and it invalidates every number downstream — plan the check, don't assume it.
+- Confirm nothing in the plan requires the user's tasks, data, or training to leave the machine.
+
+### 6. Edge Cases & Error Handling
+
+- Known edge cases to handle
+- Error states to account for, and **what outcome each produces**. Given Whetstone's contract, name the explicit `UNVERIFIED` path with its cause for anything that can fail to evaluate (verifier can't execute the task, run crashed mid-eval, non-deterministic result, held-out set unavailable, checkpoint won't load). A silent pass, or a fallback that promotes anyway, is never acceptable — the gate's default is *don't promote*.
+- Fallback behaviors
+
+### 7. Agent Execution Notes
+
+- Suggested checkpoints for human review
+- Areas likely to need iteration or debugging
+- Sections where the agent should ask for clarification before proceeding
+
+## Guidelines
+
+- Be extremely explicit — assume no implicit knowledge
+- Prefer small, testable increments over large monolithic steps
+- Each phase should result in runnable (even if incomplete) code, with the suite kept green
+- Flag any spec ambiguities that could block implementation
+- Note assumptions clearly
+- Optimize for autonomous execution by the agents team with minimal back-and-forth
+- Don't plan work that trains a frontier base model, or that rewards the policy with a model's opinion instead of re-execution — flag it against the `CLAUDE.md` wedge instead
+- Don't plan a capability whose dependencies aren't built. The verifier comes first: the loop, the gate, and the report are all downstream of it. Abstractions are earned by the second implementation, not designed for the first.
+- Don't plan a second task family before the first one's verifier is airtight
+
+## Edge Cases
+
+- **Greenfield vs. existing codebase**: For greenfield, include full setup. For existing code, skip scaffolding and focus on integration points and impact analysis. Whetstone is greenfield today — expect the setup path.
+- **No aspect spec exists yet**: Derive a candidate aspect list from the PRD, ask the user to choose one, draft `spec.md`, confirm, then plan.
+- **Incomplete PRD**: If the PRD lacks testable acceptance criteria or measurable metrics, flag this and recommend running `prd-interview` before planning.
+- **PRD with no named held-out set**: For anything that claims an improvement, the plan can't validate without one. Flag it and get the eval set defined before planning the phase that would report a number.
+- **Multiple PRDs**: Separate plans per PRD unless they share infrastructure, in which case note shared phases.
+- **Multiple planning sessions**: If an aspect has multiple `plan_YYYYMMDD.md` files, base the new plan on the current `prd.md` + `spec.md`. Create a new plan file with today's date.
+- **PRD with flagged gaps**: If `prd-interview` produced the PRD via the "just write it" path, gaps may be marked. Note these in the plan and recommend resolution before the affected phase.

whetstonehq-0.3.0/.claude/skills/whetstone-begin/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: whetstone-begin
+description: Use when starting work on a Whetstone unit of work (a GitHub issue id or an inline brief) and you need stakeholder proposals (technical + non-technical PDFs with diagrams) before planning. Triggers on "whetstone-begin", "wb", "wb bug 12", "wb feat task-verifier", "begin full".
+arguments: "type id"
+---
+
+# Whetstone Begin (Full Track)
+
+## Overview
+
+Same pipeline as `whetstone-begin-fast`, plus a **proposal phase**: after the PRD is approved, produce diagrams and two review PDFs (technical + non-technical) for stakeholders, get approval, then plan.
+
+**Invocation:** `wb <type> <id>` — e.g. `wb bug 12`, `wb feat task-verifier`.
+Arguments and conventions (type set, `<type>/<id>/aliz` branch, descriptive slug, worktree from `master`, GitHub-issue-or-inline-brief source) are identical to `whetstone-begin-fast`.
+
+The two non-negotiables carry over from `whetstone-begin-fast`: **always work through the agents team** (every phase, including diagrams and the two proposals), and **implementation is test-first** via `superpowers:test-driven-development`, executed by the agents team.
+
+## Pipeline
+
+**REQUIRED SUB-SKILL:** Use `whetstone-begin-fast` for the base pipeline.
+
+Run its **Phase 0 → Phase 4 and the ⛔ PRD review gate exactly as written** (worktree → gather context → deep dig → `prd-interview` → `prd-generator` → stop for PRD approval).
+
+**Then, instead of going straight to tech-plan, insert Phase A below. Only after Phase A's approval gate do you run `whetstone-begin-fast`'s Phase 5 (tech-plan) and Phase 6 (implement — TDD via the agents team).**
+
+### Phase A — Proposals (diagrams → PDFs)
+
+Detailed steps, proposal structure, and `md-to-pdf` invocation: see `references/proposals.md`.
+
+1. **Diagram** — Use `excalidraw`. From the approved PRD, draw as many diagrams as the work needs (system/architecture, data flow, sequence, before/after, etc.). Save to `docs/planning/{slug}/diagrams/*.excalidraw`.
+2. **Export** — Use `excalidraw-to-svg` to render every diagram to `.svg` alongside the source.
+3. **Write two proposals** (markdown, in `docs/planning/{slug}/proposals/`), embedding the SVGs. Both filenames are prefixed with the type and id so stakeholders can identify the source at a glance:
+   - `<type>-<id>-technical-proposal.md` (e.g. `feat-task-verifier-technical-proposal.md`) — for engineers: architecture, components, data flow, risks, effort.
+   - `<type>-<id>-non-technical-proposal.md` — for stakeholders: problem, value, what changes for users, timeline, plain language.
+   Generate the two in parallel (see Agents team).
+4. **PDF** — Use `md-to-pdf` to produce `<type>-<id>-technical-proposal.pdf` and `<type>-<id>-non-technical-proposal.pdf`.
+
+### ⛔ Approval gate — STOP
+
+Present both PDFs. **Wait for the user's explicit approval** of the proposals before planning. Do not auto-advance.
+
+### Final phases — Plan & implement
+
+Run `whetstone-begin-fast`'s **Phase 5 (tech-plan)** → `docs/planning/{slug}/{aspect}/plan_YYYYMMDD.md`, then its **Phase 6 (implement)** — strict TDD (`superpowers:test-driven-development`) executed through the agents team (`superpowers:subagent-driven-development`), one agent per plan task, branch kept green (`uv run pytest`, once the Python core exists).
+
+## Artifact layout (inside the worktree)
+
+```
+docs/planning/
+├── _card/issue.md                    ← gh dump or inline brief
+├── {slug}/prd.md                     ← PRD (approved at the first gate)
+├── {slug}/diagrams/*.excalidraw|.svg ← Phase A
+├── {slug}/proposals/<type>-<id>-technical-proposal.{md,pdf}
+├── {slug}/proposals/<type>-<id>-non-technical-proposal.{md,pdf}
+└── {slug}/{aspect}/plan_*.md         ← tech-plan
+```
+
+## Agents team (mandatory)
+
+Run **every** phase through the agents team — never serially in the main thread.
+
+**REQUIRED SUB-SKILL:** Use `superpowers:dispatching-parallel-agents`; use `superpowers:subagent-driven-development` for Phase 6.
+
+- Base pipeline: fan out context-gathering across related issues/PRs (as in `whetstone-begin-fast`).
+- Phase A: generate independent diagrams with parallel agents; write the technical and non-technical proposals concurrently (two agents, same PRD + SVGs).
+- Phase 6: one agent per independent plan task, each in strict TDD.
+
+## Common mistakes
+
+| Mistake | Fix |
+|---|---|
+| Writing proposals before the PRD is approved | Phase A starts only after the first ⛔ gate |
+| One proposal for both audiences | Always two: technical and non-technical |
+| Embedding `.excalidraw` instead of `.svg` | PDFs embed the exported SVGs |
+| Skipping the proposal approval gate | Proposals must be approved before tech-plan |
+| Diagrams/PDFs outside the worktree | Everything lives under the worktree's `docs/planning/{slug}/` |
+| Drawing a projected gain as if it were measured | A proposal states the target and says it's unmeasured; only the verifier produces a real delta |
+| A diagram whose reward arrow ends at a model | The reward comes from execution, never from a judge — draw it that way |
+| Implementing serially or test-after | Phase 6 is agents-team + strict TDD (RED before GREEN) |

whetstonehq-0.3.0/.claude/skills/whetstone-begin/references/proposals.md

@@ -0,0 +1,99 @@
+# Phase A — Diagrams & proposal PDFs
+
+Runs after the PRD approval gate. Everything is written inside the worktree under
+`docs/planning/{slug}/`.
+
+## 1. Diagrams (`excalidraw`)
+
+Use the `excalidraw` skill. Decide how many diagrams the work actually needs —
+don't pad. Typical set for Whetstone:
+
+| Diagram | When to include |
+|---|---|
+| System / architecture | Almost always — where the change lives in the nightly loop: task family → verifier → self-play/RL → distillation → promotion gate → morning report |
+| Data flow | Data moves across steps (user's tasks → rollouts → execution-grounded reward → training set → checkpoint → held-out eval → report) |
+| Sequence | A multi-step interaction matters (a night: sample tasks, roll out, verify, train, evaluate, promote-or-discard, report) |
+| Before / after | Behavior or structure changes visibly |
+| State machine | A checkpoint lifecycle changes (candidate → evaluated → promoted / rejected / `UNVERIFIED`) |
+
+Save sources to `docs/planning/{slug}/diagrams/`, descriptive names
+(e.g. `architecture.excalidraw`, `nightly-loop.excalidraw`).
+
+**Every text element must set `fontFamily: 2` (Helvetica)** — the excalidraw default is hand-drawn (Virgil/Excalifont) and unreadable in stakeholder PDFs. See the excalidraw skill's Rule 5.
+
+**Diagram the loop honestly.** Two rules, and they are the whole product:
+
+- **The reward arrow ends at execution, never at a model.** If a diagram shows where the reward comes from, it comes from re-execution against the verifier. A cloud teacher model may appear — but only on the *distillation* path, never on the reward path. A diagram that shows a model scoring the policy is drawing a different product.
+- **The gate has three exits, not one.** Promotion is `promoted` / `rejected` / `UNVERIFIED`, and `UNVERIFIED` is never collapsed into `promoted` for visual tidiness. If the diagram shows a gain, label whether it's a *target* (unmeasured) or a *measured* delta on the held-out verified set.
+
+## 2. Export to SVG (`excalidraw-to-svg`)
+
+Use the `excalidraw-to-svg` skill to render every `.excalidraw` to a sibling `.svg`.
+Batch-export the whole `diagrams/` directory. SVG (not PNG) keeps text crisp in the PDF.
+
+## 3. Write the two proposals
+
+Markdown, in `docs/planning/{slug}/proposals/`. Embed the SVGs with **relative** paths
+(`../diagrams/architecture.svg`) so `md-to-pdf` inlines them. Generate the two
+concurrently — same PRD + diagrams, different audience.
+
+### `<type>-<id>-technical-proposal.md` (engineers)
+
+Filename is prefixed with the type and id (e.g. `feat-task-verifier-technical-proposal.md`) so stakeholders can identify which unit of work a proposal belongs to at a glance.
+
+- **Summary** — one paragraph: what we're building and why.
+- **Current state** — how it works today (link before/after diagram).
+- **Proposed design** — architecture + components (embed architecture/data-flow/sequence SVGs).
+- **Data & interface changes** — task format, verifier contract, reward signal, checkpoint/eval artifacts, report schema.
+- **Risks & trade-offs** — failure modes, reward-hacking surface introduced or closed, alternatives considered.
+- **Effort & sequencing** — rough phases, dependencies. Name which core-loop element (① verifier, ② nightly loop, ③ promotion gate, ④ morning report, ⑤ local/private — `CLAUDE.md`) this belongs to, and the roadmap phase once `docs/ROADMAP.md` exists.
+- **Open questions** — carried from the PRD.
+
+### `<type>-<id>-non-technical-proposal.md` (stakeholders)
+
+Same naming convention (e.g. `feat-task-verifier-non-technical-proposal.md`).
+
+- **The problem** — in plain language, no jargon.
+- **What we'll do** — the solution at a high level (embed a simplified diagram).
+- **Why it matters** — value to someone who wants their model to get better at their own work, overnight, without trusting a number they can't check.
+- **What changes for users** — visible impact.
+- **Timeline** — rough, in weeks, not story points.
+- **Risks** — stated honestly, in plain terms.
+
+Keep the non-technical version free of stack names, code, and acronyms unless defined (spell out RL, RLVR, LoRA, distillation the first time, or drop them). Don't claim the loop proves more than it checks: a projected improvement is a target, not a result. If the honest answer is "we don't know the size of the gain yet, that's what this measures", say exactly that — an unhyped number is the product's whole positioning.
+
+## 4. Convert to PDF (`md-to-pdf`)
+
+Use the `md-to-pdf` skill. On macOS, point Puppeteer at system Chrome. Output lands
+next to the input as `<name>.pdf`.
+
+⚠️ **The proposals embed `../diagrams/*.svg`, which sits ABOVE the `proposals/` folder.**
+md-to-pdf's file server is rooted at the markdown's own directory by default, so `../` paths
+**silently render as broken images**. You MUST pass `--basedir ..` (the `{slug}` dir, which
+contains both `proposals/` and `diagrams/`):
+
+```bash
+cd docs/planning/{slug}/proposals
+PUPPETEER_EXECUTABLE_PATH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
+  md-to-pdf <type>-<id>-technical-proposal.md --basedir ..
+PUPPETEER_EXECUTABLE_PATH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
+  md-to-pdf <type>-<id>-non-technical-proposal.md --basedir ..
+```
+
+Result: `<type>-<id>-technical-proposal.pdf` and `<type>-<id>-non-technical-proposal.pdf`.
+
+**Verify before the approval gate (do not skip):** a missing image does NOT fail the command,
+so you must *look* at the output. Render a page to an image and inspect it:
+
+```bash
+pdftoppm -png -r 70 -f 1 -l 1 <type>-<id>-technical-proposal.pdf /tmp/check   # then Read /tmp/check-1.png
+```
+
+Both PDFs must exist, be non-trivial in size, and show the diagrams (not broken-image icons).
+If an image is broken, the path escaped the basedir — fix `--basedir`/filenames (URL-encode
+spaces as `%20`) and re-run.
+
+## 5. Approval gate
+
+Present both PDFs to the user and **stop**. Only after explicit approval continue to the
+`tech-plan` phase.