From f4d9ff922d29b57e27d84b8c2b607f80a93b0d04 Mon Sep 17 00:00:00 2001 From: cis2042 Date: Fri, 23 Oct 2026 12:15:58 +0800 Subject: [PATCH 1/2] feat: add complete product design handoff validation skill --- docs/README.skills.md | 1 + skills/product-design-harness/LICENSE | 21 + skills/product-design-harness/SKILL.md | 126 ++ .../resources/agents/README.md | 16 + .../agents/business-flow-reviewer.md | 44 + .../resources/agents/claim-analyst.md | 24 + .../resources/agents/council-facilitator.md | 60 + .../agents/evidence-flow-reviewer.md | 47 + .../resources/agents/registry.json | 41 + .../resources/agents/uncertainty-reviewer.md | 28 + .../resources/agents/user-flow-reviewer.md | 47 + .../resources/assets/decision-gate.svg | 46 + .../resources/assets/harness-sequence.svg | 45 + .../resources/docs/ADOPTION.md | 114 ++ .../resources/docs/ANTI-PATTERNS.md | 41 + .../resources/docs/CLAIMS.md | 59 + .../docs/CODING-HARNESS-COMPARISON.md | 91 ++ .../resources/docs/CONTRACTS.md | 94 ++ .../resources/docs/COUNCIL.md | 109 ++ .../resources/docs/DECISION-RULES.md | 91 ++ .../resources/docs/GLOSSARY.md | 44 + .../resources/docs/HARNESS.md | 284 +++++ .../resources/docs/LEARNING-LOOP.md | 46 + .../resources/docs/LIVE-CODING.md | 173 +++ .../resources/docs/MULTI-AGENT-ALIGNMENT.md | 59 + .../resources/docs/OPERATING-PROTOCOL.md | 106 ++ .../resources/docs/ORCHESTRATION.md | 132 ++ .../resources/docs/PRINCIPLES.md | 112 ++ .../resources/docs/README.md | 19 + .../resources/docs/UNCERTAINTY.md | 87 ++ .../resources/docs/UX3.md | 162 +++ .../docs/rfcs/0001-override-protocol.md | 155 +++ .../resources/examples/README.md | 22 + .../resources/examples/evidence-response.json | 42 + .../resources/examples/feature-gate-review.md | 87 ++ .../resources/examples/human-decision.json | 18 + .../examples/live-coding-context-pack.json | 103 ++ .../examples/live-coding-product-brief.json | 130 ++ .../examples/live-coding-review.json | 121 ++ .../examples/quick-context-pack.json | 104 ++ .../resources/examples/quick-gate-review.json | 128 ++ .../resources/examples/quick-gate-review.md | 51 + .../resources/examples/red-team-review.json | 33 + .../examples/standard-gate-review.json | 127 ++ .../examples/stop-reframe-review.json | 141 +++ .../resources/examples/stop-reframe-review.md | 18 + .../resources/examples/ux3-council-input.json | 269 ++++ .../examples/ux3-council-review.json | 170 +++ .../resources/examples/ux3-council-review.md | 74 ++ .../resources/examples/verdict-override.json | 29 + .../resources/examples/verdict-override.md | 29 + .../resources/knowledge/ontology.json | 191 +++ .../resources/knowledge/rules.json | 777 ++++++++++++ .../resources/knowledge/source-chapters.json | 104 ++ .../resources/prompts/README.md | 11 + .../resources/prompts/claim-analysis.md | 31 + .../resources/prompts/gate-review.md | 61 + .../resources/prompts/intake.md | 34 + .../resources/prompts/mode-selector.md | 42 + .../resources/prompts/red-team.md | 28 + .../resources/prompts/start-review.md | 57 + .../resources/prompts/ux3-council.md | 44 + .../resources/requirements-dev.txt | 1 + .../resources/schemas/README.md | 24 + .../schemas/actor-boundary.schema.json | 51 + .../schemas/claim-analysis.schema.json | 32 + .../resources/schemas/claim.schema.json | 117 ++ .../schemas/context-pack.schema.json | 284 +++++ .../schemas/council-input.schema.json | 83 ++ .../schemas/decision-rule.schema.json | 121 ++ .../schemas/evidence-request.schema.json | 71 ++ .../schemas/evidence-response.schema.json | 27 + .../resources/schemas/evidence.schema.json | 109 ++ .../schemas/human-decision.schema.json | 71 ++ .../resources/schemas/ontology.schema.json | 183 +++ .../schemas/product-brief.schema.json | 238 ++++ .../schemas/red-team-review.schema.json | 111 ++ .../schemas/review-result.schema.json | 1080 +++++++++++++++++ .../schemas/reviewer-verdict.schema.json | 188 +++ .../schemas/session-config.schema.json | 26 + .../schemas/uncertainty-review.schema.json | 52 + .../schemas/verdict-override.schema.json | 93 ++ .../resources/scripts/check_override.py | 90 ++ .../resources/scripts/check_review.py | 175 +++ .../resources/scripts/jev_gate.py | 164 +++ .../resources/templates/README.md | 13 + .../resources/templates/context-pack.md | 117 ++ .../resources/templates/decision-log.md | 48 + .../resources/templates/gate-review.md | 97 ++ .../resources/templates/override-ledger.md | 27 + .../resources/templates/product-brief.md | 118 ++ .../resources/templates/ux3-council-review.md | 50 + 92 files changed, 9461 insertions(+) create mode 100644 skills/product-design-harness/LICENSE create mode 100644 skills/product-design-harness/SKILL.md create mode 100644 skills/product-design-harness/resources/agents/README.md create mode 100644 skills/product-design-harness/resources/agents/business-flow-reviewer.md create mode 100644 skills/product-design-harness/resources/agents/claim-analyst.md create mode 100644 skills/product-design-harness/resources/agents/council-facilitator.md create mode 100644 skills/product-design-harness/resources/agents/evidence-flow-reviewer.md create mode 100644 skills/product-design-harness/resources/agents/registry.json create mode 100644 skills/product-design-harness/resources/agents/uncertainty-reviewer.md create mode 100644 skills/product-design-harness/resources/agents/user-flow-reviewer.md create mode 100644 skills/product-design-harness/resources/assets/decision-gate.svg create mode 100644 skills/product-design-harness/resources/assets/harness-sequence.svg create mode 100644 skills/product-design-harness/resources/docs/ADOPTION.md create mode 100644 skills/product-design-harness/resources/docs/ANTI-PATTERNS.md create mode 100644 skills/product-design-harness/resources/docs/CLAIMS.md create mode 100644 skills/product-design-harness/resources/docs/CODING-HARNESS-COMPARISON.md create mode 100644 skills/product-design-harness/resources/docs/CONTRACTS.md create mode 100644 skills/product-design-harness/resources/docs/COUNCIL.md create mode 100644 skills/product-design-harness/resources/docs/DECISION-RULES.md create mode 100644 skills/product-design-harness/resources/docs/GLOSSARY.md create mode 100644 skills/product-design-harness/resources/docs/HARNESS.md create mode 100644 skills/product-design-harness/resources/docs/LEARNING-LOOP.md create mode 100644 skills/product-design-harness/resources/docs/LIVE-CODING.md create mode 100644 skills/product-design-harness/resources/docs/MULTI-AGENT-ALIGNMENT.md create mode 100644 skills/product-design-harness/resources/docs/OPERATING-PROTOCOL.md create mode 100644 skills/product-design-harness/resources/docs/ORCHESTRATION.md create mode 100644 skills/product-design-harness/resources/docs/PRINCIPLES.md create mode 100644 skills/product-design-harness/resources/docs/README.md create mode 100644 skills/product-design-harness/resources/docs/UNCERTAINTY.md create mode 100644 skills/product-design-harness/resources/docs/UX3.md create mode 100644 skills/product-design-harness/resources/docs/rfcs/0001-override-protocol.md create mode 100644 skills/product-design-harness/resources/examples/README.md create mode 100644 skills/product-design-harness/resources/examples/evidence-response.json create mode 100644 skills/product-design-harness/resources/examples/feature-gate-review.md create mode 100644 skills/product-design-harness/resources/examples/human-decision.json create mode 100644 skills/product-design-harness/resources/examples/live-coding-context-pack.json create mode 100644 skills/product-design-harness/resources/examples/live-coding-product-brief.json create mode 100644 skills/product-design-harness/resources/examples/live-coding-review.json create mode 100644 skills/product-design-harness/resources/examples/quick-context-pack.json create mode 100644 skills/product-design-harness/resources/examples/quick-gate-review.json create mode 100644 skills/product-design-harness/resources/examples/quick-gate-review.md create mode 100644 skills/product-design-harness/resources/examples/red-team-review.json create mode 100644 skills/product-design-harness/resources/examples/standard-gate-review.json create mode 100644 skills/product-design-harness/resources/examples/stop-reframe-review.json create mode 100644 skills/product-design-harness/resources/examples/stop-reframe-review.md create mode 100644 skills/product-design-harness/resources/examples/ux3-council-input.json create mode 100644 skills/product-design-harness/resources/examples/ux3-council-review.json create mode 100644 skills/product-design-harness/resources/examples/ux3-council-review.md create mode 100644 skills/product-design-harness/resources/examples/verdict-override.json create mode 100644 skills/product-design-harness/resources/examples/verdict-override.md create mode 100644 skills/product-design-harness/resources/knowledge/ontology.json create mode 100644 skills/product-design-harness/resources/knowledge/rules.json create mode 100644 skills/product-design-harness/resources/knowledge/source-chapters.json create mode 100644 skills/product-design-harness/resources/prompts/README.md create mode 100644 skills/product-design-harness/resources/prompts/claim-analysis.md create mode 100644 skills/product-design-harness/resources/prompts/gate-review.md create mode 100644 skills/product-design-harness/resources/prompts/intake.md create mode 100644 skills/product-design-harness/resources/prompts/mode-selector.md create mode 100644 skills/product-design-harness/resources/prompts/red-team.md create mode 100644 skills/product-design-harness/resources/prompts/start-review.md create mode 100644 skills/product-design-harness/resources/prompts/ux3-council.md create mode 100644 skills/product-design-harness/resources/requirements-dev.txt create mode 100644 skills/product-design-harness/resources/schemas/README.md create mode 100644 skills/product-design-harness/resources/schemas/actor-boundary.schema.json create mode 100644 skills/product-design-harness/resources/schemas/claim-analysis.schema.json create mode 100644 skills/product-design-harness/resources/schemas/claim.schema.json create mode 100644 skills/product-design-harness/resources/schemas/context-pack.schema.json create mode 100644 skills/product-design-harness/resources/schemas/council-input.schema.json create mode 100644 skills/product-design-harness/resources/schemas/decision-rule.schema.json create mode 100644 skills/product-design-harness/resources/schemas/evidence-request.schema.json create mode 100644 skills/product-design-harness/resources/schemas/evidence-response.schema.json create mode 100644 skills/product-design-harness/resources/schemas/evidence.schema.json create mode 100644 skills/product-design-harness/resources/schemas/human-decision.schema.json create mode 100644 skills/product-design-harness/resources/schemas/ontology.schema.json create mode 100644 skills/product-design-harness/resources/schemas/product-brief.schema.json create mode 100644 skills/product-design-harness/resources/schemas/red-team-review.schema.json create mode 100644 skills/product-design-harness/resources/schemas/review-result.schema.json create mode 100644 skills/product-design-harness/resources/schemas/reviewer-verdict.schema.json create mode 100644 skills/product-design-harness/resources/schemas/session-config.schema.json create mode 100644 skills/product-design-harness/resources/schemas/uncertainty-review.schema.json create mode 100644 skills/product-design-harness/resources/schemas/verdict-override.schema.json create mode 100644 skills/product-design-harness/resources/scripts/check_override.py create mode 100644 skills/product-design-harness/resources/scripts/check_review.py create mode 100644 skills/product-design-harness/resources/scripts/jev_gate.py create mode 100644 skills/product-design-harness/resources/templates/README.md create mode 100644 skills/product-design-harness/resources/templates/context-pack.md create mode 100644 skills/product-design-harness/resources/templates/decision-log.md create mode 100644 skills/product-design-harness/resources/templates/gate-review.md create mode 100644 skills/product-design-harness/resources/templates/override-ledger.md create mode 100644 skills/product-design-harness/resources/templates/product-brief.md create mode 100644 skills/product-design-harness/resources/templates/ux3-council-review.md diff --git a/docs/README.skills.md b/docs/README.skills.md index cf30a9fd7..f3ca84832 100644 --- a/docs/README.skills.md +++ b/docs/README.skills.md @@ -345,6 +345,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to | [pr-screenshots](../skills/pr-screenshots/SKILL.md)
`gh skills install github/awesome-copilot pr-screenshots` | Embed before/after screenshots and annotated images in pull request descriptions. Covers PR description patterns, image upload for Azure DevOps and GitHub, and sizing best practices. | None | | [prd](../skills/prd/SKILL.md)
`gh skills install github/awesome-copilot prd` | Generate high-quality Product Requirements Documents (PRDs) for software systems and AI-powered features. Includes executive summaries, user stories, technical specifications, and risk analysis. | None | | [premium-frontend-ui](../skills/premium-frontend-ui/SKILL.md)
`gh skills install github/awesome-copilot premium-frontend-ui` | A comprehensive guide for GitHub Copilot to craft immersive, high-performance web experiences with advanced motion, typography, and architectural craftsmanship. | None | +| [product-design-harness](../skills/product-design-harness/SKILL.md)
`gh skills install github/awesome-copilot product-design-harness` | Use when a product direction, feature, workflow, experiment, launch, feedback signal, automation, or scale decision needs judgment before execution or the next iteration. | `LICENSE`
`resources/agents/README.md`
`resources/agents/business-flow-reviewer.md`
`resources/agents/claim-analyst.md`
`resources/agents/council-facilitator.md`
`resources/agents/evidence-flow-reviewer.md`
`resources/agents/registry.json`
`resources/agents/uncertainty-reviewer.md`
`resources/agents/user-flow-reviewer.md`
`resources/assets/decision-gate.svg`
`resources/assets/harness-sequence.svg`
`resources/docs/ADOPTION.md`
`resources/docs/ANTI-PATTERNS.md`
`resources/docs/CLAIMS.md`
`resources/docs/CODING-HARNESS-COMPARISON.md`
`resources/docs/CONTRACTS.md`
`resources/docs/COUNCIL.md`
`resources/docs/DECISION-RULES.md`
`resources/docs/GLOSSARY.md`
`resources/docs/HARNESS.md`
`resources/docs/LEARNING-LOOP.md`
`resources/docs/LIVE-CODING.md`
`resources/docs/MULTI-AGENT-ALIGNMENT.md`
`resources/docs/OPERATING-PROTOCOL.md`
`resources/docs/ORCHESTRATION.md`
`resources/docs/PRINCIPLES.md`
`resources/docs/README.md`
`resources/docs/UNCERTAINTY.md`
`resources/docs/UX3.md`
`resources/docs/rfcs/0001-override-protocol.md`
`resources/examples/README.md`
`resources/examples/evidence-response.json`
`resources/examples/feature-gate-review.md`
`resources/examples/human-decision.json`
`resources/examples/live-coding-context-pack.json`
`resources/examples/live-coding-product-brief.json`
`resources/examples/live-coding-review.json`
`resources/examples/quick-context-pack.json`
`resources/examples/quick-gate-review.json`
`resources/examples/quick-gate-review.md`
`resources/examples/red-team-review.json`
`resources/examples/standard-gate-review.json`
`resources/examples/stop-reframe-review.json`
`resources/examples/stop-reframe-review.md`
`resources/examples/ux3-council-input.json`
`resources/examples/ux3-council-review.json`
`resources/examples/ux3-council-review.md`
`resources/examples/verdict-override.json`
`resources/examples/verdict-override.md`
`resources/knowledge/ontology.json`
`resources/knowledge/rules.json`
`resources/knowledge/source-chapters.json`
`resources/prompts/README.md`
`resources/prompts/claim-analysis.md`
`resources/prompts/gate-review.md`
`resources/prompts/intake.md`
`resources/prompts/mode-selector.md`
`resources/prompts/red-team.md`
`resources/prompts/start-review.md`
`resources/prompts/ux3-council.md`
`resources/requirements-dev.txt`
`resources/schemas/README.md`
`resources/schemas/actor-boundary.schema.json`
`resources/schemas/claim-analysis.schema.json`
`resources/schemas/claim.schema.json`
`resources/schemas/context-pack.schema.json`
`resources/schemas/council-input.schema.json`
`resources/schemas/decision-rule.schema.json`
`resources/schemas/evidence-request.schema.json`
`resources/schemas/evidence-response.schema.json`
`resources/schemas/evidence.schema.json`
`resources/schemas/human-decision.schema.json`
`resources/schemas/ontology.schema.json`
`resources/schemas/product-brief.schema.json`
`resources/schemas/red-team-review.schema.json`
`resources/schemas/review-result.schema.json`
`resources/schemas/reviewer-verdict.schema.json`
`resources/schemas/session-config.schema.json`
`resources/schemas/uncertainty-review.schema.json`
`resources/schemas/verdict-override.schema.json`
`resources/scripts/check_override.py`
`resources/scripts/check_review.py`
`resources/scripts/jev_gate.py`
`resources/templates/README.md`
`resources/templates/context-pack.md`
`resources/templates/decision-log.md`
`resources/templates/gate-review.md`
`resources/templates/override-ledger.md`
`resources/templates/product-brief.md`
`resources/templates/ux3-council-review.md` | | [project-workflow-analysis-blueprint-generator](../skills/project-workflow-analysis-blueprint-generator/SKILL.md)
`gh skills install github/awesome-copilot project-workflow-analysis-blueprint-generator` | Comprehensive technology-agnostic prompt generator for documenting end-to-end application workflows. Automatically detects project architecture patterns, technology stacks, and data flow patterns to generate detailed implementation blueprints covering entry points, service layers, data access, error handling, and testing approaches across multiple technologies including .NET, Java/Spring, React, and microservices architectures. | None | | [prompt-optimizer](../skills/prompt-optimizer/SKILL.md)
`gh skills install github/awesome-copilot prompt-optimizer` | Turn any rough prompt, half-formed idea, or task description into a finished, ready-to-send prompt optimized for any LLM model inside a chat interface — NOT the API. Use this skill whenever the user wants to write, rewrite, optimize, improve, sharpen, or polish a prompt for chat. Trigger phrases include "rewrite this prompt", "make this a better prompt", "optimize this prompt", "turn this into a prompt", "help me prompt this", "draft a prompt that...", "I want to ask...", or whenever the user pastes a draft prompt and asks for improvements. Also trigger when the user describes a task they plan to send to an LLM model and clearly wants a reusable, well-structured prompt rather than a direct answer. The output is always a single, copy-pasteable prompt in a code block that the user sends as-is — never a template with placeholders. | None | | [protobuf-grpc-api-review](../skills/protobuf-grpc-api-review/SKILL.md)
`gh skills install github/awesome-copilot protobuf-grpc-api-review` | Review Protocol Buffer (.proto) and gRPC API changes for wire and JSON compatibility, safe schema evolution, rollout hazards, and RPC contract quality. Use when reviewing proto diffs, adding or changing messages and services, planning migrations, or diagnosing cross-version failures. | `references/grpc-contract-review.md`
`references/protobuf-compatibility.md` | diff --git a/skills/product-design-harness/LICENSE b/skills/product-design-harness/LICENSE new file mode 100644 index 000000000..43eff4d76 --- /dev/null +++ b/skills/product-design-harness/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Product Design Harness contributors + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/skills/product-design-harness/SKILL.md b/skills/product-design-harness/SKILL.md new file mode 100644 index 000000000..825bd5401 --- /dev/null +++ b/skills/product-design-harness/SKILL.md @@ -0,0 +1,126 @@ +--- +name: product-design-harness +description: 'Use when a product direction, feature, workflow, experiment, launch, feedback signal, automation, or scale decision needs judgment before execution or the next iteration.' +license: MIT +--- + +# Product Design Harness + +Decide whether a product direction should continue, be verified, or be +reframed anywhere in the product loop. + +Execution includes design, implementation, prototype, launch, growth, +automation, or investment. + +## Start + +Load in this order: + +1. `resources/schemas/session-config.schema.json`: set `working_language`; keep + `canonical_identifiers` in English. +2. `resources/knowledge/ontology.json`: use the canonical UX3 knowledge kernel and its + approved Flow definitions. +3. `resources/knowledge/rules.json`: load required rules plus only triggered conditional + rules. +4. `resources/prompts/start-review.md`. + +Then fill `resources/templates/product-brief.md`, select the smallest responsible mode, +and return `resources/schemas/review-result.schema.json`. + +Validate every review result with `resources/scripts/check_review.py`. JSON Schema checks +shape and conditional fields; `check_review.py` is the canonical validator for +the worst-verdict, weakest-flow, and headline-tier semantic checks. + +## Modes + +| Mode | Use when | +|---|---| +| Quick Gate | Small, reversible, low-risk change. | +| Standard Gate | New feature, workflow, or experiment. | +| UX3 Council | High uncertainty, external evidence, meaningful risk, multiple reviewers, or human-owned trade-off. | + +Handoff is not a review mode. When a prior review already returned continue, +reuse its context pack instead of running a new review. + +Reversibility lowers mode, not the review requirement. + +## UX3 + +Review three connected dimensions: + +| Flow | Core question | +|---|---| +| User Flow | Who is the product for, who is affected, what are they trying to accomplish, and what cost or loss of control exists now? | +| Evidence Flow | What signal was observed, where did it come from, what interpretation is being made, what counter-signal weakens it, and what decision impact follows? | +| Business Flow | Who creates value, receives value, pays or decides, bears cost or risk, and can the exchange remain viable and legitimate? | + +Then inspect the intersections: Situated Understanding, Viable Learning, +and Sustainable Value Exchange. + +## UX3 Decision Kernel + +Apply the same reduction sequence to every submitted review: + +1. Validate lane contracts and evidence references with `resources/scripts/check_review.py`. +2. Reduce to the worst verdict and deterministic weakest flow. +3. Gate uncertainty, risk, reversibility, and human-owned calls. +4. Emit one canonical verdict, next action, execution boundary, and stop conditions. + +Do not average lanes. Human-owned calls are recorded through an accountable +decision record; they are not converted into a machine score. + +Before handoff, name product organization, issuer, stakeholder effects, and +accountable owner. Missing issuer or owner blocks implementation. + +## Operating Rules + +- Do not implement during review. +- `verify` branch: verify authorizes only the exact proof_step and never + general coding. +- `continue` branch: continue plus a valid context pack authorizes implementation. +- Every result states `may_do`, `must_not_do`, and `must_ask`. +- List disconfirming evidence before support. +- Do not average reviewer verdicts. +- The weakest flow controls the next action. +- External tools return evidence receipts, not verdicts. +- Evidence tier controls action size; confidence does not upgrade weak proof. +- Council mode requires independent reviews and a challenge round. +- If all independent Council reviews return continue, a valid + resources/schemas/red-team-review.schema.json result must be attached to + the Council input before synthesis. +- Designer taste is a human-owned input, never an evidence score. +- Incoming feedback must be classified before it changes direction or work. +- Human-owned decisions stay human-owned. + +## Triggered Distilled Rules + +Load only rules whose observable trigger applies. These families refine the +three Flow reviews; they do not create new verdicts or allow a strong Flow to +outvote a weak one. + +| Situation | Required rule | +|---|---| +| Mental-model mismatch, hidden capability, or misunderstood consequence | `ux3.rule.mental_model_alignment` | +| Cognitive or recovery burden across human, task, tool, and environment | `ux3.rule.human_factors_load` | +| Research claim, synthetic user, simulation, interview, survey, test, or analytics result | `ux3.rule.research_validity` | +| Value proposition, positioning, buyer, channel, or GTM path before fit is proven | `ux3.rule.value_market_path` | +| Agent plan or tool action that needs visibility, control, handoff, or recovery | `ux3.rule.human_agent_interaction` | +| Retention, personalization, or gamification that changes repeated behavior | `ux3.rule.motivation_ethics` | + +## Outcome + +| Verdict | Required next step | +|---|---| +| continue | Create resources/templates/context-pack.md within the execution boundary. | +| verify | Run one proof step only. | +| stop_reframe | Stop execution and return a better product question. | + +Use triggered rule IDs for detail instead of duplicating every rule in prompts. +Common triggers include ux3.rule.actor_boundary, +ux3.rule.problem_hypothesis, ux3.rule.evidence_separation, +ux3.rule.minimum_validated_proof, ux3.rule.feedback_classification, and +ux3.rule.human_judgment. The distilled trigger table above covers additional +rules that activate only when their specific product condition appears. + +Use resources/docs/HARNESS.md for the handbook, resources/docs/OPERATING-PROTOCOL.md for the six-gate protocol, +resources/docs/CONTRACTS.md for output rules, and resources/examples/ for worked reviews. diff --git a/skills/product-design-harness/resources/agents/README.md b/skills/product-design-harness/resources/agents/README.md new file mode 100644 index 000000000..f3c57264e --- /dev/null +++ b/skills/product-design-harness/resources/agents/README.md @@ -0,0 +1,16 @@ +# Agents + +These files define reviewer roles. + +`registry.json` is the machine-readable role registry. The Markdown files are +the human-readable instructions. + +| File | Role | +|---|---| +| `user-flow-reviewer.md` | Checks actor, problem, affected people, and user reality. | +| `evidence-flow-reviewer.md` | Checks proof, measurement, failure criteria, and traceability. | +| `business-flow-reviewer.md` | Checks value, cost, distribution, retention, and defensibility. | +| `claim-analyst.md` | Breaks product directions into testable claims. | +| `uncertainty-reviewer.md` | Reviews unknowns, confidence, reversibility, and proof bar. | +| `council-facilitator.md` | Combines reviewer outputs into one verdict. | +| `registry.json` | Maps each role to its input and output schema. | diff --git a/skills/product-design-harness/resources/agents/business-flow-reviewer.md b/skills/product-design-harness/resources/agents/business-flow-reviewer.md new file mode 100644 index 000000000..6e33a54a9 --- /dev/null +++ b/skills/product-design-harness/resources/agents/business-flow-reviewer.md @@ -0,0 +1,44 @@ +# Business Flow Reviewer + +## Role + +Protect sustainable value: value exchange, ownership cost, priority, +distribution, retention, defensibility, and trust. + +Do not ask only whether the direction can be built. Ask whether it deserves +ownership. + +Use `knowledge/ontology.json` for the Business Flow definition and stakeholder +roles. Use `knowledge/rules.json` for triggered rule IDs, especially +ux3.rule.actor_boundary, ux3.rule.whole_ownership_cost, +ux3.rule.false_product_market_fit, ux3.rule.depth_accumulation, and +ux3.rule.human_judgment. Answer in `working_language`; keep schema fields, +rule IDs, and Flow identifiers canonical. + +## Checks + +| Check | Continue signal | Stop signal | +|---|---|---| +| Value exchange | User value and product value are explicit and fair. | The direction is only interesting. | +| Ownership cost | Support, trust, maintenance, exceptions, and opportunity cost are bounded. | Only initial build cost is counted. | +| Distribution | A credible route to adoption exists. | No channel or workflow entry exists. | +| Retention | Value survives novelty. | Usage depends on curiosity. | +| Defensibility | Workflow depth, domain knowledge, community, data, or edge cases compound. | It is a generic feature. | + +Approved Business Flow question: who creates value, who receives value, who +pays or decides, who bears cost or risk, and can the exchange remain viable and +legitimate? + +Require product organization, issuer, stakeholder effects, and accountable +owner before handoff. A strong business lane cannot average out missing user or +evidence proof. Reversibility lowers mode, not the review requirement. verify authorizes only the exact proof_step and never general coding. continue plus a valid context pack authorizes implementation. + +## Contract + +Input: `schemas/product-brief.schema.json` + +Output: `schemas/reviewer-verdict.schema.json` with `reviewer: business_flow`. + +Compare against the current workaround and doing nothing. In the challenge +round, question whether User Flow value and Evidence Flow proof can support the +claimed ownership cost. diff --git a/skills/product-design-harness/resources/agents/claim-analyst.md b/skills/product-design-harness/resources/agents/claim-analyst.md new file mode 100644 index 000000000..ed60dd975 --- /dev/null +++ b/skills/product-design-harness/resources/agents/claim-analyst.md @@ -0,0 +1,24 @@ +# Claim Analyst + +## Role + +Break a product direction into testable claims and dependency edges before the +council reviews it. Do not decide whether to build. + +## Method + +1. Split broad statements into user, evidence, business, risk, and taste claims. +2. Give each claim a stable identifier. +3. Add support and counter-signal. +4. Connect depends_on and breaks_if_false. +5. Name a proof step and stop condition. +6. Identify the claim whose failure changes the decision most. + +## Contract + +Input: `schemas/product-brief.schema.json` + +Output: `schemas/claim-analysis.schema.json` + +Use `docs/CLAIMS.md`. A claim without counter-signal, dependency edges, or a +stop condition is incomplete. diff --git a/skills/product-design-harness/resources/agents/council-facilitator.md b/skills/product-design-harness/resources/agents/council-facilitator.md new file mode 100644 index 000000000..47705ba2f --- /dev/null +++ b/skills/product-design-harness/resources/agents/council-facilitator.md @@ -0,0 +1,60 @@ +# Council Facilitator + +## Role + +Turn verified disagreement into one product decision. Do not vote and do not +average. + +## Preflight + +Reject synthesis unless the council input contains: + +- claim analysis with dependency edges +- three independent lane reviews +- three challenge-round reviews +- uncertainty review +- evidence provenance and freshness +- an accountable owner for any human-owned decision +- a valid red_team_review with claim and evidence references when all three + independent lane reviews returned continue + +## Decision Rule + +| Lane state | Combined verdict | +|---|---| +| Any lane `stop_reframe`, for any reason | `stop_reframe` | +| One or more `verify` and no stop | `verify` | +| All three `continue` | `continue` | + +Select the weakest flow deterministically: the lane with the most severe +verdict (`stop_reframe` > `verify` > `continue`); ties break to the lowest +lane `evidence_tier`, then to the fixed priority evidence, user, business. +The weakest flow defines the next action. Human judgment may raise the proof +bar, but it may not erase missing actor clarity, provenance, or safety. + +## Contract + +Input: `schemas/council-input.schema.json` + +Output: `schemas/review-result.schema.json` + +Additional rules: + +- If every lane returned continue, require the structured red-team result + (`schemas/red-team-review.schema.json`) in council_input.red_team_review + before synthesizing. When a finding warrants verify, record verify in the + affected final lane review with the counter-case and missing proof, then + reduce the final lane verdicts using the table above. Preserve the original + independent and challenge-round receipts. Do not change only the combined + verdict while leaving every final lane at continue. +- On stop_reframe, the execution boundary carries no build scope: + may_do lists research and reframing actions only. +- A human override of any verdict must be recorded through + `schemas/verdict-override.schema.json` (checked with + `scripts/check_override.py`) and tracked in + `templates/override-ledger.md`; an unlogged override does not exist. + The review-result itself is never edited - the verdict stays on + record, and the override authorizes execution despite it. + +Only `continue` creates a context pack. `verify` creates one proof step. +`stop_reframe` creates one better product question. diff --git a/skills/product-design-harness/resources/agents/evidence-flow-reviewer.md b/skills/product-design-harness/resources/agents/evidence-flow-reviewer.md new file mode 100644 index 000000000..efa3de4bd --- /dev/null +++ b/skills/product-design-harness/resources/agents/evidence-flow-reviewer.md @@ -0,0 +1,47 @@ +# Evidence Flow Reviewer + +## Role + +Protect decision quality: provenance, signal type, interpretation, freshness, +counter-signal, measurement, and failure criteria. + +Do not decide whether an idea sounds attractive. + +Use `knowledge/ontology.json` for the Evidence Flow definition and evidence +terms. Use `knowledge/rules.json` for triggered rule IDs, especially +ux3.rule.evidence_separation, ux3.rule.disconfirm_first, +ux3.rule.minimum_validated_proof, ux3.rule.feedback_classification, and +ux3.rule.human_judgment. Answer in `working_language`; keep schema fields, +rule IDs, and Flow identifiers canonical. + +## Checks + +| Check | Continue signal | Stop signal | +|---|---|---| +| Provenance | Raw artifact and source identifier are traceable. | The source is a summary with no trace. | +| Signal type | Opinion, quote, behavior, log, transaction, and derived signal remain distinct. | Evidence types are blended. | +| Freshness | Collection and verification dates fit the decision. | Expired evidence is treated as current. | +| Decision impact | Every receipt changes a claim or next action. | Metrics are decorative. | +| Failure criteria | The team knows what stops or reframes work. | No failure condition exists. | + +Approved Evidence Flow question: what signal was observed, where did it come +from, what interpretation is being made, what counter-signal weakens it, and +what decision impact follows? + +Designer taste is a named human-owned input, not an evidence score. Post-build +feedback must be classified before it changes product direction. Reversibility +lowers mode, not the review requirement. verify authorizes only the exact proof_step and never general coding. continue plus a valid context pack authorizes implementation. + +## Contract + +Evidence retrieval uses: + +- `schemas/evidence-request.schema.json` +- `schemas/evidence-response.schema.json` +- `schemas/evidence.schema.json` + +Reviewer output uses `schemas/reviewer-verdict.schema.json` with +`reviewer: evidence_flow`. + +In the challenge round, test whether User Flow and Business Flow conclusions +are stronger than their provenance, tier, or freshness allows. diff --git a/skills/product-design-harness/resources/agents/registry.json b/skills/product-design-harness/resources/agents/registry.json new file mode 100644 index 000000000..32aa29409 --- /dev/null +++ b/skills/product-design-harness/resources/agents/registry.json @@ -0,0 +1,41 @@ +{ + "schema_version": "1.0", + "agents": [ + { + "id": "claim_analyst", + "instructions": "agents/claim-analyst.md", + "input_schema": "schemas/product-brief.schema.json", + "output_schema": "schemas/claim-analysis.schema.json" + }, + { + "id": "user_flow_reviewer", + "instructions": "agents/user-flow-reviewer.md", + "input_schema": "schemas/product-brief.schema.json", + "output_schema": "schemas/reviewer-verdict.schema.json" + }, + { + "id": "evidence_flow_reviewer", + "instructions": "agents/evidence-flow-reviewer.md", + "input_schema": "schemas/product-brief.schema.json", + "output_schema": "schemas/reviewer-verdict.schema.json" + }, + { + "id": "business_flow_reviewer", + "instructions": "agents/business-flow-reviewer.md", + "input_schema": "schemas/product-brief.schema.json", + "output_schema": "schemas/reviewer-verdict.schema.json" + }, + { + "id": "uncertainty_reviewer", + "instructions": "agents/uncertainty-reviewer.md", + "input_schema": "schemas/council-input.schema.json", + "output_schema": "schemas/uncertainty-review.schema.json" + }, + { + "id": "council_facilitator", + "instructions": "agents/council-facilitator.md", + "input_schema": "schemas/council-input.schema.json", + "output_schema": "schemas/review-result.schema.json" + } + ] +} diff --git a/skills/product-design-harness/resources/agents/uncertainty-reviewer.md b/skills/product-design-harness/resources/agents/uncertainty-reviewer.md new file mode 100644 index 000000000..8a4b289f3 --- /dev/null +++ b/skills/product-design-harness/resources/agents/uncertainty-reviewer.md @@ -0,0 +1,28 @@ +# Uncertainty Reviewer + +## Role + +Prevent false confidence before execution expands. + +Separate evidence tier from confidence. Evidence tier limits action; confidence +describes trust in the interpretation. + +## Checks + +| Check | Required question | +|---|---| +| Evidence tier | What is the strongest valid tier after freshness checks? | +| Risk class | Is the impact R1, R2, R3, or R4? | +| Reversibility | Can the next action be rolled back without hidden accumulation? | +| False confidence | What looks proven but is not? | +| Proof bar | What must be true before the next stage? | +| Human decision | What cannot be delegated without losing accountability? | + +## Contract + +Input: `schemas/council-input.schema.json` + +Output: `schemas/uncertainty-review.schema.json` + +Use the decision matrix in `docs/UNCERTAINTY.md`. Expired evidence is +downgraded until re-verified. diff --git a/skills/product-design-harness/resources/agents/user-flow-reviewer.md b/skills/product-design-harness/resources/agents/user-flow-reviewer.md new file mode 100644 index 000000000..a53516315 --- /dev/null +++ b/skills/product-design-harness/resources/agents/user-flow-reviewer.md @@ -0,0 +1,47 @@ +# User Flow Reviewer + +## Role + +Protect user reality: actor, situation, problem, path, consequence, affected +people, exclusion, mental model, and recovery. + +Do not review interface polish. Do not propose a solution before the problem is +testable. + +Use `knowledge/ontology.json` for the User Flow definition and actor roles. +Use `knowledge/rules.json` for triggered rule IDs, especially +ux3.rule.actor_boundary, ux3.rule.problem_hypothesis, and +ux3.rule.behavior_subjective_separation. Answer in `working_language`; keep +schema fields, rule IDs, and Flow identifiers canonical. + +## Checks + +| Check | Continue signal | Stop signal | +|---|---|---| +| Actor boundary | Operator, beneficiary, affected people, and excluded groups are named. | The brief says only "users." | +| Problem | Situation, frequency, consequence, workaround, and disconfirmation are clear. | The problem is a requested feature. | +| Situated Understanding | Stated opinion, quote, feeling, behavior, and trace remain distinct. | All signals are treated as equal proof. | +| Mental model | People can predict action, consequence, and recovery. | Important power is hidden. | +| Exclusion | Access, language, device, ability, policy, and data constraints are named. | No excluded group is considered. | + +Approved User Flow question: who is the product for, who is affected, what are +they trying to accomplish, and what cost, friction, risk, or loss of control +exists now? + +Reversibility lowers mode, not the review requirement. + +- Boundary: verify authorizes only the exact proof_step and never general coding. +- Boundary: continue plus a valid context pack authorizes implementation. + +If the user boundary is incomplete, put the missing actor facts in `must_ask`; +do not authorize implementation. + +## Contract + +Input: `schemas/product-brief.schema.json` + +Output: `schemas/reviewer-verdict.schema.json` with `reviewer: user_flow`. + +List disconfirming evidence before support. In the challenge round, question one +material premise from Evidence Flow or Business Flow and record whether the +position changed. diff --git a/skills/product-design-harness/resources/assets/decision-gate.svg b/skills/product-design-harness/resources/assets/decision-gate.svg new file mode 100644 index 000000000..2c2ca8885 --- /dev/null +++ b/skills/product-design-harness/resources/assets/decision-gate.svg @@ -0,0 +1,46 @@ + + UX3 decision gate + A UX3 decision gate with Continue, Verify, and Stop/Reframe outcomes. + + Gate Logic + A review is useful only when it changes the next action. + PLATE 04 + + + Is the next step earned? + Review user, evidence, and business together. + + + + + + + + + + Continue + Scope is clear. + Risks are bounded. + Evidence is enough for + the next step. + + + + + Verify + Direction is plausible. + Proof is still thin. + Run the smallest test + before building more. + + + + + Stop / Reframe + The problem, user, or + value is unstable. + Change the frame before + execution begins. + + + diff --git a/skills/product-design-harness/resources/assets/harness-sequence.svg b/skills/product-design-harness/resources/assets/harness-sequence.svg new file mode 100644 index 000000000..2c2d2ca61 --- /dev/null +++ b/skills/product-design-harness/resources/assets/harness-sequence.svg @@ -0,0 +1,45 @@ + + Harness operating sequence + The sequence from product framing to UX3 review, context pack, execution harness, verified change, and learning. + + Operating Sequence + Judgment comes before execution; learning returns to the next review. + PLATE 03 + + + + + + 1 + Framing + goal, user, constraint + + + + 2 + UX3 Review + user, evidence, business + + + + 3 + Context Pack + scope, non-goals, criteria + + + + 4 + Execution Harness + build, test, release + + + + 5 + Verified Change + result, evidence, drift + + + + + Evidence from the change updates the next product judgment. + diff --git a/skills/product-design-harness/resources/docs/ADOPTION.md b/skills/product-design-harness/resources/docs/ADOPTION.md new file mode 100644 index 000000000..2d6d2e2f0 --- /dev/null +++ b/skills/product-design-harness/resources/docs/ADOPTION.md @@ -0,0 +1,114 @@ +# Adoption Guide + +How an agent team installs UX3 Product Design Harness, and what "installed" +means for a repository. + +The goal is not more process. The goal is fewer polished artifacts built on +weak assumptions. + +## 1. Install + +| Step | Action | +|---|---| +| 1 | Clone or vendor this repository. It is prompts, schemas, and agent definitions; there is no runtime service to deploy. | +| 2 | Confirm the copy is intact: `python3 -m venv .venv`, then `.venv/bin/python -m pip install -r requirements-dev.txt`, `.venv/bin/python -m unittest discover -s tests`, `.venv/bin/python scripts/validate.py`, and `.venv/bin/python scripts/check_review.py examples/quick-gate-review.json`. | +| 3 | Install with `npx skills add cis2042/ux3-product-design-harness -g -y`, or copy `skills/product-design-harness/SKILL.md` together with its `resources/` directory into the agent configuration. | +| 4 | Wire `prompts/start-review.md` from a full clone, or `resources/prompts/start-review.md` from an installed skill, as the entry prompt for every product review. It selects Quick Gate, Standard Gate, or UX3 Council. | +| 5 | Register the reviewer agents from `agents/registry.json` in a full clone, or `resources/agents/registry.json` from an installed skill. Each entry names its instruction file, input schema, and output schema, so any agent runtime can load them. | +| 6 | Validate every review output with `scripts/check_review.py` in a full clone, or `resources/scripts/check_review.py` from an installed skill, and reject anything invalid. JSON Schema checks shape and conditional branches; `check_review.py` also enforces worst-verdict, weakest-flow, and headline-tier semantics. | + +## 2. Continuous Validation In CI + +- Add a CI job that validates stored review results with `scripts/check_review.py` + before anyone acts on them. +- Reuse this repository's workflow as a template: + `.github/workflows/validate.yml` runs the test suite plus + `scripts/validate.py` on every push and pull request. +- Use the golden examples as fixtures: `examples/quick-gate-review.json`, + `examples/standard-gate-review.json`, `examples/ux3-council-review.json`. +- Record human decisions with `schemas/human-decision.schema.json` so every + review links to an accountable decision record and back, with reversal + conditions. + +## 3. First Integration: Standard Gate On One Feature + +Do not roll the harness out everywhere at once. Run one real feature through +Standard Gate: + +1. Pick one upcoming feature. +2. Fill `templates/product-brief.md`. +3. Run `prompts/gate-review.md` in Standard Gate mode. +4. Validate the result with `scripts/check_review.py`. +5. Record the human decision in `templates/decision-log.md` (machine form: + `schemas/human-decision.schema.json`). +6. If the verdict is `continue`, create `templates/context-pack.md` and hand + it to execution. + +Then widen: Quick Gate before small reversible changes, UX3 Council for +high-uncertainty or expensive decisions. + +## 4. Live Coding Adoption + +Live coding teams should use `docs/LIVE-CODING.md` as the operating guide. +The shortest safe path is: + +| Step | Action | +|---|---| +| 1 | Select the working language and keep identifiers in English. | +| 2 | Convert the request into a product brief before coding. | +| 3 | Run the smallest responsible review mode. | +| 4 | Validate the review with `scripts/check_review.py`. | +| 5 | If the verdict is `continue`, create and validate a context pack. | +| 6 | Implement only inside the context-pack execution boundary. | +| 7 | If scope, data, risk, or affected people change, pause and run review again. | +| 8 | Classify post-build feedback as evidence for the next iteration. | + +Use the golden chain as the first fixture: +`examples/live-coding-product-brief.json`, +`examples/live-coding-review.json`, and +`examples/live-coding-context-pack.json`. + +## 5. What "Installed" Means + +A repository has installed the harness when all of the following are true: + +| Check | Evidence | +|---|---| +| Entry prompt wired | Agent configuration references `resources/prompts/start-review.md`, directly or via the installed skill. | +| Outputs validated | Every review result is validated with `scripts/check_review.py` before it is acted on. | +| CI rejects invalid results | A CI job fails on invalid review results, including semantic weakest-flow and headline-tier mismatches. | +| Decisions traceable | Human decisions are recorded against `schemas/human-decision.schema.json` with the review id, an accountable owner, and reversal conditions. | +| Context packs gated | Context packs are created only after a `continue` verdict. | +| Live coding bounded | Coding begins only from a validated `schemas/context-pack.schema.json` artifact. | + +## 6. Team Ritual + +| Moment | Harness action | +|---|---| +| Before writing requirements | Fill product brief. | +| Before prototype or build | Run gate review. | +| Before launch | Run uncertainty review. | +| After learning | Update decision log and evidence ledger. | +| Before scaling | Run UX3 Council. | + +## 7. Common Anti-Patterns + +| Anti-pattern | Correction | +|---|---| +| Building because it is easy. | Run Business Flow and Evidence Flow. | +| Treating a quote as proof. | Separate quote, behavior, log, and counter-signal. | +| Averaging reviewer verdicts. | Let the weakest flow control the next step. | +| Skipping human judgment. | Route taste, risk, strategy, ethics, and meaning to humans. | +| Creating broad context packs. | Narrow scope and add stop conditions. | +| Treating live-coding prompts as approval. | Require a valid review and context pack before implementation. | + +## 8. For Product Designers And PMs + +You adopt this harness by instructing your agent, not by learning the +contracts. Paste the repository URL to your agent and ask it to review a +product decision; the agent installs the harness, runs the review, and +returns one of three verdicts: `continue`, `verify`, or `stop_reframe`. +Your job is to supply the decision, the evidence you actually have, and +the human judgment calls the agent routes back to you. You never run the +scripts, write JSON, or read schemas by hand - if an integration step on +this page looks technical, it is your agent's job, not yours. diff --git a/skills/product-design-harness/resources/docs/ANTI-PATTERNS.md b/skills/product-design-harness/resources/docs/ANTI-PATTERNS.md new file mode 100644 index 000000000..f9cd3a422 --- /dev/null +++ b/skills/product-design-harness/resources/docs/ANTI-PATTERNS.md @@ -0,0 +1,41 @@ +# Anti-Patterns And Anti-Gaming + +A structured review can still become a rubber stamp. The harness therefore +requires decision receipts, not checklist completion. + +## Common Failure Modes + +| Anti-pattern | Detection signal | Required correction | +|---|---|---| +| Rubber-stamp review | Every lane says continue and no counter-evidence appears. | Run the challenge round. | +| Evidence inflation | Quotes, opinions, logs, and payments are treated as equal proof. | Assign evidence tier and signal type. | +| Consensus theater | Reviewers repeat the same argument in different words. | Require objection_to and counter_evidence. | +| False precision | Confidence labels are averaged or treated as scores. | Use evidence tiers and the decision matrix. | +| Checklist substitution | All fields are filled but no decision changes. | State decision impact for every evidence receipt. | +| Context-pack leakage | A verify result becomes a broad build brief. | Allow only the proof step. | +| Tool authority | A connector or search result gives the verdict. | External tools return evidence receipts only. | +| Taste avoidance | Brand, dignity, or meaning is hidden inside a score. | Route to Human Judgment Gate. | +| Stale proof | Old evidence is reused after context changes. | Check freshness and re-verify expired sources. | + +## Continue Receipt + +A continue verdict is invalid unless it contains: + +- one disconfirming signal per lane +- one stop condition per lane +- evidence provenance and freshness +- a completed challenge round for council mode +- one bounded execution scope +- a named human owner when taste, risk, strategy, ethics, or meaning is involved + +## Review The Review + +Before final synthesis, ask: + +| Question | Failure it exposes | +|---|---| +| What answer would this format make easy to fake? | Checklist compliance. | +| Which claim changed because of evidence? | Decorative research. | +| Which reviewer challenged another reviewer? | Parallel summaries. | +| What would make us reverse this decision? | Irreversible commitment. | +| Who is accountable for the non-mechanical judgment? | Hidden responsibility. | diff --git a/skills/product-design-harness/resources/docs/CLAIMS.md b/skills/product-design-harness/resources/docs/CLAIMS.md new file mode 100644 index 000000000..5ed8e2027 --- /dev/null +++ b/skills/product-design-harness/resources/docs/CLAIMS.md @@ -0,0 +1,59 @@ +# Claim Decomposition + +A product direction is a bundle of claims. Review the claims before reviewing +the solution. + +## Claim Types + +| Type | Required question | +|---|---| +| User | What must be true about the actor, situation, problem, or consequence? | +| Evidence | What signal must be trustworthy for the decision to hold? | +| Business | What value, cost, retention, or distribution logic must be true? | +| Risk | Who can be harmed, excluded, misled, or made accountable? | +| Taste | What judgment about coherence, restraint, trust, or meaning is implied? | + +## Decomposition Method + +1. Rewrite the direction as one observable outcome. +2. Split every hidden "and" into a separate claim. +3. Give each claim an identifier. +4. Add current support and a counter-signal. +5. Link depends_on and breaks_if_false edges. +6. Name the smallest proof step and stop condition. +7. Mark the claim that can collapse the most downstream claims. + +Use schemas/claim.schema.json for each claim. + +## Claim Status + +- Every claim carries a status: assumption or verified. +- A claim stays an assumption until evidence receipts support it. +- A verified claim must list at least one evidence receipt id in evidence_ids. +- breaks_if_false must name at least one dependent decision or claim. + +## Example + +Broad statement: + +> An autonomous assistant will save time and improve retention. + +Decomposed: + +| ID | Claim | Depends on | Breaks if false | +|---|---|---|---| +| U1 | Operators repeatedly perform a costly workflow. | None | E1, B1 | +| E1 | Draft assistance reduces cycle time without increasing corrections. | U1 | B1 | +| R1 | Customer-facing mistakes can be detected and reversed. | E1 | B1 | +| B1 | Time saved exceeds review, support, and recovery cost. | U1, E1, R1 | Direction | + +The riskiest claim is not automatically the least supported claim. It is the +claim whose failure produces the largest decision change. + +## Claim Review Rules + +- A claim without a counter-signal is advocacy, not analysis. +- A claim without a stop condition cannot control execution. +- A derived claim cannot have stronger evidence than its weakest dependency. +- External retrieval may support a claim but cannot decide its verdict. +- Taste claims require a named human owner when they affect the final verdict. diff --git a/skills/product-design-harness/resources/docs/CODING-HARNESS-COMPARISON.md b/skills/product-design-harness/resources/docs/CODING-HARNESS-COMPARISON.md new file mode 100644 index 000000000..3842cb617 --- /dev/null +++ b/skills/product-design-harness/resources/docs/CODING-HARNESS-COMPARISON.md @@ -0,0 +1,91 @@ +# Product Design Harness vs Coding Harness + +![Product Design Harness vs Coding Harness](../assets/product-vs-coding-harness.svg) + +## Core Difference + +| Question | Harness | +|---|---| +| Should we build this? | Product Design Harness | +| Did we build this correctly? | Coding Harness | + +Both are needed. + +Product Design Harness should run first. + +## Comparison + +| Dimension | Product Design Harness | Coding Harness | +|---|---|---| +| Main concern | Direction quality. | Execution quality. | +| Primary failure | Wrong product. | Broken implementation. | +| Inputs | Brief, user signal, evidence, constraints, strategy. | Issue, spec, codebase, tests, tools. | +| Outputs | Verdict, gate review, context pack, stop conditions. | Diff, tests, logs, verified change. | +| Review lens | User, evidence, business, taste. | Correctness, security, maintainability, performance. | +| Human role | Judge trade-offs and risk. | Review changes and release readiness. | +| Stop signal | Problem, evidence, risk, or value fails. | Tests, linters, policies, runtime checks fail. | + +## Sequence + +![Harness sequence](../assets/harness-sequence.svg) + +1. Product idea +2. Product Design Harness +3. Context pack +4. Coding Harness +5. Implementation +6. Measurement +7. Decision update + +Skipping Product Design Harness causes teams to build the wrong work efficiently. + +Skipping Coding Harness causes teams to build the right work unreliably. + +## Where They Meet + +The handoff between the two harnesses is the context pack. + +The context pack should include: + +- goal +- stage +- scope +- non-goals +- assumptions +- user rules +- evidence rules +- business rules +- acceptance criteria +- stop conditions + +The coding harness should not invent these. + +If they are missing, execution should stop and ask for product judgment. + +## Anti-Patterns + +| Anti-pattern | Correction | +|---|---| +| "The prototype works, so the idea is valid." | Working output is not market proof. | +| "The tests pass, so the product is good." | Tests verify implementation, not value. | +| "The user asked for it, so build it." | Convert requests into testable problems. | +| "It is easy to ship, so ship it." | Easy features still have ownership cost. | +| "We will measure later." | Define evidence before execution. | + +## Good Handoff Example + +| Field | Example | +|---|---| +| Goal | Reduce failed setup for first-time account admins. | +| Scope | Prototype one guided setup path. | +| Non-goals | No billing, permissions redesign, or analytics dashboard. | +| User rule | Admin must understand the next action without reading docs. | +| Evidence rule | Measure setup completion and rescue-click rate. | +| Business rule | Do not add support-heavy customization. | +| Stop condition | Stop if prototype requires changing core account model. | + +## Rule + +Product Design Harness decides what deserves execution. + +Coding Harness verifies execution. diff --git a/skills/product-design-harness/resources/docs/CONTRACTS.md b/skills/product-design-harness/resources/docs/CONTRACTS.md new file mode 100644 index 000000000..2c225290b --- /dev/null +++ b/skills/product-design-harness/resources/docs/CONTRACTS.md @@ -0,0 +1,94 @@ +# Review Contracts + +JSON Schema defines the artifact shape and conditional branches. Prose explains +it but does not redefine it. `scripts/check_review.py` is the required +canonical validator for complete review results because weakest-flow and +headline-tier selection are semantic checks. + +The canonical final output is schemas/review-result.schema.json. Quick Gate, +Standard Gate, and UX3 Council all return this shape. + +## Canonical Final Result + +| Machine field | Human meaning | +|---|---| +| schema_version | Contract version. | +| review_id | Stable identifier for traceability. | +| product_direction | Direction under review. | +| mode | quick_gate, standard_gate, or ux3_council. | +| stage | idea, prototype, launch, or scale. | +| actor_boundary | Target population, operator, beneficiary, machine actor, affected people, and excluded groups. actor_boundary.target_population is the single target population source. | +| combined_verdict | continue, verify, or stop_reframe. | +| weakest_flow | user, evidence, or business. | +| strongest_signal | Best current support. | +| riskiest_claim | Claim most likely to break the direction. | +| main_uncertainty | Unknown that matters most. | +| confidence_level | Human-readable confidence judgment. | +| evidence_tier | Operational proof level from t0 to t4. | +| main_trade_off | What is sacrificed to protect what matters. | +| human_owned_decision | Taste, risk, strategy, ethics, meaning, or none. | +| human_decision_record_id | Link to the accountable decision record, or null. | +| evidence_receipt_ids | Evidence receipts used by the final decision. | +| reviews | User, Evidence, and Business lane verdicts. | +| next_smallest_action | One action only. | +| execution_boundary | What may and must not be done. | +| stop_conditions | Conditions that block or downgrade work. | +| context_pack_required | True only for continue. | + +Council mode also requires council_record with independent review identifiers, +three challenge receipts, and unresolved conflicts. + +A context pack must copy execution_boundary.may_do into scope exactly. Its +scope is an approved action list, not another opportunity to propose work. +Check both artifacts together with scripts/check_review.py and --context-pack. + +## Outcome Branches + +| Verdict | Required output | Execution | +|---|---|---| +| continue | context_pack_required is true. | Create a context pack within the stated boundary. | +| verify | proof_step is required. | Run only that proof step. | +| stop_reframe | reframed_question is required. | Do not create execution work. | + +## Weakest Flow Rule + +The weakest flow controls the next action, not every future decision. + +| Lane state | Combined verdict | +|---|---| +| Any lane is stop_reframe, for any reason. | stop_reframe | +| No lane stops and at least one lane is verify. | verify | +| All three lanes are continue. | continue | + +The weakest flow is the lane with the most severe verdict +(stop_reframe > verify > continue); ties break to the lowest lane +evidence_tier, then to the fixed priority evidence, user, business. + +The headline evidence_tier equals the lowest lane evidence_tier. Use +`scripts/check_review.py` to validate any review-result against both the JSON +Schema shape and these semantic rules. + +Human-owned decisions (taste, risk, strategy, ethics, meaning) are recorded +through schemas/human-decision.schema.json. Overriding a `verify` or +`stop_reframe` verdict to execute anyway is a different act with its own +contract: schemas/verdict-override.schema.json, checked by +`scripts/check_override.py` against the review it overrides. An override +never modifies the review-result - the verdict stays on record. It must name +one accountable owner, restate the weakest flow, grant an explicit scope +that cannot repeat the review's must_not_do, and carry an expiry and +tripwires. Active overrides are tracked in templates/override-ledger.md; an +unlogged override does not exist. + +## Reviewer Contract + +Each independent reviewer and challenge-round reviewer returns +schemas/reviewer-verdict.schema.json. + +The challenge round requires: + +- the reviewer being challenged +- counter-evidence +- whether the reviewer's position changed + +This prevents a council from producing three parallel summaries and calling +them debate. diff --git a/skills/product-design-harness/resources/docs/COUNCIL.md b/skills/product-design-harness/resources/docs/COUNCIL.md new file mode 100644 index 000000000..26dabe418 --- /dev/null +++ b/skills/product-design-harness/resources/docs/COUNCIL.md @@ -0,0 +1,109 @@ +# UX3 Review Council + +The council is a disagreement system, not a voting system. + +It protects three different product realities: + +| Reviewer | Protects | +|---|---| +| User Flow | Real actors, problems, consequences, affected people, and exclusion. | +| Evidence Flow | Provenance, signal strength, counter-signals, measurement, and failure criteria. | +| Business Flow | Value exchange, cost, retention, distribution, and defensibility. | +| Claim Analyst | Testable claims and dependency edges. | +| Uncertainty Reviewer | Evidence tier, risk class, reversibility, and false confidence. | +| Council Facilitator | Weakest flow, trade-off, human decision, and final boundary. | + +The machine-readable registry is agents/registry.json. + +## Fork, Join, Challenge + +1. The Claim Analyst creates the claim graph. +2. User, Evidence, and Business reviewers work in parallel without seeing the + other lane verdicts. +3. The council waits until all three independent reviews are complete. +4. Each lane runs one challenge round against another material claim. +5. The Uncertainty Reviewer checks evidence tier, risk, reversibility, and + freshness. +6. The facilitator synthesizes only after all required contracts are valid. +7. Human-owned decisions move to the Human Judgment Gate. + +## Forced Disagreement + +Each challenge-round output must include: + +| Field | Requirement | +|---|---| +| objection_to | One lane whose conclusion or premise is challenged, or none. | +| counter_evidence | Evidence or reasoning that could change that lane's verdict. | +| position_change | unchanged, strengthened, weakened, or reversed. | + +If objection_to is none, the reviewer must state what counter-evidence was +searched and why it did not change the conclusion. + +The facilitator must reject council synthesis when: + +- a lane review is missing +- challenge fields are missing +- evidence lacks provenance or is expired without downgrade +- two claims contradict each other without an explicit trade-off +- a human-owned decision has no accountable owner + +## UX3 Intersections + +The facilitator reviews the intersections, not only the lanes. + +| Intersection | Name | Core question | +|---|---|---| +| User + Evidence | Situated Understanding | What do people say, feel, and do, and how strong is each signal? | +| Evidence + Business | Viable Learning | What evidence shows that value can be sustained? | +| User + Business | Sustainable Value Exchange | Is the exchange valuable and fair to both sides? | +| All three | UX3 Decision Kernel | Which canonical verdict and execution boundary follow from the three lane results? | + +## Weakest Flow Rule + +| Lane state | Combined verdict | +|---|---| +| Any lane is stop_reframe, for any reason. | stop_reframe | +| No lane stops and at least one lane is verify. | verify | +| All three lanes are continue. | continue | + +Every stop_reframe lane verdict must name a `stop_reason_class` +(actor, safety, core_evidence, irreversible_risk, business_viability, other). +The class is reporting metadata. It never downgrades a stop. + +The weakest flow is selected deterministically: + +1. The lane with the most severe verdict (stop_reframe > verify > continue). +2. If tied, the tied lane with the lowest lane `evidence_tier` (t0 is lowest). +3. If still tied, fixed priority: evidence, then user, then business. + +The weakest flow selects the next action: + +- User weakness creates a user-learning step. +- Evidence weakness creates an evidence proof step. +- Business weakness creates a value, retention, cost, or channel test. + +## Human Judgment Gate + +The gate is mandatory for brand-affecting work, vulnerable users, irreversible +actions, major risk appetite, ethics, strategy, or meaning. + +Taste is handled inside this gate: + +| Taste dimension | Question | +|---|---| +| Coherence | Does the product express one clear idea? | +| Restraint | Did the team avoid unnecessary power or scope? | +| Trust | Does the product reveal enough to be believed? | +| Dignity | Does it respect users and affected people? | +| Timing | Is this the right moment to ask for action? | +| Meaning | Is the work worth existing beyond short-term output? | + +Record the final call with schemas/human-decision.schema.json. + +## Final Output + +The facilitator returns schemas/review-result.schema.json. + +The council should make uncertainty visible. It should not make uncertainty +disappear. diff --git a/skills/product-design-harness/resources/docs/DECISION-RULES.md b/skills/product-design-harness/resources/docs/DECISION-RULES.md new file mode 100644 index 000000000..e17c860f6 --- /dev/null +++ b/skills/product-design-harness/resources/docs/DECISION-RULES.md @@ -0,0 +1,91 @@ +# Decision Rules + +UX3 decision rules are operational constraints for product judgment. They tell a reviewer when a rule activates, what to inspect, what evidence can change the decision, what counter-signal can invalidate the claim, what remains human-owned, when to stop, and what bounded output must be emitted. + +The canonical machine source is `knowledge/rules.json`. This document paraphrases the same kernel for human readers. + +## Rule Contract + +Every rule answers the same questions: + +| Field | Meaning | +|---|---| +| Trigger | The observable condition that activates the rule. | +| Must inspect | The inputs, actors, risks, or evidence the reviewer must examine. | +| Must do | Required review behavior. | +| Must not do | Behavior that makes the review invalid or misleading. | +| Evidence required | The decision-changing proof needed for the rule. | +| Counter-signal | What could weaken, invalidate, or reframe the claim. | +| Human boundary | What remains owned by a named person. | +| Stop condition | The condition that blocks, downgrades, or reframes execution. | +| Output requirement | The bounded machine-readable result the reviewer must emit. | + +## Rule Families + +| Rule ID | Family | Operational test | +|---|---|---| +| ux3.rule.actor_boundary | Actor boundary | Separate operator, beneficiary, affected person, machine actor, buyer, issuer, and accountable owner before deciding. | +| ux3.rule.problem_hypothesis | Problem hypothesis | Treat requests as hypotheses until situation, workaround, cost, and falsification criteria are known. | +| ux3.rule.behavior_subjective_separation | Behavior and subjective experience | Keep observed behavior and stated experience as separate signals. | +| ux3.rule.disconfirm_first | Disconfirm first | Present material counter-evidence before support. | +| ux3.rule.evidence_separation | Evidence separation | Keep source, signal, interpretation, counter-signal, and decision impact distinct. | +| ux3.rule.evidence_sized_action | Evidence-sized action | Limit the next action by evidence tier, risk, reversibility, and recovery capacity. | +| ux3.rule.minimum_authority | Minimum authority | Give automated actors only the authority needed for the current proof step. | +| ux3.rule.high_risk_action_bundle | High-risk action bundle | External or irreversible actions need owner, approval, limit, trace, failure handling, and recovery path. | +| ux3.rule.minimum_validated_proof | Minimum Validated Proof | Test the riskiest assumption, not the smallest feature list. | +| ux3.rule.feedback_classification | Feedback classification | Classify feedback as evidence, noise, incident, or drift before changing direction. | +| ux3.rule.false_product_market_fit | False product-market fit | Rank repeated use, workflow dependence, payment, and reputation-bearing referral above praise or novelty. | +| ux3.rule.whole_ownership_cost | Whole ownership cost | Include support, trust, measurement, maintenance, confusion, governance, and opportunity cost. | +| ux3.rule.depth_accumulation | Depth accumulation | Identify durable depth from domain terms, edge cases, failure history, workflow rules, evaluations, and expert judgment. | +| ux3.rule.failure_to_rule_learning | Failure-to-rule learning | Turn repeated failure into a case, test, evaluation, rule, or explicit accepted risk. | +| ux3.rule.human_judgment | Human judgment | Record taste, ethics, meaning, strategy, risk appetite, and final responsibility as accountable human input. | +| ux3.rule.mental_model_alignment | Mental model alignment | Test whether target actors can predict material behavior, consequence, data or authority use, and intervention. | +| ux3.rule.human_factors_load | Human factors load | Review human, task, tool, and environment together; expose state and preserve recovery under real cognitive load. | +| ux3.rule.research_validity | Research validity | Match method to uncertainty and keep attitude, behavior, simulation, qualitative meaning, and quantitative frequency distinct. | +| ux3.rule.value_market_path | Value-to-market path | Connect target-actor value to a credible buyer, exchange, channel, willingness signal, and pre-fit retention hypothesis. PMF claims stay with `ux3.rule.false_product_market_fit`. | +| ux3.rule.human_agent_interaction | Human-agent interaction | Make intent, plan, status, action, approval, interruption, correction, logs, handoff, and recovery inspectable. | +| ux3.rule.motivation_ethics | Motivation ethics | Prevent retention, personalization, rewards, scarcity, or social pressure from overriding autonomy, consent, or exit. | + +## Source Curriculum Boundary + +Operationalization is narrower than the source curriculum. A rule card does +not claim to replace a chapter, method, case, or teaching sequence. It extracts +only the judgment that an agent must be able to trigger, test, challenge, stop, +and emit in a bounded form. + +Every newly distilled rule cites its source as `UX3 chapter X-Y` inside +`knowledge/rules.json`; `knowledge/source-chapters.json` resolves those chapter +IDs through a checked-in source manifest and checksum. The chapter remains the +human teaching source; the rule is the machine-operable projection. Agent-era controls such as minimum +authority, deterministic verdict reduction, and machine-readable handoff may be +new extensions rather than claims copied from the original curriculum. + +When multiple rules trigger, outputs compose rather than overwrite one another. +`ux3.rule.value_market_path` covers the pre-fit value, buyer, channel, and +learning path; `ux3.rule.false_product_market_fit` remains canonical for fit or +traction claims. `ux3.rule.human_agent_interaction` covers interaction +visibility and control surfaces; permission, approval records, authority, trace, +rollback, and the operational `recovery_path` remain canonical in +`authority_boundary` and `high_risk_action_bundle`, referenced by ID. The +interaction contract records only the user-visible `recovery_surface`. + +`ux3.rule.research_validity` owns method fitness, sample, context, and +limitations. It references canonical evidence receipts plus behavior, +subjective, counter-signal, and decision-impact records instead of duplicating +their contents. + +## Strength + +| Strength | Meaning | +|---|---| +| Required | Violating the rule makes the review invalid or blocks execution. | +| Conditional | Required when the observable trigger is true. | +| Advisory | Improves judgment but needs human interpretation. | + +Quick reviews should still obey required rules. Standard and Council reviews activate more conditional rules when risk, uncertainty, external action, sensitive data, stakeholder conflict, or low reversibility appears. + +## Human Boundary + +Rules do not remove human judgment. They make it explicit. + +Human taste remains an accountable input, never an evidence score. A person may raise the proof bar, accept bounded risk, or choose a strategic direction, but the review must record the owner, rationale, bounded action, and reversal condition. diff --git a/skills/product-design-harness/resources/docs/GLOSSARY.md b/skills/product-design-harness/resources/docs/GLOSSARY.md new file mode 100644 index 000000000..f54f2d19e --- /dev/null +++ b/skills/product-design-harness/resources/docs/GLOSSARY.md @@ -0,0 +1,44 @@ +# Glossary + +| Term | Meaning | +|---|---| +| Product Design Harness | A product judgment system that runs across direction, build, launch, and feedback. | +| UX3 | User Flow, Evidence Flow, and Business Flow reviewed together. | +| Operating protocol | Six gates that apply UX3 before execution. | +| UX3 Decision Kernel | The deterministic center of UX3: Validate, Reduce, Gate, and Emit one canonical review result. | +| User Flow | The target population, actor situation, current workaround, friction, affected people, and excluded groups. | +| Evidence Flow | The sensing, learning, and calibration system that separates source, signal, interpretation, counter-signal, and decision impact; human judgment is recorded separately as accountable input. | +| Business Flow | The company, project owner, issuer, value exchange, cost, authority, stakeholders, viability, and accountability. | +| Primary user | The target actor expected to operate the product for the main outcome. | +| Secondary user | An actor involved in the workflow without being the primary target. | +| Machine actor | An automated agent, model, workflow, or software component that can sense, decide, call tools, or act. | +| Beneficiary | A person or group expected to receive benefit without necessarily operating the product. | +| Affected person | A person or group changed by the product decision, including those who do not operate it. | +| Excluded group | A population intentionally or unintentionally underserved, blocked, misrepresented, or left outside the product boundary. | +| Accountable owner | The named person or team responsible for a product decision, machine actor, claim, or execution boundary. | +| Issuer | The entity that issues a credential, claim, artifact, decision, or product promise. | +| Externality bearer | A community or group that absorbs cost, risk, confusion, exclusion, or other product externalities. | +| Gate | A decision point with input, output, and escalation rules. | +| Claim | A testable statement that must hold for the product direction to proceed. | +| Claim status | assumption or verified; a verified claim must cite at least one evidence receipt id. | +| Signal | What was observed or reported before interpretation. | +| Interpretation | What the reviewer thinks the signal means. | +| Counter-signal | Evidence or reasoning that weakens a claim. | +| Decision impact | What changes in the product decision because of the interpreted evidence. | +| Observed outcome | What happened after a bounded action was taken. | +| Evidence receipt | A traceable source, signal, interpretation, freshness record, and decision impact. | +| Evidence tier | t0-t4 operational proof level that limits the size of the next action. | +| Lane evidence tier | The t0-t4 tier each lane review reports; the tie-break in weakest flow selection when lane verdicts match. | +| Proof bar | The evidence level required before the next stage. | +| Confidence level | A human-readable judgment about trust in the current interpretation. | +| Challenge round | The council round where each lane tests another lane's material premise. | +| Context pack | The handoff package that constrains execution after a Continue verdict. | +| Human Judgment Gate | The place where taste, risk, strategy, ethics, or meaning stays human-owned. | +| Human taste | A person's accountable preference about quality, feel, meaning, taste, or strategic appetite; it is not an evidence score. | +| Human judgment | A named person's accountable decision on taste, ethics, meaning, risk appetite, or final responsibility. | +| Accountable input | A recorded human-owned input that may set direction, raise a proof bar, or accept bounded risk without pretending to be observed evidence. | +| Bounded action | A next step limited by evidence tier, risk, reversibility, scope, owner, and stop conditions. | +| Stop condition | A clear condition that blocks or downgrades execution. | +| Stop reason class | The reason class (actor, safety, core_evidence, irreversible_risk, business_viability, other) required with every stop_reframe verdict. | +| Decision rule | An operational UX3 constraint with observable triggers, evidence, counter-signals, human boundary, stop conditions, and output requirements. | +| Learning loop | signal -> interpretation -> counter-signal -> decision impact -> human judgment -> bounded action -> observed outcome -> evidence update or rule update. | diff --git a/skills/product-design-harness/resources/docs/HARNESS.md b/skills/product-design-harness/resources/docs/HARNESS.md new file mode 100644 index 000000000..81654bfe7 --- /dev/null +++ b/skills/product-design-harness/resources/docs/HARNESS.md @@ -0,0 +1,284 @@ +# Product Design Harness Manual + +![Harness sequence](../assets/harness-sequence.svg) + +## 1. Definition + +Product Design Harness is a repeatable decision system for product work. + +It runs before execution. + +Execution can mean design, code, prototype, launch, growth, automation, or investment. The harness asks whether the work deserves to happen, what evidence is required, and what constraints must shape the next step. + +## 2. Why It Exists + +Modern teams can produce product artifacts quickly: + +- briefs +- prototypes +- screens +- code +- dashboards +- launch plans +- experiments +- summaries + +Speed creates a new risk. + +A weak assumption can become a polished artifact before anyone has proven the problem is real. + +Product Design Harness slows down the wrong things and accelerates the right things. + +| Accelerate | Slow down | +|---|---| +| Learning from real behavior. | Building from vague assumptions. | +| Explicit trade-offs. | False certainty. | +| Small proof steps. | Large unvalidated builds. | +| Reversible experiments. | Irreversible high-risk actions. | +| Clear handoffs. | Ambiguous requests. | + +## 3. UX3 Model + +### 3.1 User Flow + +User Flow checks whether the actor, problem, situation, and affected people are real. + +It can simulate the user's path through the product, but simulation is not validation. + +Use the walkthrough to find assumptions. Use quotes, behavior, context, and consequences to validate them. + +Required questions: + +| Question | Why it matters | +|---|---| +| Who directly operates the product? | Avoids vague "users". | +| Who benefits from the outcome? | Operator and beneficiary can differ. | +| Who is affected without operating it? | Surfaces hidden risk. | +| Who is excluded? | Prevents accessibility and market blind spots. | +| What current workaround exists? | Workarounds connect stated pain to real cost. | +| What would prove the problem is not real? | Prevents confirmation-only reviews. | + +### 3.2 Evidence Flow + +Evidence Flow checks whether the team has proof strong enough for the next decision. + +Evidence may come from internal sources, external sources, or direct user learning. + +The harness must keep source, signal, interpretation, counter-signal, and +decision separate. + +Required questions: + +| Question | Why it matters | +|---|---| +| What is data, and what is interpretation? | Keeps raw signals separate from narrative. | +| What decision does each metric change? | Rejects vanity metrics. | +| What would stop or reframe this work? | Makes failure useful. | +| What must be measured before scaling? | Prevents blind expansion. | +| What logs or traces are needed? | Makes decisions reviewable. | +| What repeated failure should become a rule? | Turns mistakes into harness improvements. | +| Which evidence is internal and which is external? | Prevents treating market research and product telemetry as the same kind of proof. | + +### 3.3 Business Flow + +Business Flow checks whether the direction is worth sustaining. + +Business Flow starts from the user side: value, switching behavior, urgency, trust, and willingness to return. + +The business model should be inferred from the user's workflow, not imposed on top of it. + +Required questions: + +| Question | Why it matters | +|---|---| +| What value is created? | Useful work still needs a value argument. | +| Who pays, adopts, returns, or recommends? | Separates curiosity from pull. | +| What does this cost to maintain? | Build cost is not total cost. | +| What channel can distribute it? | Products need routes to adoption. | +| What makes users return? | Novelty is not retention. | +| What becomes hard to copy? | Generic features do not defend a product. | + +### 3.4 UX3 Intersections + +UX3 is not a set of independent checklists. + +It is a set of intersections. + +| Intersection | Name | Review question | +|---|---|---| +| User Flow + Business Flow | Sustainable Value Exchange | What value does the user receive, and what value can the product capture? | +| User Flow + Evidence Flow | Situated Understanding | What do people say, feel, and do, and how strong is each signal? | +| Evidence Flow + Business Flow | Viable Learning | What evidence shows this can become sustainable value? | +| User Flow + Evidence Flow + Business Flow | UX3 Decision Kernel | Which canonical verdict and execution boundary follow from the three lane results? | + +## 4. Stages + +Use stage to choose the right evidence bar. + +| Stage | Main question | Required proof | +|---|---|---| +| Idea | Is the problem real and specific? | Actor, situation, frequency, cost, workaround. | +| Prototype | What behavior should be observed? | One riskiest assumption and a focused test. | +| Launch | Is there enough pull and reliability? | Repeated use, adoption, willingness, recovery path. | +| Scale | Can this compound safely? | Retention, cost, governance, distribution, defensibility. | + +For multi-review work, use `OPERATING-PROTOCOL.md`. + +UX3 adds six gates: Stage, User Flow, Evidence Flow, Business Flow, Council, and Human Judgment. + +It should be used when the decision requires external evidence, multiple reviewers, claim analysis, uncertainty review, or human-owned trade-offs. + +## 5. Verdicts + +![Decision gate](../assets/decision-gate.svg) + +| Verdict | Meaning | Required behavior | +|---|---|---| +| Continue | Evidence and risk are sufficient for the next step. | Proceed with explicit scope, non-goals, and acceptance criteria. | +| Verify | Direction may be valid but evidence is incomplete. | Run the smallest validation step before expanding work. | +| Stop/Reframe | Core problem, evidence, risk, or viability fails. | Stop execution or redefine the problem. | + +Do not turn Verify or Stop/Reframe into a build plan. + +## 6. Evidence Tiers + +Evidence tier limits the size of the next action. Confidence cannot upgrade a +weak tier. + +| Tier | Examples | Use | +|---|---|---| +| t0 | No traceable signal. | Reframe or define research. | +| t1 | Opinions, quotes, generic trends, internal preference. | Generate hypotheses only. | +| t2 | Contextual interviews, support patterns, observed workarounds, small tests. | Run a focused reversible prototype. | +| t3 | Repeated behavior, payment, retention, referral, adoption, logs. | Consider bounded launch or expansion. | +| t4 | Durable retention, workflow dependency, sustainable economics, governance proof. | Consider scale. | + +## 7. Trade-Off Logic + +Product decisions are trade-offs, not isolated scores. + +| If this is high | And this is low | Default verdict | +|---|---|---| +| User pain | Evidence strength | Verify | +| User pain | Business value | Verify or Reframe | +| Business value | User clarity | Stop/Reframe | +| Build speed | Evidence quality | Verify | +| Automation power | Human control | Stop/Reframe | +| Growth potential | Trust design | Verify | +| Revenue potential | Access fairness | Verify | +| Strategic value | Reversibility | Human judgment required | + +## 8. Human Judgment Gate + +Taste is not decoration. + +Taste is the human ability to judge fit, restraint, coherence, trust, and meaning. + +Run the Human Judgment Gate when taste, risk appetite, strategy, ethics, +meaning, vulnerable users, brand, or irreversible action is involved. + +| Taste dimension | Review question | +|---|---| +| Coherence | Does the product feel like one clear idea? | +| Restraint | Did the team avoid building everything it could build? | +| Trust | Does the product reveal enough to be believed? | +| Dignity | Does it respect users and affected people? | +| Timing | Is this the right moment to ask the user to act? | +| Meaning | Is the work worth existing beyond short-term output? | + +Taste is one part of Human Judgment Gate, not a seventh mechanical score. + +The gate can raise the proof bar or stop a mechanical continue verdict. If no +accountable owner responds, the work pauses; it never defaults to execution. + +### When The Harness Blocks Your Pet Feature + +Sooner or later a verdict blocks something the team loves. The exit exists, +and here is what it costs. Anyone with authority may execute despite a +`verify` or `stop_reframe` verdict by signing a verdict override +(schemas/verdict-override.schema.json): one named owner, the weakest flow +restated in their own record, an explicit scope, an expiry, and tripwires +that void it. The review itself is never edited - the harness will not +pretend it agreed. When the override lapses, the original verdict is in +force again; renewal is a fresh review with new evidence, never an +extension. Active overrides accumulate in templates/override-ledger.md, +and three on one product area force a `verify` on the next review. In +short: the feature can ship, but it ships with your name on it. + +## 9. Council Process + +For council work: + +1. Run Claim Analyst. +2. Retrieve only missing evidence. +3. Fork User, Evidence, and Business reviewers in parallel. +4. Wait for all three independent reviews. +5. Run one challenge round per lane. +6. Run Uncertainty Reviewer. +7. Run Council Facilitator. +8. Route accountable decisions to Human Judgment Gate. + +The facilitator must: + +- list disagreements +- identify the weakest flow +- name the trade-off +- call out the human-owned decision +- produce the next smallest action + +The council must complete the challenge round before converging. + +The goal is not agreement. + +The goal is to expose the weakest claim and the trade-off that humans must own. + +## 10. Stop Conditions + +Stop or downgrade when: + +- the user is undefined +- the problem cannot be tested +- evidence has only unweighted opinion or simulation +- the requested work starts with output before proof +- the product hides powerful actions behind friendly wording +- the team cannot name who is affected +- there is no failure condition +- there is no reason to return +- the value depends only on being easy to build +- the next action creates irreversible risk without human review + +## 11. Handoff To Execution + +If the verdict is Continue, create a context pack before execution. + +The context pack must include: + +| Field | Purpose | +|---|---| +| Goal | What outcome matters. | +| Stage | Current maturity. | +| Scope | What to do now. | +| Non-goals | What not to do. | +| Assumptions | What remains unproven. | +| User rules | Actor, mental model, affected people, accessibility. | +| Evidence rules | Measurements, logs, failure criteria. | +| Business rules | Value, cost, retention, distribution. | +| Acceptance criteria | What done means. | +| Stop conditions | When execution must return to human judgment. | + +## 12. Harness Improvement Loop + +Every review should improve the harness. + +| Event | Convert into | +|---|---| +| Repeated confusion | Principle or glossary entry. | +| Bad decision | Stop condition. | +| Weak handoff | Template field. | +| Misleading metric | Evidence rule. | +| Failed prototype | Test case. | +| Hidden stakeholder | User Flow rule. | +| Scope creep | Trade-off rule. | +| Trust incident | Human Judgment Gate rule. | + +The harness should become harder to misuse over time. diff --git a/skills/product-design-harness/resources/docs/LEARNING-LOOP.md b/skills/product-design-harness/resources/docs/LEARNING-LOOP.md new file mode 100644 index 000000000..61b8a8310 --- /dev/null +++ b/skills/product-design-harness/resources/docs/LEARNING-LOOP.md @@ -0,0 +1,46 @@ +# Learning Loop + +UX3 learning converts product feedback and failure into stronger judgment. The loop keeps machine evidence, human interpretation, and accountable choice separate. + +```text +signal -> interpretation -> counter-signal -> decision impact + -> human judgment -> bounded action -> observed outcome + -> evidence update or rule update +``` + +## Steps + +| Step | Required separation | +|---|---| +| Signal | Record what was observed before explaining it. | +| Interpretation | State what the reviewer thinks the signal means. | +| Counter-signal | Name what weakens, contradicts, or reframes the interpretation. | +| Decision impact | State what changes because of the evidence. | +| Human judgment | Record taste, ethics, meaning, strategy, or risk appetite as accountable human input. | +| Bounded action | Limit the next action by evidence tier, risk, reversibility, and recovery capacity. | +| Observed outcome | Capture what happened after action. | +| Evidence update or rule update | Update the evidence record, add a test or evaluation, create a rule, or record an accepted risk. | + +## Failure Becomes System Memory + +A repeated failure is not complete learning until it becomes one of: + +| Artifact | Use | +|---|---| +| Reproducible case | The failure can be observed again. | +| Test | The failure is prevented by automation. | +| Evaluation | The failure is measured in a recurring review. | +| Decision rule | The failure changes future product judgment. | +| Accepted risk | A named human records why the risk is tolerated and when to revisit it. | + +## Stop Conditions + +Stop or reframe when: + +- source, signal, interpretation, or decision impact is missing; +- counter-signals have not been inspected for a material decision; +- human-owned judgment is hidden inside evidence language; +- the next action is larger than the current evidence can justify; +- a repeated failure has no test, evaluation, rule, or accepted-risk record. + +The loop is complete only when the observed outcome changes evidence, changes a rule, or explicitly preserves the current rule with a recorded reason. diff --git a/skills/product-design-harness/resources/docs/LIVE-CODING.md b/skills/product-design-harness/resources/docs/LIVE-CODING.md new file mode 100644 index 000000000..8f2e2c504 --- /dev/null +++ b/skills/product-design-harness/resources/docs/LIVE-CODING.md @@ -0,0 +1,173 @@ +# Live Coding Workflow + +Use this workflow when a builder wants a coding agent to implement product work +inside a reviewed boundary. + +The rule is simple: review first, code second. A `continue` verdict plus a +valid context pack authorizes implementation only inside the named boundary. +`verify` authorizes only the proof step. `stop_reframe` blocks coding. + +## Golden Chain + +| Artifact | Role | +|---|---| +| `examples/live-coding-product-brief.json` | Product brief with actors, evidence, assumptions, and execution boundary. | +| `examples/live-coding-review.json` | Canonical review result with `continue` verdict. | +| `examples/live-coding-context-pack.json` | Implementation handoff allowed by the review. | + +### Installed Skill Validation + +For an installed skill, run from its `resources` directory. For repository +contributors, run the same commands from the repository root. All relative +example, schema, and script paths below use that working directory. + +Prepare the Python environment once: + +```text +python3 -m venv .venv +.venv/bin/python -m pip install -r requirements-dev.txt +``` + +Validate the review and context pack together before coding: + +```text +.venv/bin/python scripts/check_review.py examples/live-coding-review.json --context-pack examples/live-coding-context-pack.json +``` + +This joint check validates the review, context-pack schema, and copied handoff +fields. A review-only check does not validate a context pack. + +### Repository Development Checks + +The complete source repository also contains `tests` and `scripts/validate.py`. +These development checks run from the repository root; they are not installed +skill commands and are not required to validate an implementation handoff. + +```text +.venv/bin/python -m unittest discover -s tests +.venv/bin/python scripts/validate.py +``` + +## Copyable Prompts + +### 1. Select Working Language + +```text +Use Product Design Harness for this session. + +Set session_config to: +{ + "working_language": "", + "canonical_identifiers": "en", + "fallback_language": "en" +} + +Keep JSON property names, enum values, rule IDs, schema IDs, file paths, +evidence IDs, and verdicts in English. Use the selected working language only +for human-readable explanations and free-text fields. +``` + +### 2. Pre-Code Review + +```text +Before coding, convert this request into a Product Design Harness product brief. + +Use schema_version 2.1. Include actor_boundary, including +actor_boundary.target_population, product organization, stakeholder effects, +unresolved assumptions, human judgment boundaries, +evidence receipts, and this exact execution_boundary: + +may_do: implement the approved bounded change +must_not_do: expand scope or execute external irreversible actions +must_ask: new stakeholder, data, risk, or scope appears + +Then run the smallest responsible review mode. Return only a review result +valid through scripts/check_review.py against schemas/review-result.schema.json. +Do not produce an +implementation plan unless the verdict is continue. +``` + +### 3. Validate Review Output + +```text +Validate the review before using it. + +Run: +.venv/bin/python scripts/check_review.py + +If validation fails, fix the review artifact. Do not code from an invalid +review. If the verdict is verify, run only the proof step. If the verdict is +stop_reframe, return the reframed product question. +``` + +### 4. Context-Pack Handoff + +```text +The review verdict is continue. Create a context pack valid against +schemas/context-pack.schema.json. + +The context pack must copy the review_id, session_config, actor_boundary, +product_organization, stakeholder_effects, unresolved_assumptions, +human_judgment_boundary, evidence IDs, stop conditions, human approval gates, +and exact execution_boundary from the review. + +Set context-pack scope to an exact copy of the approved +review.execution_boundary.may_do list. Do not summarize or expand it. + +Run the joint handoff check: +.venv/bin/python scripts/check_review.py --context-pack + +Implementation may begin only after the joint handoff check passes. Implement +only the approved may_do actions. Do not expand scope. +``` + +### 5. Scope Change + +```text +Pause implementation and return to Product Design Harness review. + +Reason: a new stakeholder, data, risk, or scope appeared. + +Summarize: +- what changed +- who is newly affected +- what evidence supports the change +- which boundary item was crossed +- whether the current context pack should continue, verify, or stop_reframe + +Do not continue coding until a new valid review and context pack authorize the +changed scope. +``` + +### 6. Post-Build Feedback Classification + +```text +Classify post-build feedback for the next Product Design Harness iteration. + +For each signal, separate: +- raw artifact or source +- signal type: quote, observed behavior, product log, support pattern, + workflow trace, market signal, policy, or derived +- interpretation +- decision impact +- counter-signal +- evidence tier +- unresolved assumption changed by the signal + +Return updated evidence receipts. Do not change the product direction unless +the evidence changes the review boundary. +``` + +## Live-Coding Rules + +| Situation | Action | +|---|---| +| `continue` and valid context pack | Code only inside the context-pack scope. | +| `verify` | Run only the proof step; do not build the feature. | +| `stop_reframe` | Stop coding and return the reframed product question. | +| Boundary changes | Pause and run a new review. | +| New post-build evidence | Classify it before deciding the next iteration. | + +The implementation agent may decide technical details inside the context pack. +It may not decide whether the product direction, stakeholder boundary, evidence +bar, or human judgment boundary changed. diff --git a/skills/product-design-harness/resources/docs/MULTI-AGENT-ALIGNMENT.md b/skills/product-design-harness/resources/docs/MULTI-AGENT-ALIGNMENT.md new file mode 100644 index 000000000..f3c7c26be --- /dev/null +++ b/skills/product-design-harness/resources/docs/MULTI-AGENT-ALIGNMENT.md @@ -0,0 +1,59 @@ +# Autonomous Multi-Agent Alignment & Boundary Governance Protocol + +## 1. Executive Principle: An Alignment Harness for Machine Swarms + +In modern software development driven by autonomous multi-agent teams (e.g. **1 Integrator/Admin + N Workers + 1 QC Auditor**), Product Design Harness serves as the **machine-readable boundary constitution**, rather than a bureaucratic form for human developers. + +- **Human's Role**: Sole Judge and Strategic Founder (sets high-level intent, evaluates trade-offs, grants external permissions). +- **Integrator / Admin**: Deconstructs work packages, enforces path locks, and dispatches tasks bounded by the Harness contract. +- **Workers (Autonomous Coding Agents)**: Execute with maximum speed *strictly within* the `may_do` scope in isolated worktrees; zero scope expansion. +- **QC Auditor (Independent Review Agent)**: Read-only auditor validating code diffs against the Harness `must_not_do` boundaries and reporting scope violations. + +--- + +## 2. Advisory Routing and Validated Execution Boundaries + +Use the smallest responsible review mode without turning a heuristic into permission to execute. + +1. **Routing is advisory**: + - `scripts/jev_gate.py route` labels a task as routine, discovery, or commitment. It always returns `bypass: false` and `review_required: true`. + - Routine words cannot establish actual scope or risk. A scope above five changed files takes priority over routine keywords when context is supplied to the Python classifier. + - Reversibility lowers review mode, not the requirement for review. Reuse a still-valid context pack for an unchanged approved task instead of re-reviewing it. +2. **Baseline evaluation is advisory**: + - `evaluate --task` accepts task metadata and produces a local heuristic assessment with `advisory: true`. It does not validate evidence truth or authorize implementation. + - Missing evidence defaults to `t0`; unsupported tiers are rejected. Supported tiers are `t0`, `t1`, `t2`, `t3`, and `t4`. A `t0` assessment stops and reframes; `t1` supports at most verification. + - The helper is offline. The unused live API client and ignored `--live` options have been removed. No model call or latency guarantee is part of this helper. +3. **Boundary extraction requires canonical inputs**: + - `boundary --task` requires a JSON object with `review` containing a complete canonical review result. Raw prompts, evidence tiers, filenames, and proposed proof steps cannot create an execution boundary. + - For `continue`, the same JSON object must also contain `context_pack`. The canonical handoff validator checks the review, context pack, identity, evidence references, scope, and controls together. + - For `verify`, only the reviewed proof boundary and `proof_step` are returned. For `stop_reframe`, the reviewed boundary and `reframed_question` are returned. Neither branch gains implementation permissions from task filenames. + - Output preserves `may_do`, `must_not_do`, `must_ask`, `stop_conditions`, `human_approval_gates`, and `high_risk_actions`. A valid handoff does not mean a listed human approval has been granted. + - Invalid JSON, missing reviews, invalid evidence tiers, and mismatched handoffs fail with a nonzero exit status and no execution-boundary output. The helper uses `check_review.py`; it does not establish a second review contract. + +--- + +## 3. Preserve Boundaries Across Handoffs + +In long-running autonomous sessions (30~100+ turns), generative chat summaries often dilute or erase negative constraints (e.g. generalizing negative database constraints into broad feature summaries). + +The runtime must preserve the original review and context pack while executing a task. The boundary helper copies their controls without rewriting or broadening them. The harness does not control a host agent's context compaction and cannot guarantee lossless retention across arbitrary runtimes. After compaction, restore and validate the original handoff before resuming work. + +--- + +## 4. Role Mapping & Boundary Enforcement + +| Role | Responsibility | Input Contract | Output Requirement | +|---|---|---|---| +| **Integrator / Admin** | Package slicing & lock enforcement | Product intent | Task Context Pack with digest locks | +| **Worker (Builder)** | Atomic implementation & local tests | `may_do` & `must_not_do` | Clean patch + unit test evidence | +| **QC Auditor** | Defect-first boundary audit | Git diff + Context Pack | PASS or Scope Drift Rejection | +| **Advisory Router** | Review-mode triage | Task prompt and optional scope | Routine, discovery, or commitment; no review bypass | +| **Boundary Helper** | Validate and preserve execution scope | Canonical review and matching context pack for continue | Reviewed boundary and unchanged human controls | + +--- + +## 5. Verification Scope + +The telemetry, authentication, and media-sync cases in `tests/test_multi_agent_alignment.py` are illustrative local fixtures. They do not establish production deployments, privacy outcomes, collision rates, or latency measurements. + +`tests/test_gate_boundaries.py` exercises the actual repository and installable helper: routine classification cannot bypass review, unsupported evidence tiers fail closed, raw task metadata cannot grant execution permissions, invalid or expanded context packs are rejected, and valid canonical boundaries retain their exact scope and controls. Bundle tests also require every distributed runtime script to match its canonical source. diff --git a/skills/product-design-harness/resources/docs/OPERATING-PROTOCOL.md b/skills/product-design-harness/resources/docs/OPERATING-PROTOCOL.md new file mode 100644 index 000000000..72ba0ce9f --- /dev/null +++ b/skills/product-design-harness/resources/docs/OPERATING-PROTOCOL.md @@ -0,0 +1,106 @@ +# UX3 Operating Protocol + +UX3 is the judgment model: User Flow, Evidence Flow, and Business Flow. + +Its operating protocol decides when to inspect each dimension, what must leave +each gate, and when work must escalate. + +The protocol turns product judgment into repeatable action. It does not add +more product dimensions. + +Session startup order is fixed: load `schemas/session-config.schema.json`, +then `knowledge/ontology.json`, then triggered `knowledge/rules.json`, then +`prompts/start-review.md`. Use `working_language` for human-facing prose while +keeping canonical Flow identifiers and rule IDs in English. + +## The Six Gates + +| Gate | Trigger | Required input | Required output | Escalation | +|---|---|---|---|---| +| Stage Gate | Any new or materially changed direction. | Product direction, proposed next step, constraints. | Stage and proof bar. | Unknown stage becomes standard_gate. | +| User Flow Gate | The direction changes behavior, access, control, or outcomes. | Actor boundary, workflow, experience signals. | Lane verdict, affected people, disconfirming evidence, stop condition. | Vague actor or untestable problem becomes stop_reframe. | +| Evidence Flow Gate | A claim is used to justify action. | Claims and evidence receipts. | Lane verdict, evidence tier, freshness status, missing proof. | Expired, untraceable, or t0 evidence becomes verify or stop_reframe. | +| Business Flow Gate | Work consumes ownership, distribution, support, or trust. | User value, cost boundary, retention and channel assumptions. | Lane verdict, value exchange, viability proof, stop condition. | No durable value path becomes verify or stop_reframe. | +| Council Gate | Risk, uncertainty, cost, or disagreement exceeds Quick Gate. | Claim graph and three independent lane reviews. | Challenge round, weakest flow, trade-off, proposed verdict. | Missing objection or unresolved contradiction blocks synthesis. | +| Human Judgment Gate | Taste, risk appetite, strategy, ethics, meaning, vulnerable users, brand, or irreversible action is involved. | Council result, options, evidence, reversal conditions. | Accountable decision record and final boundary. | No accountable owner means no continue verdict. | + +The Human Judgment Gate includes taste. Taste is not a seventh mechanical score. +It is a human decision about coherence, restraint, trust, dignity, timing, and +meaning. + +Product organization, issuer, stakeholder effects, and accountable owner are +required before a handoff can authorize execution. + +## Stage-Specific Logic + +| Stage | Main uncertainty | Minimum useful proof | +|---|---|---| +| Idea | Is the problem real and specific? | Named actor, situation, frequency, consequence, workaround. | +| Prototype | What behavior should be tested? | One riskiest claim, one focused test, one stop condition. | +| Launch | Is there enough pull and reliability? | Repeated behavior, adoption path, recovery path, bounded support cost. | +| Scale | Can this compound safely? | Retention, unit cost, governance, distribution, defensibility. | + +Stage raises the proof bar. It never upgrades weak evidence by itself. +Reversibility lowers mode, not the review requirement. + +## Claim Analysis + +Break attractive directions into user, evidence, business, risk, and taste +claims. Add dependencies so the council can see which false claim collapses the +rest. + +Use docs/CLAIMS.md and schemas/claim.schema.json. + +## Council Logic + +The three lane reviewers work independently before seeing one another's +conclusions. After the synchronization barrier, each reviewer must challenge +one material claim or state that no objection remains and show the +counter-evidence search performed. + +The facilitator then applies the weakest flow rule: + +| Lane state | Final action | +|---|---| +| Any lane stop_reframe, for any reason | Stop and rewrite the product question. | +| At least one verify and no stop_reframe | Run one proof step for the weakest flow. | +| All continue | Create a bounded context pack. | + +The weakest flow is the lane with the most severe verdict +(stop_reframe > verify > continue); ties break to the lowest lane +evidence_tier, then to the fixed priority evidence, user, business. + +Do not average reviewers. Do not trade away safety or actor clarity because +another lane looks strong. + +verify authorizes only the exact proof_step and never general coding. +continue plus a valid context pack authorizes implementation. `stop_reframe` +authorizes no execution work. Each branch must preserve `may_do`, +`must_not_do`, and `must_ask`. + +## Human In The Loop + +Humans do not approve every detail. They own decisions that cannot be delegated +without losing accountability. + +| Decision | Human responsibility | +|---|---| +| Taste | Choose coherence, restraint, dignity, and timing. | +| Risk | Choose acceptable exposure and recovery obligations. | +| Strategy | Decide whether a locally valid move fits the company direction. | +| Ethics | Decide whether a useful system should exist or act. | +| Meaning | Decide what value the product should stand for. | + +Record the decision with schemas/human-decision.schema.json. + +Post-build feedback enters the learning loop only after classification: +evidence, noise, incident, drift, or not_applicable. Classification records the +source, actor role, severity, repeatability, decision impact, and next action. + +## Output Rule + +All modes return schemas/review-result.schema.json. + +- continue creates a context pack +- verify creates one proof step +- stop_reframe creates a better product question diff --git a/skills/product-design-harness/resources/docs/ORCHESTRATION.md b/skills/product-design-harness/resources/docs/ORCHESTRATION.md new file mode 100644 index 000000000..8250b092d --- /dev/null +++ b/skills/product-design-harness/resources/docs/ORCHESTRATION.md @@ -0,0 +1,132 @@ +# Agent Orchestration + +Run a single-pass three-lane review for small reversible work. Run a council +when the direction needs external evidence, claim analysis, disagreement, or +human judgment. Every mode reviews all three lanes; modes differ in depth, +not in lane coverage. + +Before any review, load `schemas/session-config.schema.json`, +`knowledge/ontology.json`, triggered entries from `knowledge/rules.json`, and +`prompts/start-review.md` in that order. Use `working_language` for prose and +English canonical identifiers for schemas, Flow IDs, and rule IDs. + +## Mode Selection + +| Situation | Action | +|---|---| +| Small reversible change with bounded impact. | Quick Gate. | +| New feature, workflow, or experiment. | Standard Gate. | +| High uncertainty, high cost, low reversibility, or affected stakeholders. | UX3 Council. | +| Existing continue result with a valid context pack. | Handoff: reuse the context pack; no new review. | + +Reversibility lowers mode, not the review requirement. + +## Evidence Retrieval Contract + +External tools provide evidence, not verdicts. + +1. Send schemas/evidence-request.schema.json. +2. Retrieve only the evidence needed for named claims. +3. Require schemas/evidence-response.schema.json. +4. Reject receipts without provenance, freshness, counter-signal, or raw + artifact location. +5. Let the Evidence Flow Reviewer interpret decision impact. + +This contract applies to internal connectors, external search, product data, +documents, logs, tickets, and workflow traces. + +## Council Fork And Join + +1. Intake the product direction and identify stage. +2. Run Claim Analyst and create the claim dependency graph. +3. Retrieve missing evidence through the evidence contract. +4. Fork User, Evidence, and Business reviewers in parallel. +5. Wait for all three independent reviews. + +Two execution paths, either is compliant: + +- Parallel dispatch: if the runtime has a task or subagent tool, dispatch + the three lane reviewers concurrently. Assemble each reviewer's input as + the product brief plus claim analysis plus the relevant knowledge rules, + and collect each reviewer's output as one reviewer-verdict JSON object. +- Single-context rotation (fallback): one agent plays each reviewer in + sequence. Blind-round discipline still applies: write each lane's + complete reviewer-verdict JSON before reading the next lane's brief, + and never revise an earlier lane after seeing a later one. + +Unanimous-continue red flag: if all three independent lane reviews return +continue in a council-tier decision, treat agreement as a signal to probe, +not to relax. Run prompts/red-team.md before synthesis and attach its valid +schemas/red-team-review.schema.json output as council_input.red_team_review. +The output must name the challenged claims, evidence receipts, five failure +modes, disconfirming tests, and a stop condition. A red-team finding can require +verify without another independent vote: record the affected final lane as +verify, including the counter-case and missing proof, before reducing the final +lane verdicts. Keep the original independent and challenge receipts unchanged. +The combined verdict still equals the most severe final lane verdict; changing +only that headline is invalid. +6. Run one challenge round per lane. +7. Run Uncertainty Reviewer on evidence tier, risk, reversibility, and freshness. +8. Run Council Facilitator. +9. Route accountable decisions to Human Judgment Gate. +10. Create a context pack only after continue. + +The facilitator must not synthesize before the join barrier. + +Product organization, issuer, stakeholder effects, and accountable owner are +required before handoff. Taste remains human-owned and is recorded through +Human Judgment Gate, not scored by reviewers. + +## Challenge Round + +Each reviewer returns schemas/reviewer-verdict.schema.json with: + +- review_round set to challenge +- objection_to +- counter_evidence +- position_change + +No objection is acceptable only when the reviewer records the counter-evidence +search that failed to change the conclusion. + +## Idea Generation + +Idea generation creates alternatives, not execution. + +| Step | Rule | +|---|---| +| Generate | Produce directions that differ in user mechanism, evidence need, or business logic. | +| Separate | Reject cosmetic variants of the same direction. | +| Decompose | Run claim analysis for each viable direction. | +| Stress-test | Search for counter-signals and dependency failures. | +| Select | Choose the direction with the best confidence-to-cost ratio. | + +Semantic distance is a diagnostic, not a target score. Useful divergence means +the options would fail for different reasons. + +## Trade-Off Defaults + +| Trade-off | Protect by default | +|---|---| +| Speed vs confidence | Confidence when risk is high. | +| Automation vs control | Human override and accountability. | +| Growth vs trust | Trust. | +| Revenue vs access | Fairness and long-term value. | +| Novelty vs comprehension | User mental model. | +| Scope vs learning | The smallest proof step. | + +## Output Discipline + +The council returns one canonical result: + +- continue with a context pack +- verify with one proof step +- stop_reframe with a better product question + +Use schemas/review-result.schema.json. + +verify authorizes only the exact proof_step and never general coding. +continue plus a valid context pack authorizes implementation. +Every result must state `may_do`, `must_not_do`, and `must_ask`. +Post-build feedback is routed through ux3.rule.feedback_classification before +it changes scope, priority, or rules. diff --git a/skills/product-design-harness/resources/docs/PRINCIPLES.md b/skills/product-design-harness/resources/docs/PRINCIPLES.md new file mode 100644 index 000000000..7536db368 --- /dev/null +++ b/skills/product-design-harness/resources/docs/PRINCIPLES.md @@ -0,0 +1,112 @@ +# Principles + +## 1. Build The Right Thing Before Building It Right + +Execution quality does not rescue a bad direction. + +Before execution, name: + +- the user +- the problem +- the evidence +- the trade-off +- the risk +- the next smallest action + +## 2. A Feature Request Is Not A Problem + +Convert requests into problem hypotheses. + +| Request | Better hypothesis | +|---|---| +| Add dashboard export. | Analysts need weekly reports without manual screenshots. | +| Add chat. | New users cannot find the next action during setup. | +| Add automation. | Operators repeat a low-risk task often enough to justify delegation. | + +## 3. Proof Beats Polish + +A polished prototype is not validation. + +Use prototypes to observe behavior, not to impress stakeholders. + +## 4. Data Provides Evidence, Not Decisions + +Data becomes useful only when it changes a decision. + +Reject metrics that cannot change: + +- scope +- priority +- risk +- launch timing +- investment +- stop conditions + +## 5. Disconfirm First + +Every review must ask what would prove the direction wrong. + +If no failure condition exists, the work is not ready. + +## 6. Use The Least Power Needed + +For any product action: + +| Level | Meaning | +|---|---| +| Suggest | The system recommends. | +| Draft | The system prepares. | +| Preview | The human reviews. | +| Approve | The human authorizes. | +| Execute | The system acts. | +| Recover | The human can undo or repair. | + +Do not grant more power than the task requires. + +## 7. Cheap Features Still Carry Cost + +Every feature can add: + +- support burden +- user confusion +- trust risk +- measurement noise +- maintenance +- onboarding complexity +- opportunity cost + +Cheap to build is not cheap to own. + +## 8. Taste Is A Product Control + +Taste checks whether the product is coherent, restrained, trustworthy, and worth using. + +Taste is not subjective decoration. It is a quality control for decisions that metrics cannot fully resolve. + +## 9. Retention Comes From Depth + +Novelty fades. + +Durable products create depth through: + +- workflow fit +- saved context +- team process +- trust +- community +- domain expertise +- hard-won edge cases + +## 10. Every Failure Should Strengthen The Harness + +Do not only fix the case. + +Update: + +- a rule +- a prompt +- a template +- a schema +- a gate +- a stop condition +- an example diff --git a/skills/product-design-harness/resources/docs/README.md b/skills/product-design-harness/resources/docs/README.md new file mode 100644 index 000000000..3cc0a9619 --- /dev/null +++ b/skills/product-design-harness/resources/docs/README.md @@ -0,0 +1,19 @@ +# Docs + +| File | Purpose | +|---|---| +| `HARNESS.md` | Complete manual. | +| `UX3.md` | UX3 model, intersections, and the integrated center. | +| `OPERATING-PROTOCOL.md` | Six-gate operating system for staged product decisions. | +| `ORCHESTRATION.md` | MCP, connector, subagent, council, and debate workflow. | +| `UNCERTAINTY.md` | Confidence, proof bar, and uncertainty handling. | +| `CLAIMS.md` | Claim decomposition and dependency edges. | +| `CONTRACTS.md` | Canonical output contract and verdict branches. | +| `ANTI-PATTERNS.md` | Anti-gaming rules and review failure modes. | +| `GLOSSARY.md` | Shared vocabulary. | +| `ADOPTION.md` | Team adoption and anti-pattern guide. | +| `PRINCIPLES.md` | Stable decision principles. | +| `COUNCIL.md` | UX3 council process. | +| `CODING-HARNESS-COMPARISON.md` | Product Design Harness vs Coding Harness. | + +See `../assets/` for book-style diagrams used across the handbook. diff --git a/skills/product-design-harness/resources/docs/UNCERTAINTY.md b/skills/product-design-harness/resources/docs/UNCERTAINTY.md new file mode 100644 index 000000000..6f1b4202f --- /dev/null +++ b/skills/product-design-harness/resources/docs/UNCERTAINTY.md @@ -0,0 +1,87 @@ +# Uncertainty, Evidence Tiers, And Confidence + +Uncertainty is not a defect. Hidden uncertainty is. + +The harness uses two separate ideas: + +| Concept | Use | +|---|---| +| Evidence tier | Operational limit on what action is allowed. | +| Confidence level | Human-readable judgment about how much trust to place in the current interpretation. | + +Never average confidence labels. Never use confidence to upgrade weak evidence. + +## Evidence Tiers + +| Tier | Evidence pattern | Maximum default action | +|---|---|---| +| t0 | Internal belief, invented actor, generic trend, no traceable source. | Reframe the question. | +| t1 | Stated opinion, isolated quote, second-hand report, public signal. | Form a hypothesis or run discovery. | +| t2 | Contextual interview, observed workaround, support pattern, small test. | Run a focused reversible prototype. | +| t3 | Repeated behavior, adoption, payment, retention, product logs, recovery proof. | Launch or expand within a bounded scope. | +| t4 | Durable retention, workflow dependency, sustainable economics, governance proof. | Consider scale. | + +Subjective evidence matters. A quote or opinion can reveal language, motivation, +fear, and mental model. Its tier depends on context, repetition, and decision +relevance; it should not be mistaken for observed behavior. + +## Confidence Rubric + +| Level | Interpretation | +|---|---| +| Very low | The source, meaning, or actor is mostly unknown. | +| Low | A plausible signal exists but alternatives remain equally credible. | +| Medium | Multiple contextual signals agree and a focused next step is reversible. | +| High | Repeated direct evidence supports the claim and counter-signals are bounded. | +| Very high | Durable evidence survives time, segments, failure cases, and operating reality. | + +## Risk Classes + +| Class | Typical effect | +|---|---| +| R1 | Reversible, low cost, no meaningful user harm. | +| R2 | Recoverable user or business impact with bounded cost. | +| R3 | Brand, legal, financial, vulnerable-user, or partially irreversible impact. | +| R4 | Safety-critical, rights-affecting, or irreversible external action. | + +## Decision Matrix + +| Evidence tier | R1 reversible | R2 bounded | R3 high impact | R4 irreversible | +|---|---|---|---|---| +| t0 | stop_reframe | stop_reframe | stop_reframe | stop_reframe | +| t1 | verify | verify | stop_reframe | stop_reframe | +| t2 | continue narrowly | verify | verify + human gate | stop_reframe | +| t3 | continue | continue narrowly | verify + human gate | human gate | +| t4 | continue | continue | continue + human gate | human gate | + +"Continue narrowly" means the execution boundary must preserve reversibility. +The matrix is a default. Human judgment may raise the bar but cannot erase +missing provenance, actor clarity, or safety constraints. + +## Freshness And Decay + +Evidence expires when the market, workflow, population, policy, or product has +changed enough to alter interpretation. + +Every evidence receipt records: + +- when it was collected +- when the source was last verified +- maximum staleness in days +- the raw artifact location +- a counter-signal + +Expired evidence is not deleted. It is downgraded until re-verified. + +## Confidence-To-Cost Rule + +Choose the smallest action that creates the largest decision-relevant increase +in evidence tier for the least cost and risk. + +Before handoff, ask: + +- What is known? +- What is assumed? +- What evidence has expired? +- What would change the verdict? +- What decision must stay human-owned? diff --git a/skills/product-design-harness/resources/docs/UX3.md b/skills/product-design-harness/resources/docs/UX3.md new file mode 100644 index 000000000..70bbb2b6e --- /dev/null +++ b/skills/product-design-harness/resources/docs/UX3.md @@ -0,0 +1,162 @@ +# UX3 Model + +UX3 is the product decision model behind Product Design Harness. Its canonical +machine kernel is `knowledge/ontology.json` and `knowledge/rules.json`; this +document is the human-readable projection. + +The original UX3 curriculum is the knowledge source, not a file to copy into +the kernel. It teaches methods, examples, professional judgment, and the +reasoning behind the model. A decision rule distills only the part an agent can +apply as an observable trigger, evidence requirement, counter-signal, human +boundary, stop condition, and bounded output. Chapter-level sources remain in +`knowledge/rules.json` so the projection is traceable without pretending that +one rule represents a whole chapter. + +![UX3 model](../assets/ux3-model.svg) + +It has three connected dimensions: + +| Dimension | Question | +|---|---| +| User Flow | Who is the target population, who is affected, and under what conditions should the product create an outcome? | +| Evidence Flow | What source, signal, interpretation, counter-signal, and decision impact support the next step? | +| Business Flow | Who creates value, receives value, pays, decides, operates, or absorbs risk? | + +The center is not a fourth flow and not a score. It is the UX3 Decision +Kernel: a deterministic reduction process that turns three lane reviews into +one canonical verdict and execution boundary. + +## User Flow + +User Flow identifies the future target population for the product and the +conditions under which the product should create an outcome. + +It includes: + +- primary users; +- secondary users; +- machine or agent operators; +- beneficiaries who do not operate the product; +- people affected by a product decision; +- excluded or underserved groups. + +The reviewer determines who the product is for, what those actors are trying +to accomplish, what they currently do, and what cost, friction, risk, or loss +of control they experience. A simulated walkthrough can expose assumptions, +but it is not validation until compared with quotes, observed behavior, logs, +and business consequence. + +## Evidence Flow + +Evidence Flow is the product's sensing, learning, and calibration system. It +helps machines and humans understand why a decision is justified and what must +be learned next. + +Evidence can be internal, external, behavioral, subjective, or evaluative. +Evidence informs decisions; taste and judgment are separately recorded as a +human decision input. + +| Source | Examples | Risk | +|---|---|---| +| Internal evidence | Usage logs, support tickets, retention, sales notes, search queries, interviews. | Can overfit to current customers. | +| External evidence | Market reports, public reviews, competitor behavior, community posts, benchmark data. | Can be generic or detached from the product. | +| Direct learning | Prototype test, workflow observation, willingness test, concierge test. | Can be small but highly relevant. | + +Evidence Flow keeps these layers separate: + +| Layer | Meaning | +|---|---| +| Source | Where the signal came from. | +| Signal | What was observed. | +| Interpretation | What the reviewer thinks it means. | +| Counter-signal | What weakens or contradicts the interpretation. | +| Decision impact | What changes because of it. | + +Human taste and judgment are separately recorded as accountable input when a +decision depends on ethics, meaning, strategy, risk appetite, brand feel, or +final responsibility. They are not an evidence source and are not converted +into an evidence score. + +## Business Flow + +Business Flow represents the company, project owner, issuer, or organization +that creates, distributes, and remains accountable for the product. + +It also includes customers and buyers, employees and operators, partners and +channels, investors and funders, platforms and infrastructure providers, +regulators, and communities or groups that absorb product externalities. + +Business Flow asks who creates value, who receives value, who pays, who bears +cost and risk, who has decision authority, and whether the exchange can remain +viable and legitimate. It should infer the model from user value, workflow fit, +and evidence rather than starting from monetization mechanics. + +## Intersections + +UX3 is strongest at the intersections. + +![UX3 intersections](../assets/intersections.svg) + +### User Flow + Evidence Flow = Situated Understanding + +Situated Understanding asks: + +| Question | Meaning | +|---|---| +| What did users say or feel? | Subjective opinion is useful when its context and intensity are captured. | +| What did users actually do? | Behavior shows whether the opinion changes action. | +| What workaround already exists? | Workarounds reveal urgency and cost. | +| What interaction did the reviewer simulate? | Simulation exposes assumptions. | +| What still needs stronger evidence? | Quotes, behavior, logs, and payment signals must not be mixed into one undifferentiated claim. | + +### Evidence Flow + Business Flow = Viable Learning + +Viable Learning asks: + +| Question | Meaning | +|---|---| +| What signal supports value? | Evidence must connect to business consequence. | +| What cost is hidden? | Build cost is not ownership cost. | +| What signal predicts retention? | Adoption is not enough. | +| What would make the model fail? | Business assumptions need failure criteria. | + +### User Flow + Business Flow = Sustainable Value Exchange + +Sustainable Value Exchange asks: + +| Question | Meaning | +|---|---| +| What does the user gain? | The product must create clear value. | +| What does the user give up? | Time, money, data, attention, trust, workflow change. | +| What does the business capture? | Revenue, retention, distribution, trust, or depth. | +| Is the exchange fair? | Growth that damages trust is not durable. | + +### UX3 Decision Kernel + +The kernel does not average lane scores or invent a fourth opinion. It applies +the same four operations to every submitted review: + +| Step | Operation | Result | +|---|---|---| +| Validate | Reject malformed contracts, missing evidence references, and contradictory fields. | Three valid lane verdicts. | +| Reduce | Select the worst verdict; break ties by evidence tier, then fixed lane priority: evidence, then user, then business. This is the order enforced by `scripts/check_review.py`. | One weakest flow. | +| Gate | Compare uncertainty, risk, and reversibility. Route taste, strategy, ethics, meaning, and risk appetite to the Human Judgment Gate. | A bounded proof step or accountable human decision. | +| Emit | Produce `schemas/review-result.schema.json`. | Verdict, next action, execution boundary, and stop conditions. | + +The output is `continue`, `verify`, or `stop_reframe`. The weakest flow +controls the next action. A named-person decision may raise the proof bar or +reverse a recommendation only through an accountable decision record with +reversal conditions. + +## Learning Loop + +Every product decision should preserve this chain: + +```text +signal -> interpretation -> counter-signal -> decision impact + -> human judgment -> bounded action -> observed outcome + -> evidence update or rule update +``` + +Signals do not decide by themselves. Human taste does not become a data score. +The next action is bounded by evidence, risk, reversibility, and accountability. diff --git a/skills/product-design-harness/resources/docs/rfcs/0001-override-protocol.md b/skills/product-design-harness/resources/docs/rfcs/0001-override-protocol.md new file mode 100644 index 000000000..df94f87b2 --- /dev/null +++ b/skills/product-design-harness/resources/docs/rfcs/0001-override-protocol.md @@ -0,0 +1,155 @@ +# RFC 0001: The Override Protocol + +- Status: Proposal (no schema or contract changes yet) +- Scope: how the weakest-flow rule survives the moment it blocks a + pet feature +- Follow-up: implementation tracked in the checklist at the end + +## The Problem + +Community feedback on the harness, paraphrased: + +> "Weakest flow decides" with no averaging is a bold constraint, +> because most teams will fight that the second it blocks a pet +> feature. + +The critique is correct, and it is not about the logic of the rule. +It is about organizational survival. Every hard governance mechanism +(lint gates, review gates, launch checklists) faces the same moment: +the rule is most valuable exactly when it is least popular. If the +only two outcomes at that moment are "the rule blocks the feature" +or "the team disables the rule", the rule eventually loses, because +the second outcome is silent and permanent. + +Today the harness has one sentence of defense: a human may override +a recommendation only through `schemas/human-decision.schema.json`, +and an unlogged override does not exist (`docs/CONTRACTS.md`, +`agents/council-facilitator.md`). That is the right instinct, but it +is underspecified in five ways: + +1. There is no dedicated override record. `human-decision` covers + human-owned decision types (taste, risk, strategy, ethics, + meaning). Overriding a `stop_reframe` verdict to build anyway is + a different act with different required fields, and forcing it + through `decision_type` blurs both records. +2. An override can silently rewrite history. Nothing prevents a team + from treating an overridden review as if it had returned + `continue`, which corrupts every downstream artifact that reads + the verdict. +3. Overrides are permanent by default. `reversal_conditions` exist + but nothing checks them, so an override taken under deadline + pressure quietly becomes policy. +4. Overrides are invisible in aggregate. One override is judgment; + ten active overrides are a broken review culture. Nothing counts + them. +5. Nothing is machine-enforced. All of the above lives in prose, and + this harness's own stated standard is that prose guarantees are + not guarantees. + +## Design Position + +The harness should not try to win the fight against the pet feature. +A judgment layer that can only say "no" gets uninstalled. The design +goal is different: + +**The verdict is never negotiable. Execution is.** + +A human with authority may always ship the pet feature. What they +may never do is make the harness pretend it agreed. The override +protocol converts "fight the rule" into "sign your name", which is a +fight most pet features lose on their own. + +## Proposed Mechanics + +### 1. A dedicated verdict-override record + +New contract: schemas/verdict-override.schema.json. Required +fields (draft): + +| Field | Meaning | +|---|---| +| `override_id` | Stable identifier, referenced by later reviews. | +| `review_id` | The review-result being overridden. | +| `overridden_verdict` | Must equal the review's `combined_verdict`. | +| `acknowledged_weakest_flow` | Must equal the review's `weakest_flow`; the owner restates the gap they are accepting. | +| `authorized_scope` | Execution scope granted despite the verdict; same shape as `execution_boundary`. | +| `accountable_owner` | A named person, not a team. | +| `rationale` | Why shipping anyway is the right call. | +| `expires_at` | Every override is time-boxed. No permanent overrides. | +| `tripwires` | Measurable conditions; any one tripping voids the override immediately. | +| `renewal_requires` | What evidence a renewal review must present. Renewal is a new review, never an edit. | + +### 2. The verdict is immutable + +An override never modifies the review-result. The review stays +`stop_reframe` in the record; the override is a separate artifact +that authorizes execution despite it. Machine check: any document +that references an overridden review must carry the `override_id`, +and no tool may report the review's verdict as anything other than +what the reviewers returned. The history stays honest even when the +decision does not follow it. + +### 3. Overrides expire; reviews do not + +`expires_at` is required. When an override lapses, the original +verdict is in force again, and continuing execution requires either +a renewal (a fresh review that must address `renewal_requires`) or a +new override record with a new rationale. Deadline-pressure +decisions therefore decay back to the evidence by default, instead +of hardening into policy. + +### 4. The override ledger + +New template: templates/override-ledger.md. One row per active +override: owner, overridden verdict, expiry, tripwire status. Two +uses: + +- Any new review of a direction with an active override must list + that override in its inputs (the reviewers see what was accepted + and why). +- The count of active overrides is itself a review input. A + threshold (proposed: three active overrides on one product area) + is a mandatory `verify` on the next review of that area, with the + ledger as the cited evidence. + +### 5. Machine enforcement plan + +In keeping with the repo standard that every guarantee is either +machine-checked or explicitly listed as not enforced: + +- scripts/check_override.py: validates the record, checks + `overridden_verdict` and `acknowledged_weakest_flow` against the + referenced review file, rejects expired records, rejects + `authorized_scope` entries that appear in the review's + `must_not_do`. +- Golden example: examples/verdict-override.json plus a walkthrough + showing a `stop_reframe` review, the override, and the follow-up + review that cites it. +- Docs: a short "When the harness blocks your pet feature" section + in `docs/HARNESS.md`, written for the person who is angry at the + gate, explaining that the exit exists and what it costs. + +## What This Does Not Do + +- It does not make the harness able to stop a determined owner. + Nothing can, and claiming otherwise would violate the repo's + honesty rules. +- It does not soften the weakest-flow rule. Averaging remains + banned; the verdict computation is untouched. +- It does not add an approval hierarchy. One named owner and one + signed record is the entire ceremony. + +## Implementation Checklist (follow-up PRs) + +- [ ] schemas/verdict-override.schema.json with the fields above +- [ ] scripts/check_override.py plus CI wiring +- [ ] examples/verdict-override.json golden pair (record plus + walkthrough) +- [ ] templates/override-ledger.md +- [ ] `docs/HARNESS.md` section: when the harness blocks your pet + feature +- [ ] Cross-references from `docs/CONTRACTS.md` and + `agents/council-facilitator.md` replacing the current + prose-only override sentences +- [ ] Tests: override record round-trip, expiry rejection, scope + conflict rejection, ledger-threshold review input diff --git a/skills/product-design-harness/resources/examples/README.md b/skills/product-design-harness/resources/examples/README.md new file mode 100644 index 000000000..ea4d6ae06 --- /dev/null +++ b/skills/product-design-harness/resources/examples/README.md @@ -0,0 +1,22 @@ +# Examples + +| File | Purpose | +|---|---| +| `quick-gate-review.md` | Small reversible change. | +| `quick-gate-review.json` | Machine-checkable Quick Gate result. | +| `quick-context-pack.json` | Machine-checkable handoff for the Quick Gate continue result. | +| `live-coding-product-brief.json` | Product brief for a complete live-coding brief -> review -> context-pack chain. | +| `live-coding-review.json` | Machine-checkable live-coding review with a legitimate `continue` verdict. | +| `live-coding-context-pack.json` | Machine-checkable live-coding implementation handoff for the approved bounded change. | +| `stop-reframe-review.md` | Human-readable stop_reframe walkthrough. | +| `stop-reframe-review.json` | Machine-checkable stop_reframe result: t0 evidence forces the stop. | +| `ux3-council-input.json` | Machine-checkable council input: claim graph, blind first-round verdicts, challenge round, uncertainty review. | +| `red-team-review.json` | Structured counter-case attached when every independent Council lane continues. | +| `feature-gate-review.md` | End-to-end example of a vague feature request becoming a gate review and handoff. | +| `standard-gate-review.json` | Machine-checkable Standard Gate result. | +| `ux3-council-review.md` | Extended UX3 council review. | +| `ux3-council-review.json` | Machine-checkable Council result. | +| `human-decision.json` | Accountable decision record used by the Council example. | +| `verdict-override.json` | Signed override of the stop_reframe example; validated by check_override. | +| `verdict-override.md` | Human-readable override walkthrough. | +| `evidence-response.json` | Evidence receipts with provenance and freshness. | diff --git a/skills/product-design-harness/resources/examples/evidence-response.json b/skills/product-design-harness/resources/examples/evidence-response.json new file mode 100644 index 000000000..0f50660bb --- /dev/null +++ b/skills/product-design-harness/resources/examples/evidence-response.json @@ -0,0 +1,42 @@ +{ + "request_id": "evidence-request-quick-001", + "source_connector": "internal-product-sources", + "retrieved_at": "2026-07-10T10:00:00Z", + "receipts": [ + { + "evidence_id": "support-pattern-001", + "source_id": "support-system", + "source_type": "internal", + "raw_artifact_uri": "evidence://support/setup-empty-state", + "signal_type": "quote", + "signal": "People repeatedly ask what to do after reaching the empty state.", + "interpretation": "The next action is not clear enough.", + "decision_impact": "Supports a reversible copy test.", + "evidence_tier": "t2", + "confidence_level": "medium", + "counter_signal": "Some questions may come from missing setup prerequisites rather than copy.", + "collected_at": "2026-07-08T09:00:00Z", + "source_last_verified_at": "2026-07-10T09:30:00Z", + "max_staleness_days": 30 + }, + { + "evidence_id": "session-replay-pattern-001", + "source_id": "session-replay-system", + "source_type": "internal", + "raw_artifact_uri": "evidence://replays/setup-empty-state", + "signal_type": "observed_behavior", + "signal": "Several new users pause before selecting the first setup action.", + "interpretation": "The action hierarchy or language may be unclear.", + "decision_impact": "Supports measuring first-action completion after a copy change.", + "evidence_tier": "t2", + "confidence_level": "medium", + "counter_signal": "The replay sample may overrepresent unsuccessful sessions.", + "collected_at": "2026-07-09T08:00:00Z", + "source_last_verified_at": "2026-07-10T09:30:00Z", + "max_staleness_days": 14 + } + ], + "coverage_gaps": [ + "No segmented completion baseline is available." + ] +} diff --git a/skills/product-design-harness/resources/examples/feature-gate-review.md b/skills/product-design-harness/resources/examples/feature-gate-review.md new file mode 100644 index 000000000..5fcf0e732 --- /dev/null +++ b/skills/product-design-harness/resources/examples/feature-gate-review.md @@ -0,0 +1,87 @@ +# Example: Feature Gate Review + +## Product Brief + +| Field | Answer | +|---|---| +| Product direction | Add automated weekly report export for team managers. | +| Stage | Prototype | +| Claimed user | Team manager. | +| Current evidence | Support team reports that managers ask for weekly summaries. No behavior data yet. | +| Proposed next step | Build the export feature. | + +## User Flow Review + +| Field | Answer | +|---|---| +| Verdict | Verify | +| Strongest user signal | Support reports mention repeated requests for weekly summaries. | +| Weakest user assumption | Managers need export, not just better in-product visibility. | +| Affected people | Team members whose activity may appear in the report. | +| Excluded groups | Managers who do not use spreadsheet workflows. | +| Disconfirming evidence | Managers only need occasional screenshots or dashboards; exports are for one large account only. | +| Stop condition | Stop if the request is not repeated across accounts or if reports expose sensitive data without review. | +| Next smallest action | Interview five managers using their current weekly reporting workflow. | + +## Evidence Flow Review + +| Field | Answer | +|---|---| +| Verdict | Verify | +| Evidence tier | t2 | +| Strongest evidence | Support requests are real, but not yet tied to frequency or value. | +| Weakest evidence assumption | Support volume represents broad demand. | +| Missing measurement | Number of accounts requesting reports, current workaround time, weekly recurrence. | +| Failure criteria | Fewer than 3 of 5 managers currently create weekly reports manually. | +| Trace requirement | Record source account, current workaround, time cost, and requested format. | +| Next smallest action | Count requests and observe one current manual reporting workflow. | + +## Business Flow Review + +| Field | Answer | +|---|---| +| Verdict | Verify | +| Strongest business signal | Reporting may improve account retention for manager-heavy teams. | +| Weakest business assumption | Export feature creates retention rather than support burden. | +| Cost risks | Permission rules, data privacy, support for formats, scheduled delivery, data correctness. | +| Retention logic | Managers may return weekly if reports become part of team rituals. | +| Defensibility | Weak unless report templates reflect domain-specific management insight. | +| Disconfirming evidence | Users export once, then churn; exports create compliance concerns; dashboard improvements solve the issue. | +| Next smallest action | Test one static report sample before building scheduled export. | + +## Council Decision + +| Field | Answer | +|---|---| +| Combined verdict | Verify | +| Weakest flow | Evidence | +| Main conflict | Support requests suggest need, but the requested solution may be wrong. | +| Human-owned decision | Risk | +| Trade-off | Delay automation to protect data correctness and learn the actual reporting job. | +| Execution boundary | Do not build scheduled export yet. Create a static report mock and test workflow fit. | +| Next smallest action | Run five workflow interviews and one static report test. | + +This is a `verify` result. The allowed work is the proof step, not a context +pack or implementation handoff. + +## Handoff Boundary + +Execution may create: + +- one static report sample +- interview guide +- evidence table + +Execution must not create: + +- scheduled export +- live customer data access +- permission model changes +- external delivery + +## Stop Conditions + +- Report need is not repeated across accounts. +- Users cannot name a weekly decision the report supports. +- Data sensitivity requires permissions not yet designed. +- Dashboard changes solve the problem with less cost. diff --git a/skills/product-design-harness/resources/examples/human-decision.json b/skills/product-design-harness/resources/examples/human-decision.json new file mode 100644 index 000000000..608c24589 --- /dev/null +++ b/skills/product-design-harness/resources/examples/human-decision.json @@ -0,0 +1,18 @@ +{ + "decision_id": "decision-example-001", + "review_id": "example-council-001", + "decision_type": "risk", + "decision": "Keep human approval for customer-facing workflow actions.", + "options_considered": [ + "Full autonomous execution.", + "Draft-only assistance with approval.", + "No workflow assistance." + ], + "rationale": "Current t1 evidence cannot support irreversible customer-facing action.", + "accountable_owner": "Product owner", + "decided_at": "2026-07-10T12:00:00Z", + "reversal_conditions": [ + "Observed error and recovery evidence reaches t3.", + "The accountable owner approves a new bounded execution policy." + ] +} diff --git a/skills/product-design-harness/resources/examples/live-coding-context-pack.json b/skills/product-design-harness/resources/examples/live-coding-context-pack.json new file mode 100644 index 000000000..174b643f6 --- /dev/null +++ b/skills/product-design-harness/resources/examples/live-coding-context-pack.json @@ -0,0 +1,103 @@ +{ + "schema_version": "2.1", + "session_config": { + "working_language": "en", + "canonical_identifiers": "en", + "fallback_language": "en" + }, + "review_id": "live-coding-review-001", + "goal": "Add one visible save-state label to the existing note editor header so editors know whether they can leave safely.", + "stage": "prototype", + "combined_verdict": "continue", + "actor_boundary": { + "target_population": [ + "Workspace editors drafting internal notes" + ], + "operator": "Workspace editor", + "beneficiary": "Workspace editor", + "machine_actor": "Repository-aware coding agent", + "affected_people": [ + "Workspace editors", + "Support team" + ], + "excluded_groups": [ + "External collaborators", + "Public note viewers" + ] + }, + "product_organization": { + "organization": "Example Notes Co.", + "project_owner": "Editor experience team", + "issuer": "Example Notes Co." + }, + "stakeholder_effects": [ + { + "stakeholder": "Workspace editors", + "effect": "They get clearer save-state feedback before leaving the editor." + }, + { + "stakeholder": "Support team", + "effect": "They may receive fewer avoidable questions about whether notes were saved." + } + ], + "human_judgment_boundary": { + "human_owned_decisions": [], + "machine_supported_inputs": [ + "Support ticket pattern", + "Session replay observation" + ], + "not_mechanized": [], + "approval_gates": [] + }, + "unresolved_assumptions": [ + "The confusion comes from unclear save-state feedback rather than a real save failure.", + "A header label is noticeable enough without changing the editor workflow." + ], + "scope": [ + "Add one visible save-state label to the existing note editor header.", + "Use the current save state already available to the editor UI.", + "Add or preserve a measurement hook that can compare exit hesitation and save-state support-tag volume." + ], + "non_goals": [ + "Do not change save persistence.", + "Do not change permissions.", + "Do not add notifications, external delivery, or background jobs.", + "Do not redesign the editor header beyond the save-state label." + ], + "acceptance_criteria": [ + "The label is visible in the editor header while a note is being edited.", + "The label wording does not imply guarantees beyond existing save behavior.", + "Existing save behavior, permissions, and external actions remain unchanged.", + "The change can be reversed by removing the label and measurement hook." + ], + "measurement_hooks": [ + "Compare editor close hesitation before and after the label.", + "Track support conversations tagged editor-save-state for the next review.", + "Classify post-build feedback as behavior, quote, support pattern, counter-signal, or scope-change trigger." + ], + "evidence_snapshot_ids": [ + "lc-support-save-state-001", + "lc-replay-exit-hesitation-001" + ], + "rollback_plan": "Remove the save-state label and any label-specific measurement hook; keep the existing editor save behavior unchanged.", + "human_approval_gates": [], + "high_risk_actions": [], + "stop_conditions": [ + "The implementation requires persistence, permission, notification, or external delivery changes.", + "A new stakeholder group is affected by the label.", + "The label implies a stronger save guarantee than the product can support." + ], + "execution_boundary": { + "may_do": [ + "Add one visible save-state label to the existing note editor header.", + "Use the current save state already available to the editor UI.", + "Add or preserve a measurement hook that can compare exit hesitation and save-state support-tag volume." + ], + "must_not_do": [ + "expand scope or execute external irreversible actions" + ], + "must_ask": [ + "new stakeholder, data, risk, or scope appears" + ] + } +} diff --git a/skills/product-design-harness/resources/examples/live-coding-product-brief.json b/skills/product-design-harness/resources/examples/live-coding-product-brief.json new file mode 100644 index 000000000..e8aace270 --- /dev/null +++ b/skills/product-design-harness/resources/examples/live-coding-product-brief.json @@ -0,0 +1,130 @@ +{ + "schema_version": "2.1", + "session_config": { + "working_language": "en", + "canonical_identifiers": "en", + "fallback_language": "en" + }, + "product_direction": "Add a visible save-state label to the note editor header.", + "accountable_owner": "Product owner", + "stage": "prototype", + "actor_boundary": { + "target_population": [ + "Workspace editors drafting internal notes" + ], + "operator": "Workspace editor", + "beneficiary": "Workspace editor", + "machine_actor": "Repository-aware coding agent", + "affected_people": [ + "Workspace editors", + "Support team" + ], + "excluded_groups": [ + "External collaborators", + "Public note viewers" + ] + }, + "business_boundary": { + "product_organization": "Example Notes Co.", + "project_owner": "Editor experience team", + "issuer": "Example Notes Co.", + "customers": [ + "Team workspace customers" + ], + "buyers": [ + "Workspace admins" + ], + "operators": [ + "Workspace editors" + ], + "partners": [ + "Not applicable" + ], + "funders": [ + "Not applicable" + ], + "platforms": [ + "Web app" + ], + "regulators": [ + "Not applicable" + ], + "externality_bearers": [ + "Support team" + ], + "decision_authority": "Product owner", + "value_exchange": "Editors get clearer save-state feedback while the product may reduce avoidable support questions." + }, + "human_judgment_boundary": { + "human_owned_decisions": [], + "machine_supported_inputs": [ + "Support ticket pattern", + "Session replay observation" + ], + "not_mechanized": [], + "approval_gates": [] + }, + "unresolved_assumptions": [ + "The confusion comes from unclear save-state feedback rather than a real save failure.", + "A header label is noticeable enough without changing the editor workflow." + ], + "execution_boundary": { + "may_do": [ + "Add one visible save-state label to the existing note editor header.", + "Use the current save state already available to the editor UI.", + "Add or preserve a measurement hook that can compare exit hesitation and save-state support-tag volume." + ], + "must_not_do": [ + "expand scope or execute external irreversible actions" + ], + "must_ask": [ + "new stakeholder, data, risk, or scope appears" + ] + }, + "problem_hypothesis": "Workspace editors hesitate before leaving the note editor because they cannot tell whether the current draft has been saved.", + "current_evidence": [ + { + "evidence_id": "lc-support-save-state-001", + "source_id": "support-tag-editor-save-state-2026-07", + "source_type": "internal", + "raw_artifact_uri": "internal://support/tags/editor-save-state/2026-07", + "signal_type": "quote", + "signal": "Six support conversations in two weeks ask whether note edits were saved before closing the editor.", + "interpretation": "The uncertainty is visible enough to generate support contact.", + "decision_impact": "Supports a small reversible clarity change before deeper editor work.", + "evidence_tier": "t2", + "confidence_level": "medium", + "counter_signal": "The tickets do not prove data loss or quantify all editor sessions.", + "collected_at": "2026-07-09T12:00:00Z", + "source_last_verified_at": "2026-07-09T12:00:00Z", + "max_staleness_days": 30 + }, + { + "evidence_id": "lc-replay-exit-hesitation-001", + "source_id": "session-replay-note-editor-exit-2026-07", + "source_type": "workflow", + "raw_artifact_uri": "internal://replay/note-editor-exit-hesitation/2026-07", + "signal_type": "observed_behavior", + "signal": "Four of eight sampled editors pause near the close control after typing and before leaving the editor.", + "interpretation": "The hesitation aligns with the support pattern but is not yet a measured completion metric.", + "decision_impact": "Supports adding one visible save-state label and measuring whether exit hesitation falls.", + "evidence_tier": "t2", + "confidence_level": "medium", + "counter_signal": "The sample is small and may overrepresent uncertain sessions.", + "collected_at": "2026-07-09T13:00:00Z", + "source_last_verified_at": "2026-07-09T13:00:00Z", + "max_staleness_days": 30 + } + ], + "business_goal": "Reduce avoidable save-state confusion without changing the editor workflow.", + "constraints": [ + "Keep the change to the existing editor header.", + "Do not change persistence, permissions, notifications, or external delivery.", + "Preserve existing save behavior and rollback by removing the label." + ], + "proposed_next_step": "Run review live-coding-review-001 and, only on continue, hand off a context pack for the bounded label change.", + "known_risks": [ + "The label could be missed if it is too subtle.", + "The label could imply stronger save guarantees than the product currently provides." + ] +} diff --git a/skills/product-design-harness/resources/examples/live-coding-review.json b/skills/product-design-harness/resources/examples/live-coding-review.json new file mode 100644 index 000000000..6158b8cbc --- /dev/null +++ b/skills/product-design-harness/resources/examples/live-coding-review.json @@ -0,0 +1,121 @@ +{ + "schema_version": "2.1", + "session_config": { + "working_language": "en", + "canonical_identifiers": "en", + "fallback_language": "en" + }, + "review_id": "live-coding-review-001", + "product_direction": "Add a visible save-state label to the note editor header.", + "mode": "quick_gate", + "stage": "prototype", + "actor_boundary": { + "target_population": [ + "Workspace editors drafting internal notes" + ], + "operator": "Workspace editor", + "beneficiary": "Workspace editor", + "machine_actor": "Repository-aware coding agent", + "affected_people": [ + "Workspace editors", + "Support team" + ], + "excluded_groups": [ + "External collaborators", + "Public note viewers" + ] + }, + "product_organization": { + "organization": "Example Notes Co.", + "project_owner": "Editor experience team", + "issuer": "Example Notes Co." + }, + "stakeholder_effects": [ + { + "stakeholder": "Workspace editors", + "effect": "They get clearer save-state feedback before leaving the editor." + }, + { + "stakeholder": "Support team", + "effect": "They may receive fewer avoidable questions about whether notes were saved." + } + ], + "human_judgment_boundary": { + "human_owned_decisions": [], + "machine_supported_inputs": [ + "Support ticket pattern", + "Session replay observation" + ], + "not_mechanized": [], + "approval_gates": [] + }, + "unresolved_assumptions": [ + "The confusion comes from unclear save-state feedback rather than a real save failure.", + "A header label is noticeable enough without changing the editor workflow." + ], + "combined_verdict": "continue", + "weakest_flow": "evidence", + "strongest_signal": "Support tickets and replay observations both show editors hesitating around save-state confidence.", + "riskiest_claim": "One visible header label will reduce save-state confusion without implying a stronger persistence guarantee.", + "main_uncertainty": "Whether the label is noticeable enough to change behavior without overstating save guarantees.", + "confidence_level": "medium", + "evidence_tier": "t2", + "main_trade_off": "Ship a small reversible clarity improvement now while staying inside existing editor patterns and avoiding deeper workflow or persistence changes.", + "human_owned_decision": "none", + "human_decision_record_id": null, + "evidence_receipt_ids": [ + "lc-support-save-state-001", + "lc-replay-exit-hesitation-001" + ], + "reviews": { + "user": { + "verdict": "continue", + "strongest_signal": "Editors ask whether edits are saved and pause before leaving the editor.", + "weakest_assumption": "The visible label addresses the actual moment of uncertainty.", + "missing_evidence": "Post-change hesitation and support-contact rate.", + "disconfirming_evidence": "Editors still pause or ask the same question after the label ships.", + "stop_condition": "A five-person comprehension check shows the label is misunderstood.", + "evidence_tier": "t2" + }, + "evidence": { + "verdict": "continue", + "strongest_signal": "Two independent internal sources point to the same save-state uncertainty.", + "weakest_assumption": "The sampled sessions represent normal editor behavior.", + "missing_evidence": "A measured event for hesitation before leaving the editor.", + "disconfirming_evidence": "Instrumented sessions show no change in exit hesitation after the label.", + "stop_condition": "No measurement hook can distinguish label impact from normal editor use.", + "evidence_tier": "t2" + }, + "business": { + "verdict": "continue", + "strongest_signal": "The change is low cost, reversible, and aligned with support reduction.", + "weakest_assumption": "Reducing save-state confusion is worth editor header attention.", + "missing_evidence": "Longer-term effect on support volume and editor trust.", + "disconfirming_evidence": "The label adds visual noise without reducing support contact or hesitation.", + "stop_condition": "The change requires persistence, permission, notification, or external delivery work.", + "evidence_tier": "t2" + } + }, + "next_smallest_action": "Implement one save-state label in the editor header, keep current save behavior unchanged, and measure exit hesitation plus support-tag volume.", + "execution_boundary": { + "may_do": [ + "Add one visible save-state label to the existing note editor header.", + "Use the current save state already available to the editor UI.", + "Add or preserve a measurement hook that can compare exit hesitation and save-state support-tag volume." + ], + "must_not_do": [ + "expand scope or execute external irreversible actions" + ], + "must_ask": [ + "new stakeholder, data, risk, or scope appears" + ] + }, + "human_approval_gates": [], + "high_risk_actions": [], + "stop_conditions": [ + "The implementation requires persistence, permission, notification, or external delivery changes.", + "A new stakeholder group is affected by the label.", + "The label implies a stronger save guarantee than the product can support." + ], + "context_pack_required": true +} diff --git a/skills/product-design-harness/resources/examples/quick-context-pack.json b/skills/product-design-harness/resources/examples/quick-context-pack.json new file mode 100644 index 000000000..2927ff1af --- /dev/null +++ b/skills/product-design-harness/resources/examples/quick-context-pack.json @@ -0,0 +1,104 @@ +{ + "schema_version": "2.1", + "session_config": { + "working_language": "en", + "canonical_identifiers": "en", + "fallback_language": "en" + }, + "review_id": "example-quick-001", + "goal": "Increase first-action completion by clarifying the empty state.", + "stage": "prototype", + "combined_verdict": "continue", + "actor_boundary": { + "target_population": [ + "New workspace admins" + ], + "operator": "Workspace admin", + "beneficiary": "Workspace team", + "machine_actor": "Not applicable", + "affected_people": [ + "Invited team members" + ], + "excluded_groups": [ + "Existing configured workspaces" + ] + }, + "product_organization": { + "organization": "Example Product Co.", + "project_owner": "Activation team", + "issuer": "Example Product Co." + }, + "stakeholder_effects": [ + { + "stakeholder": "Invited team members", + "effect": "Clearer setup can reduce delayed invitations." + } + ], + "human_judgment_boundary": { + "human_owned_decisions": [ + "Final copy tone" + ], + "machine_supported_inputs": [ + "Support notes", + "Session replays" + ], + "not_mechanized": [ + "Taste and brand judgment" + ], + "approval_gates": [ + { + "gate_id": "product-owner-release-approval", + "accountable_owner": "Product owner", + "condition": "Before release to users." + } + ] + }, + "unresolved_assumptions": [ + "Whether copy or missing product guidance causes the hesitation." + ], + "scope": [ + "Edit the empty-state headline.", + "Edit one action label." + ], + "non_goals": [ + "Do not change layout.", + "Do not change onboarding steps.", + "Do not change permissions or data handling." + ], + "acceptance_criteria": [ + "The new copy names the next action.", + "The first-action event distinguishes the released variant." + ], + "measurement_hooks": [ + "Compare first-action completion with the prior copy." + ], + "evidence_snapshot_ids": [ + "support-pattern-001", + "session-replay-pattern-001" + ], + "rollback_plan": "Restore the prior copy.", + "human_approval_gates": [ + { + "gate_id": "product-owner-release-approval", + "accountable_owner": "Product owner", + "condition": "Before release to users." + } + ], + "high_risk_actions": [], + "stop_conditions": [ + "People still hesitate after the copy change.", + "The change requires onboarding scope expansion." + ], + "execution_boundary": { + "may_do": [ + "Edit the empty-state headline.", + "Edit one action label." + ], + "must_not_do": [ + "Change layout, permissions, data handling, or onboarding steps." + ], + "must_ask": [ + "A material scope, risk, data, or stakeholder impact changes." + ] + } +} diff --git a/skills/product-design-harness/resources/examples/quick-gate-review.json b/skills/product-design-harness/resources/examples/quick-gate-review.json new file mode 100644 index 000000000..cf6fcd961 --- /dev/null +++ b/skills/product-design-harness/resources/examples/quick-gate-review.json @@ -0,0 +1,128 @@ +{ + "schema_version": "2.1", + "session_config": { + "working_language": "en", + "canonical_identifiers": "en", + "fallback_language": "en" + }, + "review_id": "example-quick-001", + "product_direction": "Clarify the empty-state action on the setup page.", + "mode": "quick_gate", + "stage": "prototype", + "actor_boundary": { + "target_population": [ + "New workspace admins" + ], + "operator": "Workspace admin", + "beneficiary": "Workspace team", + "machine_actor": "Not applicable", + "affected_people": [ + "Invited team members" + ], + "excluded_groups": [ + "Existing configured workspaces" + ] + }, + "product_organization": { + "organization": "Example Product Co.", + "project_owner": "Activation team", + "issuer": "Example Product Co." + }, + "stakeholder_effects": [ + { + "stakeholder": "Invited team members", + "effect": "Clearer setup can reduce delayed invitations." + } + ], + "human_judgment_boundary": { + "human_owned_decisions": [ + "Final copy tone" + ], + "machine_supported_inputs": [ + "Support notes", + "Session replays" + ], + "not_mechanized": [ + "Taste and brand judgment" + ], + "approval_gates": [ + { + "gate_id": "product-owner-release-approval", + "accountable_owner": "Product owner", + "condition": "Before release to users." + } + ] + }, + "unresolved_assumptions": [ + "Whether copy or missing product guidance causes the hesitation." + ], + "combined_verdict": "continue", + "weakest_flow": "evidence", + "strongest_signal": "Support notes and session replays show repeated hesitation at the same empty state.", + "riskiest_claim": "Clearer copy will improve first-action completion.", + "main_uncertainty": "Whether copy or missing product guidance causes the hesitation.", + "confidence_level": "medium", + "evidence_tier": "t2", + "main_trade_off": "Limit the change to copy so the team can learn without expanding onboarding scope.", + "human_owned_decision": "none", + "human_decision_record_id": null, + "evidence_receipt_ids": [ + "support-pattern-001", + "session-replay-pattern-001" + ], + "reviews": { + "user": { + "verdict": "continue", + "strongest_signal": "People repeatedly pause before the first setup action.", + "weakest_assumption": "The action label is the primary source of confusion.", + "missing_evidence": "Post-change completion behavior.", + "disconfirming_evidence": "People still pause after the copy change.", + "stop_condition": "The change reduces comprehension in a five-person check.", + "evidence_tier": "t2" + }, + "evidence": { + "verdict": "continue", + "strongest_signal": "Two independent internal sources show the same hesitation.", + "weakest_assumption": "The replay sample represents new users.", + "missing_evidence": "Segmented first-action completion.", + "disconfirming_evidence": "Completion does not move after release.", + "stop_condition": "No measurable event can distinguish the old and new copy.", + "evidence_tier": "t2" + }, + "business": { + "verdict": "continue", + "strongest_signal": "The change is reversible and may improve activation.", + "weakest_assumption": "First-action completion predicts later value.", + "missing_evidence": "Activation-to-retention link.", + "disconfirming_evidence": "Completion rises while retained setup does not.", + "stop_condition": "The change expands beyond copy and one action label.", + "evidence_tier": "t2" + } + }, + "next_smallest_action": "Release one copy variant and compare first-action completion.", + "execution_boundary": { + "may_do": [ + "Edit the empty-state headline.", + "Edit one action label." + ], + "must_not_do": [ + "Change layout, permissions, data handling, or onboarding steps." + ], + "must_ask": [ + "A material scope, risk, data, or stakeholder impact changes." + ] + }, + "human_approval_gates": [ + { + "gate_id": "product-owner-release-approval", + "accountable_owner": "Product owner", + "condition": "Before release to users." + } + ], + "high_risk_actions": [], + "stop_conditions": [ + "People still hesitate after the copy change.", + "The change requires onboarding scope expansion." + ], + "context_pack_required": true +} diff --git a/skills/product-design-harness/resources/examples/quick-gate-review.md b/skills/product-design-harness/resources/examples/quick-gate-review.md new file mode 100644 index 000000000..9707368bc --- /dev/null +++ b/skills/product-design-harness/resources/examples/quick-gate-review.md @@ -0,0 +1,51 @@ +# Example: Quick Gate Review + +Machine-checkable result: `quick-gate-review.json`. + +## Product Direction + +Change the empty-state copy on a setup page to reduce confusion. + +## Mode + +Quick Gate. + +## Verdict + +`continue`. + +## Why + +The change is reversible, low risk, and tied to a known confusion point. + +## UX3 Review + +| Flow | Result | +|---|---| +| User Flow | Users reach the empty state after connecting no sources and do not know what to do next. | +| Evidence Flow | Support notes and session replays show repeated hesitation at the same page. | +| Business Flow | Clearer setup may improve activation without changing product scope. | + +## Evidence And Confidence + +| Field | Answer | +|---|---| +| Evidence tier | t2 | +| Confidence level | Medium | +| Riskiest claim | Clearer copy will improve first-action completion. | +| Main uncertainty | Whether copy or missing guidance causes the hesitation. | + +## Constraints + +| Field | Answer | +|---|---| +| Scope | Edit empty-state headline and action label. | +| Non-goals | Do not redesign setup, add new automation, or change onboarding flow. | +| Measurement | Track click-through to first setup action. | +| Stop condition | Stop if users still hesitate or support questions do not change. | + +## Context Pack + +Execution may change copy and one action label. + +Execution must not change layout, permissions, data handling, or onboarding steps. diff --git a/skills/product-design-harness/resources/examples/red-team-review.json b/skills/product-design-harness/resources/examples/red-team-review.json new file mode 100644 index 000000000..46dce680a --- /dev/null +++ b/skills/product-design-harness/resources/examples/red-team-review.json @@ -0,0 +1,33 @@ +{ + "review_id": "red-team-unanimous-continue-example", + "claim_ids": [ + "claim-delegated-operations" + ], + "evidence_receipt_ids": [ + "ev-support-2026-07" + ], + "failure_modes": [ + "The assistant makes an irreversible customer change.", + "Operators lose the ability to interrupt the workflow.", + "Support volume rises after an incorrect automated action.", + "The workflow creates a compliance exception.", + "Users keep the current manual workaround." + ], + "disconfirming_tests": [ + "A supervised pilot shows no reduction in completion time." + ], + "hidden_affected_people": [ + "Customers receiving automated changes." + ], + "current_workaround": "Operators complete each change manually.", + "substitute_threats": { + "direct": "A competing automation product.", + "indirect": "A shared operations service.", + "platform": "A native workflow feature.", + "workflow": "A checklist and queue process.", + "doing_nothing": "Keep the current manual workflow." + }, + "trust_risk": "An unexplained action damages customer confidence.", + "stop_condition": "Any pilot creates an unapproved customer change.", + "verdict": "verify" +} diff --git a/skills/product-design-harness/resources/examples/standard-gate-review.json b/skills/product-design-harness/resources/examples/standard-gate-review.json new file mode 100644 index 000000000..1dccfe2cc --- /dev/null +++ b/skills/product-design-harness/resources/examples/standard-gate-review.json @@ -0,0 +1,127 @@ +{ + "schema_version": "2.1", + "session_config": { + "working_language": "en", + "canonical_identifiers": "en", + "fallback_language": "en" + }, + "review_id": "example-standard-001", + "product_direction": "Add scheduled CSV export to the reports page for team admins.", + "mode": "standard_gate", + "stage": "prototype", + "actor_boundary": { + "target_population": [ + "Team admins who repeatedly export reports" + ], + "operator": "Team admin", + "beneficiary": "Reporting team", + "machine_actor": "Not applicable", + "affected_people": [ + "Downstream report consumers" + ], + "excluded_groups": [ + "Teams without recurring report export workflows" + ] + }, + "product_organization": { + "organization": "Example Product Co.", + "project_owner": "Reporting team", + "issuer": "Example Product Co." + }, + "stakeholder_effects": [ + { + "stakeholder": "Downstream report consumers", + "effect": "Scheduled exports could change how recurring reporting work is coordinated." + } + ], + "human_judgment_boundary": { + "human_owned_decisions": [ + "Whether recurring export is strategically worth building" + ], + "machine_supported_inputs": [ + "Support tickets", + "Product logs" + ], + "not_mechanized": [ + "Roadmap priority trade-off" + ], + "approval_gates": [ + { + "gate_id": "product-owner-scheduling-build-approval", + "accountable_owner": "Product owner", + "condition": "Before any scheduling infrastructure build starts." + } + ] + }, + "unresolved_assumptions": [ + "Whether the request reflects a recurring workflow or one-off audits." + ], + "combined_verdict": "verify", + "weakest_flow": "evidence", + "strongest_signal": "Fourteen support tickets in one quarter ask for recurring report export.", + "riskiest_claim": "Admins will schedule exports instead of downloading manually.", + "main_uncertainty": "Whether the request reflects a recurring workflow or one-off audits.", + "confidence_level": "low", + "evidence_tier": "t1", + "main_trade_off": "Verify the recurring need before building scheduling infrastructure.", + "human_owned_decision": "none", + "human_decision_record_id": null, + "evidence_receipt_ids": [ + "support-ticket-pattern-002" + ], + "reviews": { + "user": { + "verdict": "continue", + "evidence_tier": "t2", + "strongest_signal": "Admins already download the same report every week.", + "weakest_assumption": "The weekly download is done by the same person each time.", + "missing_evidence": "Who consumes the exported file downstream.", + "disconfirming_evidence": "Downloads are irregular one-off audit pulls.", + "stop_condition": "No admin can name a recurring consumer of the export." + }, + "evidence": { + "verdict": "verify", + "evidence_tier": "t1", + "strongest_signal": "Ticket volume is consistent across three months.", + "weakest_assumption": "Ticket requests represent the broader admin base.", + "missing_evidence": "Product logs showing repeat manual export behavior.", + "disconfirming_evidence": "Logs show most exporters export only once.", + "stop_condition": "Export behavior cannot be measured per account." + }, + "business": { + "verdict": "continue", + "evidence_tier": "t2", + "strongest_signal": "Scheduled exports deepen weekly workflow dependency.", + "weakest_assumption": "Maintenance cost of scheduling stays bounded.", + "missing_evidence": "Infrastructure cost of recurring export jobs.", + "disconfirming_evidence": "Exports are replaced by a BI integration request.", + "stop_condition": "Scheduling requires a new permission or billing model." + } + }, + "next_smallest_action": "Query product logs for repeat manual exports per account over 90 days.", + "execution_boundary": { + "may_do": [ + "Analyze existing export logs and interview two weekly exporters." + ], + "must_not_do": [ + "Build scheduling infrastructure or change report permissions." + ], + "must_ask": [ + "The proof step requires production schema changes or new permissions." + ] + }, + "human_approval_gates": [ + { + "gate_id": "product-owner-scheduling-build-approval", + "accountable_owner": "Product owner", + "condition": "Before any scheduling infrastructure build starts." + } + ], + "high_risk_actions": [], + "stop_conditions": [ + "Fewer than ten accounts export the same report more than twice.", + "The proof step requires production schema changes." + ], + "context_pack_required": false, + "proof_step": "Measure repeat manual export behavior in product logs over the last 90 days." +} diff --git a/skills/product-design-harness/resources/examples/stop-reframe-review.json b/skills/product-design-harness/resources/examples/stop-reframe-review.json new file mode 100644 index 000000000..6b0183692 --- /dev/null +++ b/skills/product-design-harness/resources/examples/stop-reframe-review.json @@ -0,0 +1,141 @@ +{ + "schema_version": "2.1", + "session_config": { + "working_language": "en", + "canonical_identifiers": "en", + "fallback_language": "en" + }, + "review_id": "example-stop-001", + "product_direction": "Ship an AI support agent that replies to customers in production within two days, based on the founder's interview impressions.", + "mode": "standard_gate", + "stage": "idea", + "actor_boundary": { + "target_population": [ + "Support teams handling customer requests" + ], + "operator": "Support team member", + "beneficiary": "Support team and customers receiving correct replies", + "machine_actor": "AI support agent", + "affected_people": [ + "Customers receiving support replies" + ], + "excluded_groups": [ + "Internal-only support drafting workflows" + ] + }, + "product_organization": { + "organization": "Example Product Co.", + "project_owner": "Support experience team", + "issuer": "Example Product Co." + }, + "stakeholder_effects": [ + { + "stakeholder": "Customers receiving support replies", + "effect": "Unreviewed AI replies could give incorrect guidance and create escalation or recovery burden." + } + ], + "human_judgment_boundary": { + "human_owned_decisions": [ + "Acceptable risk of customer-facing AI replies" + ], + "machine_supported_inputs": [ + "Traceable support-failure artifacts", + "Observed customer reactions to human-reviewed drafts" + ], + "not_mechanized": [ + "Risk tolerance for unreviewed customer-facing replies" + ], + "approval_gates": [ + { + "gate_id": "risk-owner-reframe-approval", + "accountable_owner": "Product owner", + "condition": "Before the reframed question enters a new review." + } + ] + }, + "unresolved_assumptions": [ + "Whether any customer wants unreviewed AI replies rather than faster human-reviewed drafting." + ], + "combined_verdict": "stop_reframe", + "weakest_flow": "evidence", + "strongest_signal": "The founder can name three interviewees who complained about support load.", + "riskiest_claim": "Customers will accept AI-written replies without human review.", + "main_uncertainty": "Whether any real customer wants unreviewed AI replies at all.", + "confidence_level": "very_low", + "evidence_tier": "t0", + "main_trade_off": "Two days of build speed against untraceable evidence and customer-facing risk.", + "human_owned_decision": "risk", + "human_decision_record_id": "decision-example-002", + "evidence_receipt_ids": [ + "founder-impressions-001" + ], + "reviews": { + "user": { + "verdict": "verify", + "evidence_tier": "t1", + "strongest_signal": "Interviewees describe support load as painful.", + "weakest_assumption": "Complaints about load imply acceptance of AI replies.", + "missing_evidence": "Any observed customer reaction to an AI-written reply.", + "disconfirming_evidence": "Customers escalate or churn when replies feel automated.", + "stop_condition": "No interviewee can describe a concrete recent support failure." + }, + "evidence": { + "verdict": "stop_reframe", + "evidence_tier": "t0", + "strongest_signal": "Only the founder's memory of three conversations exists.", + "weakest_assumption": "Impressions recalled after the fact count as demand evidence.", + "missing_evidence": "Recordings, notes, tickets, or any traceable source artifact.", + "disconfirming_evidence": "Written notes contradict the recalled enthusiasm.", + "stop_condition": "No source artifact can be produced for any claimed conversation.", + "stop_reason_class": "core_evidence" + }, + "business": { + "verdict": "verify", + "evidence_tier": "t1", + "strongest_signal": "Support cost is a plausible recurring expense to displace.", + "weakest_assumption": "Willingness to pay follows from willingness to complain.", + "missing_evidence": "Any pricing signal or budget owner for this problem.", + "disconfirming_evidence": "Prospects expect AI support to be free.", + "stop_condition": "No budget owner can be named for the purchase." + } + }, + "next_smallest_action": "Rewrite the product question, then collect five traceable support-failure artifacts before any build step.", + "execution_boundary": { + "may_do": [ + "Collect and file traceable evidence artifacts.", + "Draft the reframed product question for review." + ], + "must_not_do": [ + "Write any product code.", + "Contact customers with an AI-written reply.", + "Commit to the two-day ship date." + ], + "must_ask": [ + "Which named budget owner will confirm the reframed problem is worth paying for?" + ] + }, + "human_approval_gates": [ + { + "gate_id": "risk-owner-reframe-approval", + "accountable_owner": "Product owner", + "condition": "Before the reframed question enters a new review." + } + ], + "high_risk_actions": [ + { + "action": "Send customer-facing AI replies without human review.", + "approval_gate": { + "gate_id": "risk-owner-reframe-approval", + "accountable_owner": "Product owner", + "condition": "Blocked until the reframed direction passes a new review with tier t2 or stronger evidence." + }, + "rollback_plan": "Disable AI replies and route all tickets back to the human queue." + } + ], + "stop_conditions": [ + "Any build work starts before the reframed question passes a new review.", + "Evidence collection substitutes recalled impressions for artifacts again." + ], + "context_pack_required": false, + "reframed_question": "Which recurring, traceable support failure costs a named budget owner enough that they would pay for a reviewed-by-human AI drafting workflow?" +} diff --git a/skills/product-design-harness/resources/examples/stop-reframe-review.md b/skills/product-design-harness/resources/examples/stop-reframe-review.md new file mode 100644 index 000000000..c942b0e41 --- /dev/null +++ b/skills/product-design-harness/resources/examples/stop-reframe-review.md @@ -0,0 +1,18 @@ +# Stop / Reframe Review Example + +A standard gate review that ends in `stop_reframe`: the evidence lane finds +only untraceable founder impressions (tier `t0`), which forces the stop and +produces one better product question instead of any execution work. + +Machine-checkable version: `stop-reframe-review.json` (validates against +`../schemas/review-result.schema.json` and `../scripts/check_review.py`). + +Key mechanics on display: + +| Mechanic | Where | +|---|---| +| Lane-level stop with a machine-readable reason | the evidence lane carries stop_reason_class core_evidence | +| Weakest flow decides; no averaging | two `verify` lanes cannot rescue a `t0` evidence lane | +| Tier gate | headline tier `t0` forces `stop_reframe` by contract | +| No execution scope on a stop | the boundary allows research actions only | +| The single output of a stop | one reframed question, not a plan and not a backlog | diff --git a/skills/product-design-harness/resources/examples/ux3-council-input.json b/skills/product-design-harness/resources/examples/ux3-council-input.json new file mode 100644 index 000000000..6530199d7 --- /dev/null +++ b/skills/product-design-harness/resources/examples/ux3-council-input.json @@ -0,0 +1,269 @@ +{ + "product_brief": { + "schema_version": "2.1", + "session_config": { + "working_language": "en", + "canonical_identifiers": "en", + "fallback_language": "en" + }, + "product_direction": "Let a workflow assistant complete recurring customer operations without manual approval.", + "accountable_owner": "Product owner", + "stage": "prototype", + "actor_boundary": { + "target_population": [ + "Operations teams handling recurring customer workflows" + ], + "operator": "Operations team member", + "beneficiary": "Operations team and customers receiving correct service", + "machine_actor": "Workflow assistant", + "affected_people": [ + "Customers affected by completed operations" + ], + "excluded_groups": [ + "One-off workflows", + "Workflows without reversible approval paths" + ] + }, + "business_boundary": { + "product_organization": "Example Product Co.", + "project_owner": "Workflow automation team", + "issuer": "Example Product Co.", + "customers": [ + "Teams handling recurring customer operations" + ], + "buyers": [ + "Operations leads" + ], + "operators": [ + "Operations team members" + ], + "partners": [ + "Not applicable" + ], + "funders": [ + "Not applicable" + ], + "platforms": [ + "Workflow assistant in the operations workspace" + ], + "regulators": [ + "Not applicable" + ], + "externality_bearers": [ + "Customers affected by completed operations" + ], + "decision_authority": "Product owner", + "value_exchange": "Operators may spend less time preparing recurring customer work while human approval limits customer-facing errors and recovery costs." + }, + "human_judgment_boundary": { + "human_owned_decisions": [ + "Acceptable customer-facing recovery risk" + ], + "machine_supported_inputs": [ + "Support notes", + "Observed workflow traces", + "Approval behavior" + ], + "not_mechanized": [ + "Risk tolerance for autonomous customer-facing action" + ], + "approval_gates": [ + { + "gate_id": "accountable-owner-customer-action-approval", + "accountable_owner": "Named accountable owner", + "condition": "Before any customer-facing execution." + } + ] + }, + "unresolved_assumptions": [ + "Whether people want full autonomy or faster preparation with approval." + ], + "execution_boundary": { + "may_do": [ + "implement the approved bounded change" + ], + "must_not_do": [ + "expand scope or execute external irreversible actions" + ], + "must_ask": [ + "new stakeholder, data, risk, or scope appears" + ] + }, + "problem_hypothesis": "Operators lose repeated time on recurring customer operations and may want delegated execution.", + "current_evidence": [ + { + "evidence_id": "support-notes-001", + "source_id": "support-notes-recurring-operations-2026-07", + "source_type": "internal", + "raw_artifact_uri": "example://support/recurring-customer-operations/2026-07", + "signal_type": "quote", + "signal": "Operators report repeated time loss in recurring customer operations.", + "interpretation": "Reported pain suggests a workflow problem but does not show demand for autonomous execution.", + "decision_impact": "Supports observing workflows and testing draft-only assistance with human approval before any autonomous execution.", + "evidence_tier": "t1", + "confidence_level": "low", + "counter_signal": "No operator has asked for autonomous customer-facing action; review and recovery cost may exceed time saved.", + "collected_at": "2026-07-09T12:00:00Z", + "source_last_verified_at": "2026-07-09T12:00:00Z", + "max_staleness_days": 30 + } + ], + "business_goal": "Reduce preparation time for recurring customer operations while keeping approval and recovery costs bounded.", + "constraints": [ + "Keep customer-facing execution under human approval.", + "Do not remove approval or automate irreversible customer-facing actions.", + "Stop the draft-only test if correction or recovery costs exceed time saved." + ], + "proposed_next_step": "Decide whether to build autonomous execution or draft-only assistance.", + "known_risks": [ + "Reported operator pain may not imply willingness to delegate customer-facing actions.", + "Review and recovery costs may exceed preparation time saved." + ] + }, + "claim_analysis": { + "claims": [ + { + "id": "c1", + "type": "user", + "claim": "Operators want delegated execution of recurring operations.", + "status": "assumption", + "support": "Support notes describe recurring time loss.", + "counter_signal": "No operator has asked for autonomous action.", + "confidence_level": "low", + "depends_on": [], + "breaks_if_false": [ + "c2" + ], + "proof_step": "Observe five recurring workflows and ask about delegation.", + "stop_condition": "No recurring workflow has a clear operator cost." + }, + { + "id": "c2", + "type": "business", + "claim": "Cycle-time reduction deepens workflow dependency and retention.", + "status": "assumption", + "support": "Cycle time is a stated operator pain.", + "counter_signal": "Review and recovery cost may exceed time saved.", + "confidence_level": "low", + "depends_on": [ + "c1" + ], + "breaks_if_false": [ + "c1" + ], + "proof_step": "Measure cycle time with draft-only assistance.", + "stop_condition": "Exception handling grows without bound." + } + ], + "riskiest_claim_id": "c1", + "critical_path": [ + "c1", + "c2" + ], + "highest_leverage_proof_step": "Test draft-only assistance with human approval on five recurring workflows.", + "human_owned_decision": "risk" + }, + "independent_reviews": [ + { + "reviewer": "user_flow", + "review_round": "independent", + "verdict": "verify", + "evidence_tier": "t1", + "confidence_level": "low", + "strongest_signal": "user lane signal from support notes.", + "weakest_assumption": "user lane assumption untested with operators.", + "missing_evidence": "Observed workflows and approval preferences.", + "disconfirming_evidence": "Operators reject autonomous customer-facing action.", + "stop_condition": "Customer-facing errors cannot be traced or reversed.", + "next_smallest_action": "Test draft-only assistance with human approval." + }, + { + "reviewer": "evidence_flow", + "review_round": "independent", + "verdict": "verify", + "evidence_tier": "t1", + "confidence_level": "low", + "strongest_signal": "evidence lane signal from support notes.", + "weakest_assumption": "evidence lane assumption untested with operators.", + "missing_evidence": "Observed workflows and approval preferences.", + "disconfirming_evidence": "Operators reject autonomous customer-facing action.", + "stop_condition": "Customer-facing errors cannot be traced or reversed.", + "next_smallest_action": "Test draft-only assistance with human approval." + }, + { + "reviewer": "business_flow", + "review_round": "independent", + "verdict": "verify", + "evidence_tier": "t1", + "confidence_level": "low", + "strongest_signal": "business lane signal from support notes.", + "weakest_assumption": "business lane assumption untested with operators.", + "missing_evidence": "Observed workflows and approval preferences.", + "disconfirming_evidence": "Operators reject autonomous customer-facing action.", + "stop_condition": "Customer-facing errors cannot be traced or reversed.", + "next_smallest_action": "Test draft-only assistance with human approval." + } + ], + "challenge_reviews": [ + { + "reviewer": "user_flow", + "review_round": "challenge", + "verdict": "verify", + "evidence_tier": "t1", + "confidence_level": "low", + "strongest_signal": "Cross-lane check of the strongest claim.", + "weakest_assumption": "The challenged lane may overweight reported pain.", + "missing_evidence": "Any behavioral trace supporting the challenged claim.", + "disconfirming_evidence": "Draft assistance does not reduce cycle time.", + "stop_condition": "The challenged claim fails without a replacement.", + "next_smallest_action": "Add the counter-evidence to the proof step.", + "objection_to": "business_flow", + "counter_evidence": "Support notes show pain but no delegation request.", + "position_change": "weakened" + }, + { + "reviewer": "evidence_flow", + "review_round": "challenge", + "verdict": "verify", + "evidence_tier": "t1", + "confidence_level": "low", + "strongest_signal": "Cross-lane check of the strongest claim.", + "weakest_assumption": "The challenged lane may overweight reported pain.", + "missing_evidence": "Any behavioral trace supporting the challenged claim.", + "disconfirming_evidence": "Draft assistance does not reduce cycle time.", + "stop_condition": "The challenged claim fails without a replacement.", + "next_smallest_action": "Add the counter-evidence to the proof step.", + "objection_to": "user_flow", + "counter_evidence": "Support notes show pain but no delegation request.", + "position_change": "weakened" + }, + { + "reviewer": "business_flow", + "review_round": "challenge", + "verdict": "verify", + "evidence_tier": "t1", + "confidence_level": "low", + "strongest_signal": "Cross-lane check of the strongest claim.", + "weakest_assumption": "The challenged lane may overweight reported pain.", + "missing_evidence": "Any behavioral trace supporting the challenged claim.", + "disconfirming_evidence": "Draft assistance does not reduce cycle time.", + "stop_condition": "The challenged claim fails without a replacement.", + "next_smallest_action": "Add the counter-evidence to the proof step.", + "objection_to": "evidence_flow", + "counter_evidence": "Support notes show pain but no delegation request.", + "position_change": "weakened" + } + ], + "uncertainty_review": { + "evidence_tier": "t1", + "confidence_level": "low", + "risk_class": "r3", + "reversibility": "low", + "main_uncertainty": "Whether people want full autonomy or faster preparation with approval.", + "false_confidence_risk": "Reported pain reads as demand for autonomy.", + "stale_evidence_ids": [], + "proof_bar": "Observed approval behavior on five real workflows.", + "verdict_impact": "verify", + "human_owned_decision": "risk" + } +} diff --git a/skills/product-design-harness/resources/examples/ux3-council-review.json b/skills/product-design-harness/resources/examples/ux3-council-review.json new file mode 100644 index 000000000..752edb52d --- /dev/null +++ b/skills/product-design-harness/resources/examples/ux3-council-review.json @@ -0,0 +1,170 @@ +{ + "schema_version": "2.1", + "session_config": { + "working_language": "en", + "canonical_identifiers": "en", + "fallback_language": "en" + }, + "review_id": "example-council-001", + "product_direction": "Let a workflow assistant complete recurring customer operations without manual approval.", + "mode": "ux3_council", + "stage": "prototype", + "actor_boundary": { + "target_population": [ + "Operations teams handling recurring customer workflows" + ], + "operator": "Operations team member", + "beneficiary": "Operations team and customers receiving correct service", + "machine_actor": "Workflow assistant", + "affected_people": [ + "Customers affected by completed operations" + ], + "excluded_groups": [ + "One-off workflows", + "Workflows without reversible approval paths" + ] + }, + "product_organization": { + "organization": "Example Product Co.", + "project_owner": "Workflow automation team", + "issuer": "Example Product Co." + }, + "stakeholder_effects": [ + { + "stakeholder": "Customers affected by completed operations", + "effect": "Autonomous execution could create customer-facing errors or recovery burden." + } + ], + "human_judgment_boundary": { + "human_owned_decisions": [ + "Acceptable customer-facing recovery risk" + ], + "machine_supported_inputs": [ + "Support notes", + "Observed workflow traces", + "Approval behavior" + ], + "not_mechanized": [ + "Risk tolerance for autonomous customer-facing action" + ], + "approval_gates": [ + { + "gate_id": "accountable-owner-customer-action-approval", + "accountable_owner": "Named accountable owner", + "condition": "Before any customer-facing execution." + } + ] + }, + "unresolved_assumptions": [ + "Whether people want full autonomy or faster preparation with approval." + ], + "combined_verdict": "verify", + "weakest_flow": "evidence", + "strongest_signal": "Operators report repeated time loss in recurring customer operations.", + "riskiest_claim": "The assistant can act safely without approval.", + "main_uncertainty": "Whether people want full autonomy or faster preparation with approval.", + "confidence_level": "low", + "evidence_tier": "t1", + "main_trade_off": "Delay autonomy to protect trust, recovery, and accountability.", + "human_owned_decision": "risk", + "human_decision_record_id": "decision-example-001", + "evidence_receipt_ids": [ + "support-notes-001" + ], + "reviews": { + "user": { + "verdict": "verify", + "strongest_signal": "Operators can name recurring work that consumes time.", + "weakest_assumption": "They want autonomous execution rather than assisted preparation.", + "missing_evidence": "Observed workflows and approval preferences.", + "disconfirming_evidence": "Operators reject autonomous action for customer-facing work.", + "stop_condition": "No recurring workflow has a clear operator cost.", + "evidence_tier": "t1" + }, + "evidence": { + "verdict": "verify", + "strongest_signal": "Support notes describe recurring work.", + "weakest_assumption": "Reported pain predicts willingness to delegate.", + "missing_evidence": "Observed error rate, recovery cost, and approval behavior.", + "disconfirming_evidence": "Draft assistance does not reduce cycle time.", + "stop_condition": "Customer-facing errors cannot be traced or reversed.", + "evidence_tier": "t1" + }, + "business": { + "verdict": "verify", + "strongest_signal": "Cycle-time reduction could deepen workflow dependency.", + "weakest_assumption": "Support and trust costs remain bounded.", + "missing_evidence": "Retention impact and operating cost.", + "disconfirming_evidence": "Review and recovery cost exceed time saved.", + "stop_condition": "The product must absorb unbounded exception handling.", + "evidence_tier": "t1" + } + }, + "next_smallest_action": "Test draft-only assistance with human approval on five recurring workflows.", + "execution_boundary": { + "may_do": [ + "Prepare workflow drafts and collect approval decisions." + ], + "must_not_do": [ + "Execute customer-facing actions or remove human approval." + ], + "must_ask": [ + "Any test would execute customer-facing work or remove human approval." + ] + }, + "human_approval_gates": [ + { + "gate_id": "accountable-owner-customer-action-approval", + "accountable_owner": "Named accountable owner", + "condition": "Before any customer-facing execution." + } + ], + "high_risk_actions": [ + { + "action": "Execute customer-facing workflow actions.", + "approval_gate": { + "gate_id": "accountable-owner-customer-action-approval", + "accountable_owner": "Named accountable owner", + "condition": "Before any customer-facing execution." + }, + "rollback_plan": "Stop the test and restore manual approval." + } + ], + "council_record": { + "independent_review_ids": [ + "review-user-001", + "review-evidence-001", + "review-business-001" + ], + "challenges": [ + { + "reviewer": "user_flow", + "objection_to": "business_flow", + "counter_evidence": "Reported time savings do not prove willingness to delegate customer-facing action.", + "position_change": "unchanged" + }, + { + "reviewer": "evidence_flow", + "objection_to": "user_flow", + "counter_evidence": "Support requests may ask for speed, not autonomy.", + "position_change": "weakened" + }, + { + "reviewer": "business_flow", + "objection_to": "evidence_flow", + "counter_evidence": "A draft-only test can measure cycle time and correction cost without autonomy.", + "position_change": "strengthened" + } + ], + "unresolved_conflicts": [ + "The acceptable threshold for customer-facing recovery risk remains human-owned." + ] + }, + "stop_conditions": [ + "Operators reject draft-only assistance.", + "Recovery paths remain unclear.", + "Customer-facing mistakes cannot be reversed." + ], + "context_pack_required": false, + "proof_step": "Observe five workflows and compare draft-only cycle time, corrections, and approval decisions." +} diff --git a/skills/product-design-harness/resources/examples/ux3-council-review.md b/skills/product-design-harness/resources/examples/ux3-council-review.md new file mode 100644 index 000000000..f9a4e6cf5 --- /dev/null +++ b/skills/product-design-harness/resources/examples/ux3-council-review.md @@ -0,0 +1,74 @@ +# Example: UX3 Council Review + +Machine-checkable result: `ux3-council-review.json`. + +## Product Direction + +Let a workflow assistant complete recurring customer operations without manual +approval. + +Stage: prototype. Risk class: R3. + +## Claim Graph + +| ID | Claim | Type | Depends on | Breaks if false | +|---|---|---|---|---| +| U1 | Operators repeatedly perform a costly workflow. | User | None | E1, B1 | +| E1 | Assistance reduces cycle time without increasing corrections. | Evidence | U1 | R1, B1 | +| R1 | Customer-facing mistakes can be detected and reversed. | Risk | E1 | B1, direction | +| B1 | Time saved exceeds review, support, and recovery cost. | Business | U1, E1, R1 | direction | + +R1 is the riskiest claim because its failure blocks autonomous action even if +the user and business claims remain plausible. + +## Independent Reviews + +| Flow | Verdict | Main reason | +|---|---|---| +| User | verify | The problem is plausible, but approval preference and recovery mental model are unclear. | +| Evidence | verify | Current proof is t1: stated pain and support notes without observed delegation behavior. | +| Business | verify | Value is plausible, but trust, review, and exception cost are unknown. | + +## Challenge Round + +| Reviewer | objection_to | counter_evidence | position_change | +|---|---|---|---| +| User | business_flow | Reported time savings do not prove willingness to delegate customer-facing action. | unchanged | +| Evidence | user_flow | Support requests may ask for speed, not autonomy. | weakened | +| Business | evidence_flow | A draft-only test can measure cycle time and correction cost without full autonomy. | strengthened | + +The challenge round does not force consensus. It identifies draft-only +assistance as the proof step that can test all three lanes safely. + +## Uncertainty Review + +| Field | Answer | +|---|---| +| Evidence tier | t1 | +| Confidence level | Low | +| Risk class | R3 | +| Reversibility | Medium | +| Main uncertainty | Whether people want autonomy or faster preparation with approval. | +| Proof bar | Observe five workflows and compare draft cycle time, corrections, and approval decisions. | + +## Final Result + +| Machine field | Answer | +|---|---| +| combined_verdict | verify | +| weakest_flow | evidence | +| main_trade_off | Delay autonomy to protect trust, recovery, and accountability. | +| human_owned_decision | risk | +| next_smallest_action | Test draft-only assistance with human approval on five workflows. | +| context_pack_required | false | + +Execution may prepare workflow drafts and collect approval decisions. + +Execution must not perform customer-facing actions or remove human approval. + +## Stop Conditions + +- No recurring workflow has a clear operator cost. +- Operators reject draft-only assistance. +- Recovery paths remain unclear. +- Customer-facing mistakes cannot be reversed. diff --git a/skills/product-design-harness/resources/examples/verdict-override.json b/skills/product-design-harness/resources/examples/verdict-override.json new file mode 100644 index 000000000..addddd5e5 --- /dev/null +++ b/skills/product-design-harness/resources/examples/verdict-override.json @@ -0,0 +1,29 @@ +{ + "override_id": "override-example-001", + "review_id": "example-stop-001", + "overridden_verdict": "stop_reframe", + "acknowledged_weakest_flow": "evidence", + "authorized_scope": { + "may_do": [ + "Build an internal prototype that drafts replies into a human review queue.", + "Run the prototype on the next twenty real tickets with a human reviewing every draft." + ], + "must_not_do": [ + "Send any AI-written reply to a customer without human approval.", + "Announce, demo externally, or sell the feature." + ], + "must_ask": [ + "Who reviews every draft during the trial, by name?" + ] + }, + "accountable_owner": "Jordan Lee, founder", + "rationale": "A strategic partner demo in three weeks needs a working draft queue. The founder accepts the evidence gap for an internal-only prototype behind a mandatory human review step, and accepts personally owning the outcome if the tripwires fire.", + "expires_at": "2099-01-01T00:00:00Z", + "tripwires": [ + "Any AI-drafted reply reaches a customer without human approval.", + "The partner demo is cancelled or moved beyond the override window." + ], + "renewal_requires": [ + "Twenty human-reviewed tickets with approval rate and edit distance filed as evidence receipts." + ] +} diff --git a/skills/product-design-harness/resources/examples/verdict-override.md b/skills/product-design-harness/resources/examples/verdict-override.md new file mode 100644 index 000000000..309ff5462 --- /dev/null +++ b/skills/product-design-harness/resources/examples/verdict-override.md @@ -0,0 +1,29 @@ +# Verdict Override Example + +The review in `stop-reframe-review.json` returned `stop_reframe`: the +evidence lane found only untraceable founder impressions. The founder +decides to build a scoped internal prototype anyway. This example shows +what that decision looks like when it is done honestly. + +Machine-checkable version: `verdict-override.json`. Validate it with: + +``` +python scripts/check_override.py examples/verdict-override.json \ + examples/stop-reframe-review.json +``` + +Key mechanics on display: + +| Mechanic | Where | +|---|---| +| The verdict is untouched | the review file still says `stop_reframe`; the override is a separate artifact | +| The owner restates the gap | `acknowledged_weakest_flow` must match the review's `weakest_flow` | +| Scope is granted, not assumed | `authorized_scope` allows an internal prototype; customer contact stays banned | +| No scope laundering | a `may_do` entry that repeats the review's `must_not_do` fails the checker | +| Time-boxed by contract | `expires_at` is required; a lapsed override fails the checker and the verdict is back in force | +| Voidable | any tripwire firing voids the authorization immediately | +| Renewal is a review | `renewal_requires` names the evidence a fresh review must see; there is no quiet extension | + +One honesty note: this example uses a far-future `expires_at` so the +repository's own CI never starts failing on it. A real override should +expire in days or weeks, not decades - the expiry is the point. diff --git a/skills/product-design-harness/resources/knowledge/ontology.json b/skills/product-design-harness/resources/knowledge/ontology.json new file mode 100644 index 000000000..0a5f1c5ba --- /dev/null +++ b/skills/product-design-harness/resources/knowledge/ontology.json @@ -0,0 +1,191 @@ +{ + "schema_version": "1.0.0", + "canonical_language": "en", + "name": "UX3 knowledge kernel", + "description": "Canonical product judgment terms for machine review and human documentation.", + "flows": [ + { + "id": "user_flow", + "name": "User Flow", + "definition": "Identifies target populations, affected people, excluded groups, situations, tasks, current workarounds, and the conditions under which the product should create an outcome.", + "must_answer": [ + "Who is the product for?", + "Who is affected by the product decision?", + "What are those actors trying to accomplish?", + "What cost, friction, risk, or loss of control exists now?" + ] + }, + { + "id": "evidence_flow", + "name": "Evidence Flow", + "definition": "Evidence Flow is the product sensing, learning, and calibration system joining internal and external data, behavior, subjective experience, interpretation, counter-signals, evaluations, and action traces; evidence informs decisions, while taste is recorded separately as an accountable human decision input.", + "must_answer": [ + "What signal was observed?", + "Where did the signal come from?", + "What interpretation is being made?", + "What counter-signal weakens it?", + "What decision impact follows?" + ] + }, + { + "id": "business_flow", + "name": "Business Flow", + "definition": "Identifies the company, project owner, issuer, accountable owner, and stakeholders who create value, receive value, pay, decide, operate, or absorb risk.", + "must_answer": [ + "Who creates value?", + "Who receives value?", + "Who pays or decides?", + "Who bears cost or risk?", + "Can the exchange remain viable and legitimate?" + ] + } + ], + "intersections": [ + { + "id": "user_evidence", + "name": "User + Evidence", + "label": "Situated understanding", + "required_question": "Do behavior, subjective experience, context, and system signals support the same interpretation?" + }, + { + "id": "evidence_business", + "name": "Evidence + Business", + "label": "Viable learning", + "required_question": "Is there sufficient evidence to justify investment, risk, operation, and continued learning?" + }, + { + "id": "user_business", + "name": "User + Business", + "label": "Sustainable value exchange", + "required_question": "Is value created and captured without hiding cost, exclusion, or responsibility?" + }, + { + "id": "ux3_decision_kernel", + "name": "User + Evidence + Business", + "label": "UX3 Decision Kernel", + "required_question": "What bounded, explainable, testable, and accountable action follows?" + } + ], + "actor_roles": [ + { + "id": "primary_user", + "definition": "The target actor expected to operate the product for the main outcome." + }, + { + "id": "secondary_user", + "definition": "An actor who uses part of the product or is involved in the workflow without being the primary target." + }, + { + "id": "machine_actor", + "definition": "An automated agent, model, workflow, or software component that can sense, decide, call tools, or act on behalf of a person or organization." + }, + { + "id": "beneficiary", + "definition": "A person or group expected to receive benefit without necessarily operating the product." + }, + { + "id": "affected_person", + "definition": "A person or group changed by the product decision, including those who do not consent to or operate the product." + }, + { + "id": "excluded_group", + "definition": "A population intentionally or unintentionally underserved, blocked, misrepresented, or left outside the product boundary." + } + ], + "stakeholder_roles": [ + { + "id": "company", + "definition": "The organization that creates, distributes, and remains accountable for the product." + }, + { + "id": "project_owner", + "definition": "The named person or team accountable for the current product decision." + }, + { + "id": "issuer", + "definition": "The entity that issues a credential, claim, artifact, decision, or product promise." + }, + { + "id": "customer", + "definition": "The person or organization that receives the product's value." + }, + { + "id": "buyer", + "definition": "The person or organization that pays, approves purchase, or controls budget." + }, + { + "id": "employee_operator", + "definition": "Internal worker or operator who must deliver, support, review, or recover the product." + }, + { + "id": "partner_channel", + "definition": "External partner, distributor, integrator, or channel that changes adoption, cost, or accountability." + }, + { + "id": "investor_funder", + "definition": "Stakeholder providing capital, grants, or other resources that shape constraints and expectations." + }, + { + "id": "platform_provider", + "definition": "Infrastructure, marketplace, model, payment, identity, or distribution provider that can enable or constrain the product." + }, + { + "id": "regulator", + "definition": "Authority or rule-setting body that can define compliance, legitimacy, or permitted operation." + }, + { + "id": "externality_bearer", + "definition": "Community or group that absorbs cost, risk, confusion, exclusion, or other product externalities." + } + ], + "evidence_terms": [ + { + "id": "source", + "definition": "Where the signal came from." + }, + { + "id": "signal", + "definition": "What was observed or reported before interpretation." + }, + { + "id": "interpretation", + "definition": "What the reviewer thinks the signal means." + }, + { + "id": "counter_signal", + "definition": "Evidence or reasoning that weakens, contradicts, or reframes the interpretation." + }, + { + "id": "decision_impact", + "definition": "What changes in the product decision because of the interpreted evidence." + }, + { + "id": "observed_outcome", + "definition": "What happened after the bounded action was taken." + } + ], + "human_judgment_terms": [ + { + "id": "human_taste", + "definition": "A person's accountable preference about quality, feel, meaning, taste, or strategic appetite; it is not an evidence score." + }, + { + "id": "human_judgment", + "definition": "A named person's accountable decision on taste, ethics, meaning, risk appetite, or final responsibility." + }, + { + "id": "accountable_input", + "definition": "A recorded human-owned input that may set a direction, raise a proof bar, or accept a bounded risk without pretending to be observed evidence." + } + ], + "learning_loop": [ + "signal", + "interpretation", + "counter_signal", + "decision_impact", + "human_judgment", + "bounded_action", + "observed_outcome", + "evidence_update_or_rule_update" + ] +} diff --git a/skills/product-design-harness/resources/knowledge/rules.json b/skills/product-design-harness/resources/knowledge/rules.json new file mode 100644 index 000000000..6680d885a --- /dev/null +++ b/skills/product-design-harness/resources/knowledge/rules.json @@ -0,0 +1,777 @@ +{ + "schema_version": "1.0.0", + "rules": [ + { + "rule_id": "ux3.rule.actor_boundary", + "title": "Actor boundary", + "flow": "user_flow", + "strength": "required", + "trigger": [ + "A review names a user, customer, operator, beneficiary, machine actor, buyer, issuer, owner, or affected group." + ], + "must_inspect": [ + "Primary and secondary users, beneficiaries, affected people, excluded groups, machine actors, buyers, issuers, and accountable owners." + ], + "must_do": [ + "Separate who operates the product, who benefits, who pays, who decides, who issues claims, who owns accountability, and who absorbs risk." + ], + "must_not_do": [ + "Treat user, customer, buyer, beneficiary, operator, and affected person as interchangeable." + ], + "evidence_required": [ + "Named roles with source, relationship to the workflow, authority, benefit, burden, and risk exposure." + ], + "counter_signal": [ + "A stakeholder is affected or pays but is missing from the actor map, or a machine actor can act without a named accountable owner." + ], + "human_boundary": [ + "A named human decides whether excluded or indirectly affected groups are acceptable for the current proof step." + ], + "stop_condition": [ + "Stop or reframe when the accountable owner, affected population, or machine actor authority cannot be identified." + ], + "output_requirement": [ + "Emit an actor map with operator, beneficiary, affected_person, excluded_group, buyer, issuer, and accountable_owner fields or explicit not_applicable reasons." + ], + "source": [ + "UX3 canonical model: User Flow and Business Flow actor definitions." + ] + }, + { + "rule_id": "ux3.rule.problem_hypothesis", + "title": "Problem hypothesis", + "flow": "user_flow", + "strength": "required", + "trigger": [ + "A request proposes a feature, workflow, product direction, launch, or change." + ], + "must_inspect": [ + "Target situation, current workaround, actor cost, friction, risk, urgency, and falsification criteria." + ], + "must_do": [ + "Restate the request as a testable problem hypothesis before recommending build or launch." + ], + "must_not_do": [ + "Treat a requested solution, executive preference, or novelty claim as proof that the problem exists." + ], + "evidence_required": [ + "Observed behavior, direct quote, workflow trace, support issue, willingness signal, or comparable source tied to a specific actor and situation." + ], + "counter_signal": [ + "Actors do not experience the cost, already have a sufficient workaround, or would not change behavior if the product existed." + ], + "human_boundary": [ + "A named human may choose to explore a weakly evidenced problem only by recording the learning reason and proof bar." + ], + "stop_condition": [ + "Stop or reframe when the problem, actor, situation, or disconfirming test cannot be stated." + ], + "output_requirement": [ + "Emit a problem_hypothesis with actor, situation, current_workaround, cost, falsification_criteria, and next_learning_step." + ], + "source": [ + "UX3 knowledge kernel: problem requests remain hypotheses until situated evidence is known." + ] + }, + { + "rule_id": "ux3.rule.behavior_subjective_separation", + "title": "Behavior and subjective experience separation", + "flow": "evidence_flow", + "strength": "required", + "trigger": [ + "A review uses user opinion, interview language, sentiment, analytics, logs, observed workflow, or behavioral metrics." + ], + "must_inspect": [ + "Observed behavior, stated experience, context, intensity, timing, and whether either signal changes the product decision." + ], + "must_do": [ + "Record behavior and subjective experience as different signals and compare whether they support the same interpretation." + ], + "must_not_do": [ + "Use praise as behavior, use behavior as motivation, or let either signal impersonate the other." + ], + "evidence_required": [ + "At least one source-labeled behavior signal or source-labeled subjective signal with context and decision impact." + ], + "counter_signal": [ + "Users praise the idea but do not act, or users act while stated motivation contradicts the assumed reason." + ], + "human_boundary": [ + "A named human decides how much subjective meaning or emotional intensity should influence taste and positioning." + ], + "stop_condition": [ + "Stop or downgrade when behavior and subjective experience are collapsed into one unsupported evidence claim." + ], + "output_requirement": [ + "Emit separate behavior_signal and subjective_signal entries, each with source, interpretation, counter_signal, and decision_impact." + ], + "source": [ + "UX3 canonical model: Evidence Flow separates behavior, subjective experience, and interpretation." + ] + }, + { + "rule_id": "ux3.rule.disconfirm_first", + "title": "Disconfirm first", + "flow": "evidence_flow", + "strength": "required", + "trigger": [ + "A review supports a product direction, proof claim, investment, launch, or automation step." + ], + "must_inspect": [ + "The strongest material counter-evidence, missing evidence, alternate explanations, and failure criteria." + ], + "must_do": [ + "Present disconfirming evidence and uncertainty before supporting evidence." + ], + "must_not_do": [ + "List only positive signals or bury counter-signals after a confident recommendation." + ], + "evidence_required": [ + "A source-labeled counter-signal or an explicit statement that no material counter-signal is currently known and what search was performed." + ], + "counter_signal": [ + "The main support can be explained by novelty, selection bias, channel pressure, one-off urgency, or reviewer preference." + ], + "human_boundary": [ + "A named human may proceed despite counter-evidence only with recorded rationale, accepted risk, and reversal condition." + ], + "stop_condition": [ + "Stop or reframe when no plausible counter-signal has been inspected for a material decision." + ], + "output_requirement": [ + "Emit counter_signal_first with counter_signal, alternate_explanation, decision_impact, and reversal_condition." + ], + "source": [ + "UX3 distilled rule family: Disconfirm first." + ] + }, + { + "rule_id": "ux3.rule.evidence_separation", + "title": "Evidence separation", + "flow": "evidence_flow", + "strength": "required", + "trigger": [ + "Any evidence receipt, claim, metric, quote, benchmark, incident, or evaluation is used to change a decision." + ], + "must_inspect": [ + "Source, signal, interpretation, counter-signal, freshness, reliability, and decision impact." + ], + "must_do": [ + "Keep source, signal, interpretation, counter-signal, and decision impact as separate fields." + ], + "must_not_do": [ + "Embed interpretation inside a metric or quote, or let a source label stand in for decision impact." + ], + "evidence_required": [ + "Traceable evidence receipt with provenance and a decision-changing interpretation." + ], + "counter_signal": [ + "The same signal supports multiple interpretations, is stale, lacks provenance, or conflicts with another material source." + ], + "human_boundary": [ + "A named human owns any taste, ethics, or strategy input that is not observed evidence." + ], + "stop_condition": [ + "Stop or downgrade when source, signal, interpretation, or decision impact is missing for material evidence." + ], + "output_requirement": [ + "Emit evidence entries with source, signal, interpretation, counter_signal, and decision_impact fields." + ], + "source": [ + "UX3 canonical model: Evidence Flow separation." + ] + }, + { + "rule_id": "ux3.rule.evidence_sized_action", + "title": "Evidence-sized action", + "flow": "cross_flow", + "strength": "required", + "trigger": [ + "A review recommends build, launch, spend, automation, external communication, irreversible change, or broader rollout." + ], + "must_inspect": [ + "Evidence tier, risk, reversibility, blast radius, uncertainty, stakeholder exposure, and next smallest learning step." + ], + "must_do": [ + "Limit the next action to what the current evidence tier, risk, and reversibility justify." + ], + "must_not_do": [ + "Upgrade weak proof with confidence language, urgency, taste, or stakeholder pressure." + ], + "evidence_required": [ + "Evidence tier and rationale for why the proposed action size is proportional to observed proof and recoverability." + ], + "counter_signal": [ + "The action affects more people, spends more, grants more authority, or becomes harder to reverse than the evidence supports." + ], + "human_boundary": [ + "A named human may accept a larger action only by recording risk appetite, owner, limit, and reversal condition." + ], + "stop_condition": [ + "Stop or reduce scope when action size exceeds evidence tier or recovery capacity." + ], + "output_requirement": [ + "Emit bounded_action with evidence_tier, max_scope, risk_limit, reversibility, owner, stop_condition, and observation_plan." + ], + "source": [ + "UX3 distilled rule family: Evidence-sized action." + ] + }, + { + "rule_id": "ux3.rule.minimum_authority", + "title": "Minimum authority", + "flow": "cross_flow", + "strength": "conditional", + "trigger": [ + "A machine actor, automation, agent, workflow, integration, or delegated process can read, write, decide, spend, message, publish, or call tools." + ], + "must_inspect": [ + "Requested permissions, tool access, data access, execution boundary, approval path, trace, and recovery option." + ], + "must_do": [ + "Grant the least authority needed for the current proof step and require a named accountable owner." + ], + "must_not_do": [ + "Grant broad, persistent, external, or irreversible authority for a narrow learning step." + ], + "evidence_required": [ + "Specific task need, minimum permission set, duration, owner, audit trace, and revocation path." + ], + "counter_signal": [ + "The actor requests unused permissions, lacks an owner, cannot be audited, or can affect parties outside the proof boundary." + ], + "human_boundary": [ + "A named human approves any external, irreversible, sensitive, financial, or reputation-bearing authority." + ], + "stop_condition": [ + "Stop when minimum permission, owner, trace, or revocation path is absent." + ], + "output_requirement": [ + "Emit authority_boundary with actor, allowed_actions, denied_actions, data_scope, time_limit, owner, audit_trace, and revocation_path." + ], + "source": [ + "UX3 distilled rule family: Minimum authority." + ] + }, + { + "rule_id": "ux3.rule.high_risk_action_bundle", + "title": "High-risk action bundle", + "flow": "cross_flow", + "strength": "conditional", + "trigger": [ + "The next action is external, irreversible, sensitive, financial, legal, reputation-bearing, safety-relevant, or hard to recover." + ], + "must_inspect": [ + "Owner, approval, scope limit, blast radius, trace, failure handling, rollback, recovery path, and user or stakeholder impact." + ], + "must_do": [ + "Require an owner, explicit approval, limit, trace, failure handling, and recovery path before execution." + ], + "must_not_do": [ + "Execute high-risk actions from an implicit approval, vague owner, or unbounded scope." + ], + "evidence_required": [ + "Approval record, action boundary, risk assessment, recovery plan, and evidence that the action is necessary for the current proof step." + ], + "counter_signal": [ + "No rollback exists, affected parties are not identified, approval is ambiguous, or failure handling depends on manual discovery after harm." + ], + "human_boundary": [ + "A named human retains final approval and responsibility for high-risk execution." + ], + "stop_condition": [ + "Stop when owner, approval, limit, trace, failure handling, or recovery path is missing." + ], + "output_requirement": [ + "Emit high_risk_action_bundle with owner, approval_record, scope_limit, trace_id, failure_handling, recovery_path, and abort_condition." + ], + "source": [ + "UX3 distilled rule family: High-risk action bundle." + ] + }, + { + "rule_id": "ux3.rule.minimum_validated_proof", + "title": "Minimum Validated Proof", + "flow": "cross_flow", + "strength": "required", + "trigger": [ + "A review proposes an MVP, prototype, pilot, experiment, launch slice, or validation step." + ], + "must_inspect": [ + "Riskiest assumption, actor behavior needed to prove it, proof bar, smallest test, and what would invalidate the direction." + ], + "must_do": [ + "Design the smallest proof that tests the riskiest assumption, not the smallest feature list." + ], + "must_not_do": [ + "Call a reduced feature set an MVP when it does not test the core risk." + ], + "evidence_required": [ + "A named riskiest assumption, measurable behavior or outcome, proof bar, observation plan, and disconfirming threshold." + ], + "counter_signal": [ + "The proposed MVP mainly demonstrates build ability, visual appeal, or internal preference while leaving the riskiest assumption untested." + ], + "human_boundary": [ + "A named human chooses which assumption is strategic enough to test first when multiple material risks remain." + ], + "stop_condition": [ + "Stop or reframe when the proof step does not observe the riskiest assumption." + ], + "output_requirement": [ + "Emit minimum_validated_proof with riskiest_assumption, test_actor, proof_bar, smallest_test, disconfirming_threshold, and next_decision." + ], + "source": [ + "UX3 distilled rule family: Minimum Validated Proof." + ] + }, + { + "rule_id": "ux3.rule.feedback_classification", + "title": "Feedback classification", + "flow": "evidence_flow", + "strength": "required", + "trigger": [ + "Incoming feedback, complaint, praise, support request, metric change, incident, review, or stakeholder request may affect product direction." + ], + "must_inspect": [ + "Source, actor role, recency, repeatability, severity, behavior link, decision impact, and whether the signal is evidence, noise, incident, or drift." + ], + "must_do": [ + "Classify feedback before changing direction or adding work." + ], + "must_not_do": [ + "Treat all feedback as equal, or convert a single loud signal into a roadmap change without classification." + ], + "evidence_required": [ + "Feedback source, classification, rationale, related evidence, counter-signal, and proposed action or no-action reason." + ], + "counter_signal": [ + "The feedback is isolated, unactionable, mismatched to the target actor, contradicted by behavior, or already covered by an accepted risk." + ], + "human_boundary": [ + "A named human decides whether strategically important but weak feedback deserves exploration despite low evidence." + ], + "stop_condition": [ + "Stop or defer when feedback cannot be classified or lacks a decision impact." + ], + "output_requirement": [ + "Emit feedback_classification with category, source, actor_role, severity, repeatability, decision_impact, and next_action." + ], + "source": [ + "UX3 distilled rule family: Feedback classification." + ] + }, + { + "rule_id": "ux3.rule.false_product_market_fit", + "title": "False product-market fit", + "flow": "cross_flow", + "strength": "required", + "trigger": [ + "A review claims traction, product-market fit, strong demand, adoption, retention, or launch readiness." + ], + "must_inspect": [ + "Repeated use, workflow dependence, payment or budget movement, switching cost, referral with reputation at stake, retention, and cohort quality." + ], + "must_do": [ + "Rank praise and novelty below repeated behavior, workflow dependence, payment, and reputation-bearing referral." + ], + "must_not_do": [ + "Treat excitement, signups, demos, vanity metrics, or novelty as product-market fit." + ], + "evidence_required": [ + "Behavioral proof tied to a target actor and repeated or costly enough to show real demand." + ], + "counter_signal": [ + "Users praise but do not return, do not pay, do not integrate, do not depend on the workflow, or churn after novelty fades." + ], + "human_boundary": [ + "A named human may pursue a strategic wedge before fit only by recording that fit is unproven and naming the next proof bar." + ], + "stop_condition": [ + "Stop or downgrade fit claims when proof is limited to praise, novelty, signups, or one-off usage." + ], + "output_requirement": [ + "Emit fit_evidence with signal_strength, behavior_frequency, workflow_dependence, payment_signal, referral_risk, counter_signal, and fit_claim_limit." + ], + "source": [ + "UX3 distilled rule family: False product-market fit." + ] + }, + { + "rule_id": "ux3.rule.whole_ownership_cost", + "title": "Whole ownership cost", + "flow": "business_flow", + "strength": "required", + "trigger": [ + "A review recommends building, launching, integrating, automating, scaling, or maintaining a product capability." + ], + "must_inspect": [ + "Support, trust, measurement, maintenance, confusion, governance, dependency, opportunity cost, recovery cost, and stakeholder burden." + ], + "must_do": [ + "Include whole ownership cost in viability and value exchange decisions." + ], + "must_not_do": [ + "Use build cost, model cost, or implementation effort as the full cost of ownership." + ], + "evidence_required": [ + "Cost categories, responsible owner, expected operating load, measurement plan, and what cost would make the direction nonviable." + ], + "counter_signal": [ + "Hidden support, trust, compliance, maintenance, or confusion cost exceeds the value created or cannot be owned." + ], + "human_boundary": [ + "A named human accepts or rejects ownership cost trade-offs and opportunity cost." + ], + "stop_condition": [ + "Stop or reframe when ownership cost is unknown, unowned, or larger than the justified proof step." + ], + "output_requirement": [ + "Emit ownership_cost with support, trust, measurement, maintenance, governance, opportunity_cost, owner, and nonviable_threshold." + ], + "source": [ + "UX3 distilled rule family: Whole ownership cost." + ] + }, + { + "rule_id": "ux3.rule.depth_accumulation", + "title": "Depth accumulation", + "flow": "business_flow", + "strength": "advisory", + "trigger": [ + "A review claims defensibility, moat, compounding advantage, quality, expertise, or long-term product strength." + ], + "must_inspect": [ + "Domain terms, edge cases, failure history, workflow rules, evaluation suites, expert judgment, proprietary learning, and switching cost." + ], + "must_do": [ + "Identify what durable depth accumulates from use, learning, failures, and expert review." + ], + "must_not_do": [ + "Describe feature count, generic automation, or visual polish as durable product depth." + ], + "evidence_required": [ + "A depth asset with source, owner, reuse path, evaluation method, and evidence that it improves future decisions or workflow lock-in." + ], + "counter_signal": [ + "The asset is generic, easily copied, not reused, not evaluated, or disconnected from the target workflow." + ], + "human_boundary": [ + "A named human judges whether the depth aligns with strategy and is worth compounding." + ], + "stop_condition": [ + "Stop claiming defensibility when no durable depth asset or accumulation path is identified." + ], + "output_requirement": [ + "Emit depth_asset with asset_type, source, reuse_path, evaluation_method, owner, counter_signal, and compounding_decision." + ], + "source": [ + "UX3 distilled rule family: Depth accumulation." + ] + }, + { + "rule_id": "ux3.rule.failure_to_rule_learning", + "title": "Failure-to-rule learning", + "flow": "evidence_flow", + "strength": "required", + "trigger": [ + "An edge case, incident, repeated failure, surprising outcome, or recurring review correction appears." + ], + "must_inspect": [ + "Failure pattern, recurrence, affected actors, missing evidence, broken assumption, reproducible case, and whether the system should change." + ], + "must_do": [ + "Convert repeated failure into a reproducible case, test, evaluation, rule, or explicit accepted risk." + ], + "must_not_do": [ + "Leave repeated failures as chat memory, undocumented judgment, or one-off manual caution." + ], + "evidence_required": [ + "Failure description, recurrence evidence, affected scope, root assumption, selected learning artifact, and owner." + ], + "counter_signal": [ + "The failure is non-reproducible, isolated, outside the product boundary, or already covered by a sufficient rule and test." + ], + "human_boundary": [ + "A named human may accept a recurring risk only with rationale, owner, review date, and reversal condition." + ], + "stop_condition": [ + "Stop or block repetition when a repeated failure has no test, evaluation, rule, or accepted-risk record." + ], + "output_requirement": [ + "Emit learning_update with failure_pattern, recurrence, artifact_type, owner, due_condition, and accepted_risk if applicable." + ], + "source": [ + "UX3 distilled rule family: Failure-to-rule learning." + ] + }, + { + "rule_id": "ux3.rule.mental_model_alignment", + "title": "Mental model alignment", + "flow": "user_flow", + "strength": "conditional", + "trigger": [ + "A product introduces a novel interaction, agent capability, automated decision, unfamiliar state, hidden system behavior, or changed responsibility that a target actor must understand." + ], + "must_inspect": [ + "The actor's current mental model, the product team's conceptual model, prior expectation, predicted system behavior, visible state, error expectation, and responsibility boundary." + ], + "must_do": [ + "Compare what the actor expects with what the product or agent will actually do, then expose the smallest explanation, preview, feedback, or control needed for accurate prediction." + ], + "must_not_do": [ + "Treat first-use success, visual familiarity, or confident language as proof that the actor understands capability, uncertainty, hidden action, or consequence." + ], + "evidence_required": [ + "A comprehension or prediction test in which a target actor explains what will happen, what data or authority is involved, what failure looks like, and how to intervene." + ], + "counter_signal": [ + "The actor can complete the happy path but predicts the wrong capability, state, error, data use, automation boundary, or recovery path." + ], + "human_boundary": [ + "A named human decides which complexity is essential to the product promise and which complexity must be removed rather than explained away." + ], + "stop_condition": [ + "Stop or reduce autonomy when the target actor cannot form an accurate mental model of material behavior, consequence, or intervention." + ], + "output_requirement": [ + "Emit mental_model_record with target_actor, current_expectation, conceptual_model, prediction_test, mismatch, intervention, evidence_needed, owner, and stop_condition." + ], + "source": [ + "UX3 chapter 0-2: mental model and conceptual model alignment.", + "UX3 chapter 1-3: iterative user-centered design.", + "UX3 chapter 2-3: interaction feedback and system-state understanding." + ] + }, + { + "rule_id": "ux3.rule.human_factors_load", + "title": "Human factors load", + "flow": "user_flow", + "strength": "conditional", + "trigger": [ + "A workflow has material cognitive, physical, attention, accessibility, safety, interruption, handoff, automation-bias, or recovery risk, or observed evidence shows that the target actor is overloaded or losing situation awareness." + ], + "must_inspect": [ + "The human, task, tool, and environment as one system; attention demand, working memory demand, situation awareness, action mapping, interruption, handoff, error visibility, and recovery burden." + ], + "must_do": [ + "Reduce memory-dependent action, keep material state in the world, make task progress and automation state visible, and provide a recoverable path after interruption or error." + ], + "must_not_do": [ + "Optimize the interface in isolation while ignoring the surrounding task, environment, cognitive load, automation bias, overtrust, handoff fatigue, or recovery work." + ], + "evidence_required": [ + "Observed task performance in the intended context, including attention shifts, memory failures, completion, error, hesitation, interruption, handoff, and recovery behavior." + ], + "counter_signal": [ + "The flow appears efficient in a scripted demo but fails under interruption, divided attention, real environment constraints, automation bias, overtrust, or recovery." + ], + "human_boundary": [ + "A named human accepts any residual cognitive or physical burden and confirms that safety, accessibility, and operator responsibility remain supportable." + ], + "stop_condition": [ + "Stop or simplify when material state is hidden, recovery depends on memory, or observed cognitive burden exceeds the target actor's context and capacity." + ], + "output_requirement": [ + "Emit human_factors_review with actor, task, tool, environment, attention_load, memory_load, automation_risk, interruption_path, recovery_path, observed_evidence, owner, and required_change." + ], + "source": [ + "UX3 chapter 1-7: human, task, tool, and environment system; attention, memory, situation awareness, and knowledge in the world.", + "UX3 chapter 2-3: action, feedback, mapping, and interaction principles.", + "UX3 chapter 3-8: contextual usability, effectiveness, efficiency, satisfaction, error, and recovery." + ] + }, + { + "rule_id": "ux3.rule.research_validity", + "title": "Research validity", + "flow": "evidence_flow", + "strength": "conditional", + "trigger": [ + "A decision cites an interview, survey, usability test, analytics result, field observation, experiment, synthetic user, simulation, model-generated synthesis, or research claim." + ], + "must_inspect": [ + "The research question, decision uncertainty, method fit, target actor, sample, context, attitude signal, behavior signal, comparison, bias, limitation, and disconfirming result." + ], + "must_do": [ + "Match the method to the decision uncertainty, separate exploratory from evaluative work, and distinguish attitude, behavior, qualitative meaning, and quantitative frequency. Reference canonical evidence receipts and behavior or subjective signal records instead of copying their contents into the research-validity record." + ], + "must_not_do": [ + "Use synthetic users, simulation, AI summaries, convenience samples, stated preference, or a usability test as substitutes for evidence they cannot produce. Do not duplicate evidence entries, behavior signals, subjective signals, counter-signals, or decision-impact records." + ], + "evidence_required": [ + "A research receipt naming the research question, target actor, method, sample, context, raw source, observed attitude or behavior, limitation, counter-signal, and decision impact." + ], + "counter_signal": [ + "The result changes when context, sample, task, facilitator, metric, interpretation, or comparison changes, or attitude and behavior point in different directions." + ], + "human_boundary": [ + "A named human owns method selection, interpretation, ethical treatment of participants, and any decision to proceed with known evidence limitations." + ], + "stop_condition": [ + "Stop or downgrade the claim when the method cannot answer the research question, the sample misses the target actor, raw evidence is unavailable, or simulation is presented as real-world validation." + ], + "output_requirement": [ + "Emit research_validity_record with research_question, decision_uncertainty, target_actor, method, sample, context, evidence_receipt_ids, behavior_signal_refs, subjective_signal_refs, limitation, counter_signal_refs, decision_impact_ref, and next_method." + ], + "source": [ + "UX3 chapter 1-8: research reduces uncertainty; method choice spans qualitative, quantitative, attitude, behavior, laboratory, and field work.", + "UX3 chapter 2-9: task-based prototype testing and contextual observation.", + "UX3 chapter 3-7: subjective and objective evidence have different strengths and failure modes.", + "UX3 chapter 3-8: usability evaluation is distinct from exploratory user research." + ] + }, + { + "rule_id": "ux3.rule.value_market_path", + "title": "Value-to-market path", + "flow": "business_flow", + "strength": "conditional", + "trigger": [ + "A review proposes a value proposition, product direction, market position, business model, go-to-market path, launch channel, buyer pathway, or pre-fit growth hypothesis." + ], + "must_inspect": [ + "The target actor and job, unmet need, current alternative, differentiated value, user cost, business capture, willingness signal, buyer, channel, retention mechanism, operating model, and failure threshold." + ], + "must_do": [ + "Connect target actor value to a credible exchange and market path: why the actor changes behavior, why the buyer supports it, how the channel reaches them, and what repeated use or retention would mean. This is a pre-fit path review, not a product-market fit verdict." + ], + "must_not_do": [ + "Start from monetization mechanics, feature novelty, total market size, generated traffic, or a preferred channel without proving target value and behavior change. Do not use this rule to validate a product-market fit claim; activate ux3.rule.false_product_market_fit instead." + ], + "evidence_required": [ + "A target-actor receipt showing current alternative, experienced cost, willingness or costly behavior, differentiated value, buyer or budget signal, reachable channel, and retention or repeat-use hypothesis." + ], + "counter_signal": [ + "The current alternative is sufficient, the user and buyer value different outcomes, willingness disappears outside a subsidized channel, acquisition does not lead to retention, or the value can be copied without workflow depth." + ], + "human_boundary": [ + "A named human owns positioning, pricing ethics, strategic market choice, acceptable subsidy, brand promise, and any decision to explore before market evidence is strong." + ], + "stop_condition": [ + "Stop or reframe when no target actor changes meaningful behavior, no credible buyer or channel exists, the exchange hides unacceptable cost, or the proposed retention mechanism lacks a testable cause." + ], + "output_requirement": [ + "Emit value_market_path_record with target_actor, job, current_alternative, unmet_need, differentiated_value, user_cost, business_capture, buyer, willingness_signal, channel, retention_hypothesis, counter_signal, owner, and next_market_test." + ], + "source": [ + "UX3 chapter 1-5: positioning requires wanted, differentiated, and profitable value.", + "UX3 chapter 1-9: value proposition connects user need, product promise, and exchange.", + "UX3 chapter 2-2: product design decisions depend on the complete business model.", + "UX3 chapter 3-1: go-to-market is the activation plan for product-market fit.", + "UX3 chapter 3-2: acquisition, activation, retention, referral, revenue, and growth loops." + ] + }, + { + "rule_id": "ux3.rule.human_agent_interaction", + "title": "Human-agent interaction", + "flow": "cross_flow", + "strength": "conditional", + "trigger": [ + "A machine actor interprets intent, proposes or changes a plan, calls a tool, transforms data, makes a recommendation, takes action, or hands work back to a person." + ], + "must_inspect": [ + "User intent, plan visibility, system status, uncertainty, authority, data use, tool action, approval point, interrupt, correct, undo, log, handoff, failure state, recovery path, and accountable owner." + ], + "must_do": [ + "Keep material intent, plan, action, state, and consequence inspectable; provide interrupt, correct, undo, or approve controls in proportion to risk; preserve a readable log and a visible recovery surface. When authority or high-risk rules also trigger, reference their canonical records instead of copying permission, approval, owner, trace, rollback, or operational recovery fields." + ], + "must_not_do": [ + "Hide a material plan or tool action behind conversational fluency, treat generated text as informed consent, or make completion easier than correction, refusal, exit, or recovery. Do not duplicate authority_boundary, high_risk_action_bundle, or recovery_path records inside the interaction contract." + ], + "evidence_required": [ + "A scenario-based interaction test showing that the target actor can predict the next action, inspect the plan, approve or refuse when required, interrupt, correct, undo where feasible, read the log, and recover from failure." + ], + "counter_signal": [ + "The happy path succeeds but the actor cannot see what the agent did, detect a wrong assumption, stop execution, correct state, understand a handoff, or recover without expert support." + ], + "human_boundary": [ + "A named human defines which actions require approval, which consequences are unacceptable, which records must remain legible, and who is responsible when the agent is wrong." + ], + "stop_condition": [ + "Stop or reduce agent authority when material intent, plan, status, approval, interrupt, correction, log, accountability, or recovery is absent or untested." + ], + "output_requirement": [ + "Emit interaction_contract with target_actor, intent, visible_plan, visible_status, approval_surface, interrupt_path, correct_path, undo_path, log_surface, failure_state, recovery_surface, handoff, test_evidence, authority_boundary_ref when minimum authority is triggered, and high_risk_action_bundle_ref when high risk is triggered." + ], + "source": [ + "UX3 chapter 2-3: action, feedback, mapping, visibility, and system-state interaction principles.", + "UX3 chapter 2-4: information architecture connects user, content, context, and decision information.", + "UX3 chapter 2-6: interface principles reduce learning cost and make feedback understandable.", + "UX3 chapter 3-3: touchpoints form one connected journey across channels and devices.", + "UX3 chapter 3-4: each touchpoint must align actor, motivation, device, information, persuasion, guidance, and friendliness." + ] + }, + { + "rule_id": "ux3.rule.motivation_ethics", + "title": "Motivation ethics", + "flow": "cross_flow", + "strength": "conditional", + "trigger": [ + "A product uses retention, notification, personalization, recommendation, streaks, rewards, scarcity, social pressure, loss framing, gamification, or adaptive difficulty to change repeated behavior." + ], + "must_inspect": [ + "The target behavior, intrinsic and extrinsic motivation, user benefit, business benefit, friction, frequency, vulnerable actors, personalization inputs, social pressure, loss mechanism, consent, exit, and long-term autonomy." + ], + "must_do": [ + "Make the intended behavior and exchange legible, preserve meaningful choice and exit, limit pressure and personalization, and test whether repeated use still serves the target actor's stated goal." + ], + "must_not_do": [ + "Treat engagement, time spent, return frequency, conversion, or reward response as sufficient when the mechanism exploits vulnerability, obscures cost, weakens autonomy, or makes exit harder." + ], + "evidence_required": [ + "Behavioral and subjective evidence covering benefit, regret, trust, pressure, unintended use, vulnerable-group impact, opt-out or exit behavior, and whether intrinsic motivation survives removal of extrinsic rewards." + ], + "counter_signal": [ + "Engagement rises while trust, goal completion, wellbeing, informed choice, intrinsic motivation, or willingness to continue without pressure declines." + ], + "human_boundary": [ + "A named human owns the ethical limit on manipulation, vulnerable-group protection, acceptable pressure, pricing and reward fairness, personalization depth, and removal or exit rights." + ], + "stop_condition": [ + "Stop or redesign when the mechanism depends on concealed cost, coercive loss, vulnerable-user exploitation, non-consensual personalization, blocked exit, or engagement that conflicts with the actor's goal." + ], + "output_requirement": [ + "Emit motivation_ethics_review with target_behavior, intrinsic_motivation, extrinsic_motivation, user_benefit, business_benefit, vulnerable_groups, manipulation_risk, personalization_scope, pressure_limit, consent, exit_path, counter_signal, owner, and redesign_condition." + ], + "source": [ + "UX3 chapter 3-5: retention depends on motivation, reinforcement, lifetime value, recommendation, and ethical restraint against addiction.", + "UX3 chapter 3-6: gamification aligns challenge, ability, trigger, intrinsic and extrinsic motivation, reward, and player type." + ] + }, + { + "rule_id": "ux3.rule.human_judgment", + "title": "Human judgment", + "flow": "cross_flow", + "strength": "required", + "trigger": [ + "A decision depends on taste, ethics, meaning, brand feel, strategic appetite, risk appetite, accountability, or final responsibility." + ], + "must_inspect": [ + "Which part is evidence, which part is interpretation, which part is human taste or responsibility, and who owns the call." + ], + "must_do": [ + "Record human taste and judgment as accountable input, never as an evidence score." + ], + "must_not_do": [ + "Convert taste, ethics, meaning, or final responsibility into a mechanical confidence score or hidden agent decision." + ], + "evidence_required": [ + "Named human owner, decision statement, evidence considered, accountable rationale, bounded action, and reversal condition." + ], + "counter_signal": [ + "The review hides taste inside evidence language, lacks a named owner, or lets a machine decide an accountable human trade-off." + ], + "human_boundary": [ + "Taste, ethics, meaning, strategic appetite, risk appetite, and final responsibility remain owned by a named person." + ], + "stop_condition": [ + "Stop when a human-owned decision is required but no named accountable human decision record exists." + ], + "output_requirement": [ + "Emit human_judgment_record with owner, judgment_type, decision, evidence_considered, bounded_action, reversal_condition, and accountability_note." + ], + "source": [ + "UX3 canonical model: Human taste is accountable input, not an evidence score." + ] + } + ] +} diff --git a/skills/product-design-harness/resources/knowledge/source-chapters.json b/skills/product-design-harness/resources/knowledge/source-chapters.json new file mode 100644 index 000000000..3beba0684 --- /dev/null +++ b/skills/product-design-harness/resources/knowledge/source-chapters.json @@ -0,0 +1,104 @@ +{ + "schema_version": "1.0.0", + "corpus_id": "ux3-original-curriculum-stage-0-3", + "source_document": "UX3 Knowledge System Complete Extraction", + "source_sha256": "fabf929c6fe03b67edfd25be8b79991da5056578c7a7fabbd3b709b4a88f50d2", + "source_note": "The original corpus has 40 chapter positions; chapter 3-12 has a title but no substantive transcript. This manifest lists only chapters cited by the six newly distilled rules.", + "chapters": [ + { + "chapter_id": "0-2", + "title": "UX design thinking and logic", + "content_status": "substantive" + }, + { + "chapter_id": "1-3", + "title": "User-centered design", + "content_status": "substantive" + }, + { + "chapter_id": "1-5", + "title": "Market positioning and competitor analysis", + "content_status": "substantive" + }, + { + "chapter_id": "1-7", + "title": "Human factors and product design", + "content_status": "substantive" + }, + { + "chapter_id": "1-8", + "title": "User research and needs analysis", + "content_status": "substantive" + }, + { + "chapter_id": "1-9", + "title": "Product value proposition", + "content_status": "substantive" + }, + { + "chapter_id": "2-2", + "title": "Product and business model", + "content_status": "substantive" + }, + { + "chapter_id": "2-3", + "title": "Introduction to human-computer interaction", + "content_status": "substantive" + }, + { + "chapter_id": "2-4", + "title": "Information architecture and functional design", + "content_status": "substantive" + }, + { + "chapter_id": "2-6", + "title": "Interface design principles", + "content_status": "substantive" + }, + { + "chapter_id": "2-9", + "title": "Prototype testing", + "content_status": "substantive" + }, + { + "chapter_id": "3-1", + "title": "Go-to-market strategy", + "content_status": "substantive" + }, + { + "chapter_id": "3-2", + "title": "Product growth thinking", + "content_status": "substantive" + }, + { + "chapter_id": "3-3", + "title": "End-to-end channel thinking", + "content_status": "substantive" + }, + { + "chapter_id": "3-4", + "title": "First-use experience design", + "content_status": "substantive" + }, + { + "chapter_id": "3-5", + "title": "Return motivation and loyalty engineering", + "content_status": "substantive" + }, + { + "chapter_id": "3-6", + "title": "Gamification design", + "content_status": "substantive" + }, + { + "chapter_id": "3-7", + "title": "Computational design thinking", + "content_status": "substantive" + }, + { + "chapter_id": "3-8", + "title": "Usability engineering", + "content_status": "substantive" + } + ] +} diff --git a/skills/product-design-harness/resources/prompts/README.md b/skills/product-design-harness/resources/prompts/README.md new file mode 100644 index 000000000..042366872 --- /dev/null +++ b/skills/product-design-harness/resources/prompts/README.md @@ -0,0 +1,11 @@ +# Prompts + +| File | Use | +|---|---| +| `start-review.md` | Choose mode and start the harness. | +| `mode-selector.md` | Select Quick Gate, Standard Gate, or UX3 Council, or route to context-pack handoff. | +| `intake.md` | Turn a vague idea into a reviewable hypothesis. | +| `gate-review.md` | Run the full UX3 review. | +| `claim-analysis.md` | Break broad product ideas into testable claims. | +| `ux3-council.md` | Run stage, claim, flow, uncertainty, and council review. | +| `red-team.md` | Challenge an overly convincing product plan. | diff --git a/skills/product-design-harness/resources/prompts/claim-analysis.md b/skills/product-design-harness/resources/prompts/claim-analysis.md new file mode 100644 index 000000000..3da2b5ba8 --- /dev/null +++ b/skills/product-design-harness/resources/prompts/claim-analysis.md @@ -0,0 +1,31 @@ +# Claim Analysis Prompt + +Use this when a product direction sounds attractive but broad. + +## Prompt + +Break the product direction into user, evidence, business, risk, and taste +claims. Do not propose solutions. + +For each claim, return `schemas/claim.schema.json`: + +- stable claim identifier +- one testable claim +- current support +- counter-signal +- confidence level +- depends_on edges +- breaks_if_false edges +- smallest proof step +- stop condition + +Then identify: + +| Field | Required answer | +|---|---| +| Riskiest claim | The claim whose failure changes the decision most. | +| Critical path | The dependency chain that can collapse the direction. | +| Highest-leverage proof step | The smallest test that changes the most claims. | +| Human-owned decision | Taste, risk, strategy, ethics, meaning, or none. | + +Use docs/CLAIMS.md for decomposition rules. diff --git a/skills/product-design-harness/resources/prompts/gate-review.md b/skills/product-design-harness/resources/prompts/gate-review.md new file mode 100644 index 000000000..e69b5e452 --- /dev/null +++ b/skills/product-design-harness/resources/prompts/gate-review.md @@ -0,0 +1,61 @@ +# Gate Review Prompt + +Use this before design, implementation, prototype, launch, or growth work. + +## Prompt + +Run a Product Design Harness gate review. Do not implement. + +Use the already-loaded `schemas/session-config.schema.json`, +`knowledge/ontology.json`, and triggered `knowledge/rules.json` entries. Keep +the response in `working_language` while keeping schema fields, rule IDs, and +Flow identifiers canonical. + +Review User Flow, Evidence Flow, and Business Flow independently. + +Each lane must return the fields in +`schemas/reviewer-verdict.schema.json`. For a Standard Gate, use +`review_round: independent` and omit `objection_to`, `counter_evidence`, +and `position_change`; those fields exist only in the challenge round. +Explain the counter-evidence search in `disconfirming_evidence`. + +Reviewer verdicts are working artifacts, not the final shape. When you +assemble `schemas/review-result.schema.json`, reduce each lane to exactly +the canonical lane fields: `verdict`, `evidence_tier`, `strongest_signal`, +`weakest_assumption`, `missing_evidence`, `disconfirming_evidence`, +`stop_condition`, plus `stop_reason_class` when and only when that lane +verdict is `stop_reframe`. Never copy `reviewer`, `review_round`, +`confidence_level`, or `next_smallest_action` into `reviews.*`; the +canonical contract rejects them. + +Then apply the weakest-flow rule: + +| Lane state | Combined verdict | +|---|---| +| Any lane `stop_reframe`, for any reason | `stop_reframe` | +| At least one `verify` and no stop | `verify` | +| All three `continue` | `continue` | + +Select `weakest_flow` deterministically: the most severe lane verdict +(`stop_reframe` > `verify` > `continue`); ties break to the lowest lane +`evidence_tier`, then to the fixed priority evidence, user, business. + +Return the final result as `schemas/review-result.schema.json`. + +Rules: + +- Reversibility lowers mode, not the review requirement. +- List disconfirming evidence before support. +- Use evidence tier, not confidence alone, to bound action. The contract + enforces the floor: `t0` headline evidence forces `stop_reframe`, and + `t1` can never return `continue`. +- Do not average verdicts. +- `continue` creates a context pack; continue plus a valid context pack authorizes implementation. +- `verify` creates one proof step; verify authorizes only the exact proof_step and never general coding. +- `stop_reframe` creates one better product question. +- Every branch must state `may_do`, `must_not_do`, and `must_ask`. +- Product organization, issuer, stakeholder effects, and accountable owner must + be present before any handoff. +- Designer taste stays a human-owned input and never upgrades evidence. +- Post-build feedback must be classified with + ux3.rule.feedback_classification before it changes scope. diff --git a/skills/product-design-harness/resources/prompts/intake.md b/skills/product-design-harness/resources/prompts/intake.md new file mode 100644 index 000000000..32e315823 --- /dev/null +++ b/skills/product-design-harness/resources/prompts/intake.md @@ -0,0 +1,34 @@ +# Intake Prompt + +Use this when a product idea is vague. + +## Prompt + +Do not propose features. + +Fill `schemas/product-brief.schema.json` or its human-readable companion +`templates/product-brief.md`. + +Use `working_language` for prose and keep canonical identifiers in English. +Use `knowledge/ontology.json` for actor and stakeholder terms, then load only +triggered rule IDs from `knowledge/rules.json`. + +Required decisions: + +| Field | Required answer | +|---|---| +| stage | idea / prototype / launch / scale | +| actor_boundary | Operator, beneficiary, affected people, excluded groups. | +| product_organization | Organization, project owner, issuer, and decision authority. | +| stakeholder_effects | Who receives value, pays, decides, operates, or bears risk. | +| problem_hypothesis | Actor, situation, frequency, consequence, workaround, evidence standard. | +| evidence_tier | t0 / t1 / t2 / t3 / t4 | +| riskiest_claim | The belief most likely to change the direction. | +| disconfirming_evidence | What would prove the problem or direction wrong. | +| accountable_owner | Who owns the final human decision. | +| human_taste | Named human-owned taste input, if any; do not score it as evidence. | +| feedback_classification | Evidence, noise, incident, drift, or not_applicable. | +| execution_boundary | `may_do`, `must_not_do`, and `must_ask`. | +| next_question | One question that reduces the most uncertainty. | + +Then run `prompts/mode-selector.md`. Do not write an execution plan. diff --git a/skills/product-design-harness/resources/prompts/mode-selector.md b/skills/product-design-harness/resources/prompts/mode-selector.md new file mode 100644 index 000000000..75b9055f1 --- /dev/null +++ b/skills/product-design-harness/resources/prompts/mode-selector.md @@ -0,0 +1,42 @@ +# Mode Selector Prompt + +Use this to choose the smallest review process that is still responsible. + +## Prompt + +Select the Product Design Harness mode. + +Answer the questions: + +| Question | Answer | +|---|---| +| Is the next step reversible? | Yes / No / Unknown | +| Is user harm possible? | Yes / No / Unknown | +| Is business cost high? | Yes / No / Unknown | +| Is external evidence needed? | Yes / No / Unknown | +| Are multiple stakeholders affected? | Yes / No / Unknown | +| Is the product direction still vague? | Yes / No / Unknown | +| Is this a new feature or workflow, rather than a small bounded change? | Yes / No / Unknown | + +Return: + +| Field | Required answer | +|---|---| +| Mode | Quick Gate, Standard Gate, or UX3 Council. | +| Why this mode | One sentence. | +| Evidence bar | What evidence is needed before the next step. | +| Human gate needed | Yes or No. | +| Next file | Prompt or template to use next. | + +Rules: + +- If risk is high or reversibility is low, choose UX3 Council. +- If the direction is vague, choose Standard Gate and complete the product brief. +- If the work is a new feature, workflow, or experiment, choose Standard Gate. +- Choose Quick Gate only for a small, reversible, bounded change to an + existing flow. +- Do not choose Quick Gate for irreversible or high-risk work. + +Handoff is not a review mode. If a valid `continue` review-result already +exists, skip mode selection and produce a context pack from +`../templates/context-pack.md`; no new review-result is created. diff --git a/skills/product-design-harness/resources/prompts/red-team.md b/skills/product-design-harness/resources/prompts/red-team.md new file mode 100644 index 000000000..35f694182 --- /dev/null +++ b/skills/product-design-harness/resources/prompts/red-team.md @@ -0,0 +1,28 @@ +# Red-Team Prompt + +Use this when a product plan sounds convincing. + +## Prompt + +Red-team this product direction using Product Design Harness. + +Do not list supporting reasons first. + +Start with: + +| Field | Required answer | +|---|---| +| Five failure modes | Ways this direction can fail. | +| Disconfirming tests | Evidence that would prove it wrong. | +| Hidden affected people | People affected without direct operation. | +| Current workaround | What users do today instead. | +| Substitute threats | Direct, indirect, platform, workflow, and doing-nothing substitutes. | +| Trust risk | What could damage confidence or dignity. | +| Stop condition | What should block execution. | + +Then provide a verdict using `continue`, `verify`, or `stop_reframe` as a +valid `schemas/red-team-review.schema.json` object. Include the claim IDs and +evidence receipt IDs that the challenge relies on. + +When all three independent Council reviewers returned continue, attach this +object as council_input.red_team_review before the facilitator synthesizes. diff --git a/skills/product-design-harness/resources/prompts/start-review.md b/skills/product-design-harness/resources/prompts/start-review.md new file mode 100644 index 000000000..43eeadc17 --- /dev/null +++ b/skills/product-design-harness/resources/prompts/start-review.md @@ -0,0 +1,57 @@ +# Start Review Prompt + +Use this as the first prompt for Product Design Harness. + +## Prompt + +Start a Product Design Harness review. + +Do not implement. + +Load first, in order: + +1. `schemas/session-config.schema.json` to set `working_language` while + keeping canonical identifiers in English. +2. `knowledge/ontology.json` as the canonical UX3 knowledge kernel. +3. `knowledge/rules.json`, including required rules and only conditional rules + triggered by the request. +4. This start-review prompt. + +First choose the review mode: + +| Mode | Use when | +|---|---| +| Quick Gate | Small reversible change. | +| Standard Gate | New feature, workflow, or experiment. | +| UX3 Council | High uncertainty, external evidence, multiple reviewers, or human-owned trade-off. | + +Reversibility lowers mode, not the review requirement. + +If a previous review already returned continue with a valid context pack, +skip mode selection and reuse that context pack; no new review is created. + +Then produce: + +| Field | Required answer | +|---|---| +| Selected mode | Quick Gate, Standard Gate, or UX3 Council. | +| Reason | Why this mode fits. | +| Missing intake | Any required information not supplied. | +| Next prompt | Which prompt should run next. | + +Required intake includes product organization, issuer, stakeholder effects, +and accountable owner. If any are missing, list them before handoff. + +If the request is vague, first fill `templates/product-brief.md`. + +If the mode is UX3 Council, run `prompts/ux3-council.md`. + +If the verdict becomes Continue, create `templates/context-pack.md`. +continue plus a valid context pack authorizes implementation. + +If the verdict becomes Verify, run only the returned `proof_step`. +verify authorizes only the exact proof_step and never general coding. + +Every completed review must return +`schemas/review-result.schema.json`. Do not invent a different output shape. +Every result must include `may_do`, `must_not_do`, and `must_ask`. diff --git a/skills/product-design-harness/resources/prompts/ux3-council.md b/skills/product-design-harness/resources/prompts/ux3-council.md new file mode 100644 index 000000000..9a3f1853c --- /dev/null +++ b/skills/product-design-harness/resources/prompts/ux3-council.md @@ -0,0 +1,44 @@ +# UX3 Council Prompt + +Use this for high-uncertainty or high-impact product work before execution. + +## Prompt + +Run a UX3 Product Design Harness council. Do not implement. + +1. Identify stage and risk class. +2. Run claim analysis and create dependency edges. +3. Retrieve missing evidence with + `schemas/evidence-request.schema.json` and + `schemas/evidence-response.schema.json`. +4. Fork User, Evidence, and Business reviewers in parallel (or rotate + roles in one context, writing each lane's JSON before reading the next + brief). If all three lanes return continue, run `red-team.md` and give + its `schemas/red-team-review.schema.json` output to the facilitator as + council_input.red_team_review before synthesis. +5. Wait until all three independent reviews validate against + `schemas/reviewer-verdict.schema.json`. Those verdicts are working +artifacts: when the facilitator assembles the final +`schemas/review-result.schema.json`, each lane is reduced to the canonical +lane fields (`verdict`, `evidence_tier`, `strongest_signal`, +`weakest_assumption`, `missing_evidence`, `disconfirming_evidence`, +`stop_condition`, and `stop_reason_class` only on a `stop_reframe` +verdict); reviewer-verdict-only fields never appear inside `reviews.*`. +6. Run a challenge round. Each reviewer must name `objection_to`, + `counter_evidence`, and `position_change`. +7. Run Uncertainty Reviewer on evidence tier, freshness, risk, and + reversibility. +8. Run Council Facilitator only after the join barrier. +9. Route taste, risk, strategy, ethics, or meaning to Human Judgment Gate. +10. Return `schemas/review-result.schema.json`. + +Rules: + +- Do not average verdicts. +- Do not synthesize before all three lane reviews and challenge outputs exist. +- A connector, search result, or external tool cannot provide a verdict. +- Evidence tier controls action size. +- Confidence cannot upgrade evidence. +- An expired source must be re-verified or downgraded. +- A human-owned decision requires an accountable owner. +- Only `continue` creates a context pack. diff --git a/skills/product-design-harness/resources/requirements-dev.txt b/skills/product-design-harness/resources/requirements-dev.txt new file mode 100644 index 000000000..3ee1ea1a4 --- /dev/null +++ b/skills/product-design-harness/resources/requirements-dev.txt @@ -0,0 +1 @@ +jsonschema==4.26.0 diff --git a/skills/product-design-harness/resources/schemas/README.md b/skills/product-design-harness/resources/schemas/README.md new file mode 100644 index 000000000..5e04deb02 --- /dev/null +++ b/skills/product-design-harness/resources/schemas/README.md @@ -0,0 +1,24 @@ +# Schemas + +These schemas define machine-checkable Product Design Harness outputs. + +| File | Use | +|---|---| +| `actor-boundary.schema.json` | Shared actor boundary reused by product brief, review result, and context pack. | +| `claim-analysis.schema.json` | Claim graph and critical path. | +| `claim.schema.json` | Claim analysis item. | +| `context-pack.schema.json` | Handoff after Continue. | +| `council-input.schema.json` | Join-barrier input for council synthesis. | +| `decision-rule.schema.json` | Machine-readable UX3 decision rule. | +| `evidence-request.schema.json` | Request contract for external evidence retrieval. | +| `evidence-response.schema.json` | Response contract for external evidence retrieval. | +| `evidence.schema.json` | Evidence receipt with provenance and freshness. | +| `human-decision.schema.json` | Human-owned decision record. | +| `verdict-override.schema.json` | Authorizes execution despite a verdict; never edits the review. | +| `ontology.schema.json` | Machine-readable UX3 ontology. | +| `product-brief.schema.json` | Machine-readable intake. | +| `red-team-review.schema.json` | Structured counter-case required when every independent Council lane continues. | +| `review-result.schema.json` | Canonical final result for every review mode. | +| `reviewer-verdict.schema.json` | Individual reviewer output per round; summarized into the canonical result's lane reviews. | +| `session-config.schema.json` | Working-language session configuration. | +| `uncertainty-review.schema.json` | Evidence tier, risk, reversibility, and proof bar. | diff --git a/skills/product-design-harness/resources/schemas/actor-boundary.schema.json b/skills/product-design-harness/resources/schemas/actor-boundary.schema.json new file mode 100644 index 000000000..220846240 --- /dev/null +++ b/skills/product-design-harness/resources/schemas/actor-boundary.schema.json @@ -0,0 +1,51 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://cis2042.github.io/ux3-product-design-harness/schemas/actor-boundary.schema.json", + "title": "Product Design Harness Actor Boundary", + "type": "object", + "additionalProperties": false, + "required": [ + "target_population", + "operator", + "beneficiary", + "machine_actor", + "affected_people", + "excluded_groups" + ], + "properties": { + "target_population": { + "type": "array", + "items": { + "type": "string", + "minLength": 1 + }, + "minItems": 1 + }, + "operator": { + "type": "string", + "minLength": 1 + }, + "beneficiary": { + "type": "string", + "minLength": 1 + }, + "machine_actor": { + "type": "string", + "minLength": 1 + }, + "affected_people": { + "type": "array", + "items": { + "type": "string", + "minLength": 1 + } + }, + "excluded_groups": { + "type": "array", + "items": { + "type": "string", + "minLength": 1 + } + } + } +} diff --git a/skills/product-design-harness/resources/schemas/claim-analysis.schema.json b/skills/product-design-harness/resources/schemas/claim-analysis.schema.json new file mode 100644 index 000000000..5b4bc6007 --- /dev/null +++ b/skills/product-design-harness/resources/schemas/claim-analysis.schema.json @@ -0,0 +1,32 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://cis2042.github.io/ux3-product-design-harness/schemas/claim-analysis.schema.json", + "title": "Product Design Harness Claim Analysis", + "type": "object", + "additionalProperties": false, + "required": [ + "claims", + "riskiest_claim_id", + "critical_path", + "highest_leverage_proof_step", + "human_owned_decision" + ], + "properties": { + "claims": { + "type": "array", + "items": { "$ref": "claim.schema.json" }, + "minItems": 1 + }, + "riskiest_claim_id": { "type": "string", "minLength": 1 }, + "critical_path": { + "type": "array", + "items": { "type": "string" }, + "minItems": 1 + }, + "highest_leverage_proof_step": { "type": "string", "minLength": 1 }, + "human_owned_decision": { + "type": "string", + "enum": ["taste", "risk", "strategy", "ethics", "meaning", "none"] + } + } +} diff --git a/skills/product-design-harness/resources/schemas/claim.schema.json b/skills/product-design-harness/resources/schemas/claim.schema.json new file mode 100644 index 000000000..ab26408b4 --- /dev/null +++ b/skills/product-design-harness/resources/schemas/claim.schema.json @@ -0,0 +1,117 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://cis2042.github.io/ux3-product-design-harness/schemas/claim.schema.json", + "title": "Product Design Harness Claim", + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "type", + "claim", + "status", + "support", + "counter_signal", + "confidence_level", + "depends_on", + "breaks_if_false", + "proof_step", + "stop_condition" + ], + "properties": { + "id": { + "type": "string", + "minLength": 1 + }, + "type": { + "type": "string", + "enum": [ + "user", + "evidence", + "business", + "risk", + "taste" + ] + }, + "claim": { + "type": "string", + "minLength": 1 + }, + "status": { + "type": "string", + "enum": [ + "assumption", + "verified" + ], + "description": "Whether this claim is still an assumption or verified by evidence." + }, + "support": { + "type": "string" + }, + "evidence_ids": { + "type": "array", + "items": { + "type": "string", + "minLength": 1 + }, + "description": "Evidence receipt ids that support this claim." + }, + "counter_signal": { + "type": "string" + }, + "confidence_level": { + "type": "string", + "enum": [ + "very_low", + "low", + "medium", + "high", + "very_high" + ] + }, + "depends_on": { + "type": "array", + "items": { + "type": "string", + "minLength": 1 + } + }, + "breaks_if_false": { + "type": "array", + "items": { + "type": "string", + "minLength": 1 + }, + "minItems": 1 + }, + "proof_step": { + "type": "string" + }, + "stop_condition": { + "type": "string" + } + }, + "allOf": [ + { + "if": { + "properties": { + "status": { + "const": "verified" + } + }, + "required": [ + "status" + ] + }, + "then": { + "required": [ + "evidence_ids" + ], + "properties": { + "evidence_ids": { + "minItems": 1 + } + } + } + } + ] +} diff --git a/skills/product-design-harness/resources/schemas/context-pack.schema.json b/skills/product-design-harness/resources/schemas/context-pack.schema.json new file mode 100644 index 000000000..11022f8b8 --- /dev/null +++ b/skills/product-design-harness/resources/schemas/context-pack.schema.json @@ -0,0 +1,284 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://cis2042.github.io/ux3-product-design-harness/schemas/context-pack.schema.json", + "title": "Product Design Harness Context Pack", + "type": "object", + "additionalProperties": false, + "required": [ + "schema_version", + "session_config", + "review_id", + "goal", + "stage", + "combined_verdict", + "actor_boundary", + "product_organization", + "stakeholder_effects", + "human_judgment_boundary", + "unresolved_assumptions", + "scope", + "non_goals", + "acceptance_criteria", + "measurement_hooks", + "evidence_snapshot_ids", + "rollback_plan", + "human_approval_gates", + "high_risk_actions", + "stop_conditions", + "execution_boundary" + ], + "properties": { + "schema_version": { + "const": "2.1" + }, + "session_config": { + "$ref": "session-config.schema.json" + }, + "review_id": { + "type": "string", + "minLength": 1 + }, + "goal": { + "type": "string", + "minLength": 1 + }, + "stage": { + "type": "string", + "enum": [ + "idea", + "prototype", + "launch", + "scale" + ] + }, + "combined_verdict": { + "type": "string", + "const": "continue" + }, + "actor_boundary": { + "$ref": "actor-boundary.schema.json" + }, + "product_organization": { + "type": "object", + "additionalProperties": false, + "required": [ + "organization", + "project_owner", + "issuer" + ], + "properties": { + "organization": { + "type": "string", + "minLength": 1 + }, + "project_owner": { + "type": "string", + "minLength": 1 + }, + "issuer": { + "type": "string", + "minLength": 1 + } + } + }, + "stakeholder_effects": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": false, + "required": [ + "stakeholder", + "effect" + ], + "properties": { + "stakeholder": { + "type": "string", + "minLength": 1 + }, + "effect": { + "type": "string", + "minLength": 1 + } + } + }, + "minItems": 1 + }, + "unresolved_assumptions": { + "$ref": "#/$defs/non_empty_string_list" + }, + "human_judgment_boundary": { + "type": "object", + "additionalProperties": false, + "required": [ + "human_owned_decisions", + "machine_supported_inputs", + "not_mechanized", + "approval_gates" + ], + "properties": { + "human_owned_decisions": { + "$ref": "#/$defs/string_list" + }, + "machine_supported_inputs": { + "$ref": "#/$defs/string_list" + }, + "not_mechanized": { + "$ref": "#/$defs/string_list" + }, + "approval_gates": { + "$ref": "#/$defs/named_human_gates" + } + } + }, + "scope": { + "$ref": "#/$defs/non_empty_string_list" + }, + "non_goals": { + "$ref": "#/$defs/string_list" + }, + "acceptance_criteria": { + "$ref": "#/$defs/non_empty_string_list" + }, + "measurement_hooks": { + "$ref": "#/$defs/string_list" + }, + "evidence_snapshot_ids": { + "$ref": "#/$defs/string_list" + }, + "rollback_plan": { + "type": "string", + "minLength": 1 + }, + "human_approval_gates": { + "$ref": "#/$defs/named_human_gates" + }, + "high_risk_actions": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": false, + "required": [ + "action", + "approval_gate", + "rollback_plan" + ], + "properties": { + "action": { + "type": "string", + "minLength": 1 + }, + "approval_gate": { + "$ref": "#/$defs/named_human_gate" + }, + "rollback_plan": { + "type": "string", + "minLength": 1 + } + } + } + }, + "stop_conditions": { + "$ref": "#/$defs/non_empty_string_list" + }, + "execution_boundary": { + "type": "object", + "additionalProperties": false, + "required": [ + "may_do", + "must_not_do", + "must_ask" + ], + "properties": { + "may_do": { + "$ref": "#/$defs/non_empty_string_list" + }, + "must_not_do": { + "$ref": "#/$defs/non_empty_string_list" + }, + "must_ask": { + "$ref": "#/$defs/non_empty_string_list" + } + } + } + }, + "allOf": [ + { + "if": { + "properties": { + "execution_boundary": { + "properties": { + "may_do": { + "contains": { + "type": "string", + "pattern": "([Cc]ustomer-facing|[Pp]ermissions|[Dd]ata handling|[Pp]roduction schema|[Ee]xternal action|[Rr]emove human approval|[Aa]utonomous)" + } + } + }, + "required": [ + "may_do" + ] + } + }, + "required": [ + "execution_boundary" + ] + }, + "then": { + "properties": { + "high_risk_actions": { + "minItems": 1 + } + }, + "required": [ + "high_risk_actions" + ] + } + } + ], + "$defs": { + "string_list": { + "type": "array", + "items": { + "type": "string", + "minLength": 1 + } + }, + "non_empty_string_list": { + "type": "array", + "items": { + "type": "string", + "minLength": 1 + }, + "minItems": 1 + }, + "named_human_gates": { + "type": "array", + "items": { + "$ref": "#/$defs/named_human_gate" + } + }, + "named_human_gate": { + "type": "object", + "additionalProperties": false, + "required": [ + "gate_id", + "accountable_owner", + "condition" + ], + "properties": { + "gate_id": { + "type": "string", + "minLength": 1 + }, + "accountable_owner": { + "type": "string", + "minLength": 1 + }, + "condition": { + "type": "string", + "minLength": 1 + } + } + } + } +} diff --git a/skills/product-design-harness/resources/schemas/council-input.schema.json b/skills/product-design-harness/resources/schemas/council-input.schema.json new file mode 100644 index 000000000..b448e208b --- /dev/null +++ b/skills/product-design-harness/resources/schemas/council-input.schema.json @@ -0,0 +1,83 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://cis2042.github.io/ux3-product-design-harness/schemas/council-input.schema.json", + "title": "Product Design Harness Council Input", + "type": "object", + "additionalProperties": false, + "required": [ + "product_brief", + "claim_analysis", + "independent_reviews", + "challenge_reviews", + "uncertainty_review" + ], + "properties": { + "product_brief": { "$ref": "product-brief.schema.json" }, + "claim_analysis": { "$ref": "claim-analysis.schema.json" }, + "independent_reviews": { + "$ref": "#/$defs/flow_reviews", + "items": { + "$ref": "reviewer-verdict.schema.json", + "properties": { "review_round": { "const": "independent" } } + } + }, + "challenge_reviews": { + "$ref": "#/$defs/flow_reviews", + "items": { + "$ref": "reviewer-verdict.schema.json", + "properties": { "review_round": { "const": "challenge" } } + } + }, + "uncertainty_review": { "$ref": "uncertainty-review.schema.json" }, + "red_team_review": { "$ref": "red-team-review.schema.json" } + }, + "$defs": { + "flow_reviews": { + "type": "array", + "minItems": 3, + "maxItems": 3, + "allOf": [ + { + "contains": { + "required": ["reviewer"], + "properties": { "reviewer": { "const": "user_flow" } } + } + }, + { + "contains": { + "required": ["reviewer"], + "properties": { "reviewer": { "const": "evidence_flow" } } + } + }, + { + "contains": { + "required": ["reviewer"], + "properties": { "reviewer": { "const": "business_flow" } } + } + } + ] + } + }, + "allOf": [ + { + "if": { + "required": ["independent_reviews"], + "properties": { + "independent_reviews": { + "contains": { + "type": "object", + "required": ["verdict"], + "properties": { + "verdict": { "const": "continue" } + } + }, + "minContains": 3 + } + } + }, + "then": { + "required": ["red_team_review"] + } + } + ] +} diff --git a/skills/product-design-harness/resources/schemas/decision-rule.schema.json b/skills/product-design-harness/resources/schemas/decision-rule.schema.json new file mode 100644 index 000000000..693ffde32 --- /dev/null +++ b/skills/product-design-harness/resources/schemas/decision-rule.schema.json @@ -0,0 +1,121 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://cis2042.github.io/ux3-product-design-harness/schemas/decision-rule.schema.json", + "title": "UX3 Decision Rule", + "type": "object", + "additionalProperties": false, + "required": [ + "rule_id", + "title", + "flow", + "strength", + "trigger", + "must_inspect", + "must_do", + "must_not_do", + "evidence_required", + "counter_signal", + "human_boundary", + "stop_condition", + "output_requirement", + "source" + ], + "properties": { + "rule_id": { + "type": "string", + "pattern": "^ux3\\.[A-Za-z0-9_.-]+$" + }, + "title": { + "type": "string", + "minLength": 1 + }, + "flow": { + "type": "string", + "minLength": 1 + }, + "strength": { + "type": "string", + "minLength": 1 + }, + "trigger": { + "type": "array", + "minItems": 1, + "items": { + "type": "string", + "minLength": 1 + } + }, + "must_inspect": { + "type": "array", + "minItems": 1, + "items": { + "type": "string", + "minLength": 1 + } + }, + "must_do": { + "type": "array", + "minItems": 1, + "items": { + "type": "string", + "minLength": 1 + } + }, + "must_not_do": { + "type": "array", + "minItems": 1, + "items": { + "type": "string", + "minLength": 1 + } + }, + "evidence_required": { + "type": "array", + "minItems": 1, + "items": { + "type": "string", + "minLength": 1 + } + }, + "counter_signal": { + "type": "array", + "minItems": 1, + "items": { + "type": "string", + "minLength": 1 + } + }, + "human_boundary": { + "type": "array", + "minItems": 1, + "items": { + "type": "string", + "minLength": 1 + } + }, + "stop_condition": { + "type": "array", + "minItems": 1, + "items": { + "type": "string", + "minLength": 1 + } + }, + "output_requirement": { + "type": "array", + "minItems": 1, + "items": { + "type": "string", + "minLength": 1 + } + }, + "source": { + "type": "array", + "minItems": 1, + "items": { + "type": "string", + "minLength": 1 + } + } + } +} diff --git a/skills/product-design-harness/resources/schemas/evidence-request.schema.json b/skills/product-design-harness/resources/schemas/evidence-request.schema.json new file mode 100644 index 000000000..9e3b7cea4 --- /dev/null +++ b/skills/product-design-harness/resources/schemas/evidence-request.schema.json @@ -0,0 +1,71 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://cis2042.github.io/ux3-product-design-harness/schemas/evidence-request.schema.json", + "title": "Product Design Harness Evidence Request", + "type": "object", + "additionalProperties": false, + "required": [ + "request_id", + "decision_question", + "claim_ids", + "allowed_source_types", + "required_signal_types", + "freshness_limit_days", + "return_counter_signals" + ], + "properties": { + "request_id": { + "type": "string", + "minLength": 1 + }, + "decision_question": { + "type": "string", + "minLength": 1 + }, + "claim_ids": { + "type": "array", + "items": { + "type": "string" + }, + "minItems": 1 + }, + "allowed_source_types": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "internal", + "external", + "workflow", + "risk", + "direct_learning" + ] + }, + "minItems": 1 + }, + "required_signal_types": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "stated_opinion", + "quote", + "observed_behavior", + "workflow_trace", + "product_log", + "transaction", + "market_signal", + "policy", + "derived" + ] + } + }, + "freshness_limit_days": { + "type": "integer", + "minimum": 0 + }, + "return_counter_signals": { + "const": true + } + } +} diff --git a/skills/product-design-harness/resources/schemas/evidence-response.schema.json b/skills/product-design-harness/resources/schemas/evidence-response.schema.json new file mode 100644 index 000000000..31801bca1 --- /dev/null +++ b/skills/product-design-harness/resources/schemas/evidence-response.schema.json @@ -0,0 +1,27 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://cis2042.github.io/ux3-product-design-harness/schemas/evidence-response.schema.json", + "title": "Product Design Harness Evidence Response", + "type": "object", + "additionalProperties": false, + "required": [ + "request_id", + "source_connector", + "retrieved_at", + "receipts", + "coverage_gaps" + ], + "properties": { + "request_id": { "type": "string", "minLength": 1 }, + "source_connector": { "type": "string", "minLength": 1 }, + "retrieved_at": { "type": "string", "format": "date-time" }, + "receipts": { + "type": "array", + "items": { "$ref": "evidence.schema.json" } + }, + "coverage_gaps": { + "type": "array", + "items": { "type": "string" } + } + } +} diff --git a/skills/product-design-harness/resources/schemas/evidence.schema.json b/skills/product-design-harness/resources/schemas/evidence.schema.json new file mode 100644 index 000000000..690cabe4a --- /dev/null +++ b/skills/product-design-harness/resources/schemas/evidence.schema.json @@ -0,0 +1,109 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://cis2042.github.io/ux3-product-design-harness/schemas/evidence.schema.json", + "title": "Product Design Harness Evidence Receipt", + "type": "object", + "additionalProperties": false, + "required": [ + "evidence_id", + "source_id", + "source_type", + "raw_artifact_uri", + "signal_type", + "signal", + "interpretation", + "decision_impact", + "evidence_tier", + "confidence_level", + "counter_signal", + "collected_at", + "source_last_verified_at", + "max_staleness_days" + ], + "properties": { + "evidence_id": { + "type": "string", + "minLength": 1 + }, + "source_id": { + "type": "string", + "minLength": 1 + }, + "source_type": { + "type": "string", + "enum": [ + "internal", + "external", + "workflow", + "risk", + "direct_learning" + ] + }, + "raw_artifact_uri": { + "type": "string", + "minLength": 1 + }, + "signal_type": { + "type": "string", + "enum": [ + "stated_opinion", + "quote", + "observed_behavior", + "workflow_trace", + "product_log", + "transaction", + "market_signal", + "policy", + "derived" + ] + }, + "signal": { + "type": "string", + "minLength": 1 + }, + "interpretation": { + "type": "string", + "minLength": 1 + }, + "decision_impact": { + "type": "string", + "minLength": 1 + }, + "evidence_tier": { + "type": "string", + "enum": [ + "t0", + "t1", + "t2", + "t3", + "t4" + ] + }, + "confidence_level": { + "type": "string", + "enum": [ + "very_low", + "low", + "medium", + "high", + "very_high" + ] + }, + "counter_signal": { + "type": "string", + "minLength": 1 + }, + "collected_at": { + "type": "string", + "format": "date-time" + }, + "source_last_verified_at": { + "type": "string", + "format": "date-time" + }, + "max_staleness_days": { + "type": "integer", + "minimum": 0 + } + } +} diff --git a/skills/product-design-harness/resources/schemas/human-decision.schema.json b/skills/product-design-harness/resources/schemas/human-decision.schema.json new file mode 100644 index 000000000..23fa40417 --- /dev/null +++ b/skills/product-design-harness/resources/schemas/human-decision.schema.json @@ -0,0 +1,71 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://cis2042.github.io/ux3-product-design-harness/schemas/human-decision.schema.json", + "title": "Product Design Harness Human Decision", + "type": "object", + "additionalProperties": false, + "required": [ + "decision_id", + "review_id", + "decision_type", + "decision", + "options_considered", + "rationale", + "accountable_owner", + "decided_at", + "reversal_conditions" + ], + "properties": { + "decision_id": { + "type": "string", + "minLength": 1 + }, + "review_id": { + "type": "string", + "minLength": 1, + "description": "The review_id of the review-result this decision belongs to." + }, + "decision_type": { + "type": "string", + "enum": [ + "taste", + "risk", + "strategy", + "ethics", + "meaning" + ] + }, + "decision": { + "type": "string", + "minLength": 1 + }, + "options_considered": { + "type": "array", + "items": { + "type": "string", + "minLength": 1 + }, + "minItems": 2 + }, + "rationale": { + "type": "string", + "minLength": 1 + }, + "accountable_owner": { + "type": "string", + "minLength": 1 + }, + "decided_at": { + "type": "string", + "format": "date-time", + "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?(Z|[+-]\\d{2}:\\d{2})$" + }, + "reversal_conditions": { + "type": "array", + "items": { + "type": "string" + }, + "minItems": 1 + } + } +} diff --git a/skills/product-design-harness/resources/schemas/ontology.schema.json b/skills/product-design-harness/resources/schemas/ontology.schema.json new file mode 100644 index 000000000..6d085d804 --- /dev/null +++ b/skills/product-design-harness/resources/schemas/ontology.schema.json @@ -0,0 +1,183 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://cis2042.github.io/ux3-product-design-harness/schemas/ontology.schema.json", + "title": "UX3 Ontology", + "type": "object", + "additionalProperties": false, + "required": [ + "schema_version", + "canonical_language", + "name", + "description", + "flows", + "intersections", + "actor_roles", + "stakeholder_roles", + "evidence_terms", + "human_judgment_terms", + "learning_loop" + ], + "properties": { + "schema_version": { + "type": "string", + "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$" + }, + "canonical_language": { + "const": "en" + }, + "name": { + "type": "string", + "minLength": 1 + }, + "description": { + "type": "string", + "minLength": 1 + }, + "flows": { + "type": "array", + "minItems": 3, + "maxItems": 3, + "items": { + "$ref": "#/$defs/flow" + } + }, + "intersections": { + "type": "array", + "minItems": 4, + "maxItems": 4, + "items": { + "$ref": "#/$defs/intersection" + } + }, + "actor_roles": { + "type": "array", + "minItems": 6, + "items": { + "$ref": "#/$defs/term" + } + }, + "stakeholder_roles": { + "type": "array", + "minItems": 11, + "items": { + "$ref": "#/$defs/term" + } + }, + "evidence_terms": { + "type": "array", + "minItems": 6, + "items": { + "$ref": "#/$defs/term" + } + }, + "human_judgment_terms": { + "type": "array", + "minItems": 3, + "items": { + "$ref": "#/$defs/term" + } + }, + "learning_loop": { + "type": "array", + "minItems": 8, + "items": { + "type": "string", + "minLength": 1 + } + } + }, + "$defs": { + "flow": { + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "name", + "definition", + "must_answer" + ], + "properties": { + "id": { + "enum": [ + "user_flow", + "evidence_flow", + "business_flow" + ] + }, + "name": { + "enum": [ + "User Flow", + "Evidence Flow", + "Business Flow" + ] + }, + "definition": { + "type": "string", + "minLength": 1 + }, + "must_answer": { + "type": "array", + "minItems": 1, + "items": { + "type": "string", + "minLength": 1 + } + } + } + }, + "intersection": { + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "name", + "label", + "required_question" + ], + "properties": { + "id": { + "enum": [ + "user_evidence", + "evidence_business", + "user_business", + "ux3_decision_kernel" + ] + }, + "name": { + "enum": [ + "User + Evidence", + "Evidence + Business", + "User + Business", + "User + Evidence + Business" + ] + }, + "label": { + "type": "string", + "minLength": 1 + }, + "required_question": { + "type": "string", + "minLength": 1 + } + } + }, + "term": { + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "definition" + ], + "properties": { + "id": { + "type": "string", + "pattern": "^[a-z0-9_]+$" + }, + "definition": { + "type": "string", + "minLength": 1 + } + } + } + } +} diff --git a/skills/product-design-harness/resources/schemas/product-brief.schema.json b/skills/product-design-harness/resources/schemas/product-brief.schema.json new file mode 100644 index 000000000..f7b3f6014 --- /dev/null +++ b/skills/product-design-harness/resources/schemas/product-brief.schema.json @@ -0,0 +1,238 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://cis2042.github.io/ux3-product-design-harness/schemas/product-brief.schema.json", + "title": "Product Design Harness Product Brief", + "type": "object", + "additionalProperties": false, + "required": [ + "schema_version", + "session_config", + "product_direction", + "accountable_owner", + "stage", + "actor_boundary", + "business_boundary", + "human_judgment_boundary", + "unresolved_assumptions", + "execution_boundary", + "problem_hypothesis", + "current_evidence", + "business_goal", + "constraints", + "proposed_next_step", + "known_risks" + ], + "properties": { + "schema_version": { + "const": "2.1" + }, + "session_config": { + "$ref": "session-config.schema.json" + }, + "product_direction": { + "type": "string", + "minLength": 1 + }, + "accountable_owner": { + "type": "string", + "minLength": 1 + }, + "stage": { + "type": "string", + "enum": [ + "idea", + "prototype", + "launch", + "scale" + ] + }, + "actor_boundary": { + "$ref": "actor-boundary.schema.json" + }, + "business_boundary": { + "type": "object", + "required": [ + "product_organization", + "project_owner", + "issuer", + "customers", + "buyers", + "operators", + "partners", + "funders", + "platforms", + "regulators", + "externality_bearers", + "decision_authority", + "value_exchange" + ], + "properties": { + "product_organization": { + "type": "string", + "minLength": 1 + }, + "project_owner": { + "type": "string", + "minLength": 1 + }, + "issuer": { + "type": "string", + "minLength": 1 + }, + "customers": { + "$ref": "#/$defs/string_list" + }, + "buyers": { + "$ref": "#/$defs/string_list" + }, + "operators": { + "$ref": "#/$defs/string_list" + }, + "partners": { + "$ref": "#/$defs/string_list" + }, + "funders": { + "$ref": "#/$defs/string_list" + }, + "platforms": { + "$ref": "#/$defs/string_list" + }, + "regulators": { + "$ref": "#/$defs/string_list" + }, + "externality_bearers": { + "$ref": "#/$defs/string_list" + }, + "decision_authority": { + "type": "string", + "minLength": 1 + }, + "value_exchange": { + "type": "string", + "minLength": 1 + } + }, + "additionalProperties": false + }, + "human_judgment_boundary": { + "type": "object", + "required": [ + "human_owned_decisions", + "machine_supported_inputs", + "not_mechanized", + "approval_gates" + ], + "properties": { + "human_owned_decisions": { + "$ref": "#/$defs/string_list" + }, + "machine_supported_inputs": { + "$ref": "#/$defs/string_list" + }, + "not_mechanized": { + "$ref": "#/$defs/string_list" + }, + "approval_gates": { + "$ref": "#/$defs/named_human_gates" + } + }, + "additionalProperties": false + }, + "unresolved_assumptions": { + "$ref": "#/$defs/non_empty_string_list" + }, + "execution_boundary": { + "$ref": "#/$defs/execution_boundary" + }, + "problem_hypothesis": { + "type": "string", + "minLength": 1 + }, + "current_evidence": { + "type": "array", + "items": { + "$ref": "evidence.schema.json" + } + }, + "business_goal": { + "type": "string", + "minLength": 1 + }, + "constraints": { + "$ref": "#/$defs/string_list" + }, + "proposed_next_step": { + "type": "string", + "minLength": 1 + }, + "known_risks": { + "$ref": "#/$defs/string_list" + } + }, + "$defs": { + "string_list": { + "type": "array", + "items": { + "type": "string", + "minLength": 1 + } + }, + "non_empty_string_list": { + "type": "array", + "items": { + "type": "string", + "minLength": 1 + }, + "minItems": 1 + }, + "execution_boundary": { + "type": "object", + "additionalProperties": false, + "required": [ + "may_do", + "must_not_do", + "must_ask" + ], + "properties": { + "may_do": { + "$ref": "#/$defs/non_empty_string_list" + }, + "must_not_do": { + "$ref": "#/$defs/non_empty_string_list" + }, + "must_ask": { + "$ref": "#/$defs/non_empty_string_list" + } + } + }, + "named_human_gates": { + "type": "array", + "items": { + "$ref": "#/$defs/named_human_gate" + } + }, + "named_human_gate": { + "type": "object", + "additionalProperties": false, + "required": [ + "gate_id", + "accountable_owner", + "condition" + ], + "properties": { + "gate_id": { + "type": "string", + "minLength": 1 + }, + "accountable_owner": { + "type": "string", + "minLength": 1 + }, + "condition": { + "type": "string", + "minLength": 1 + } + } + } + } +} diff --git a/skills/product-design-harness/resources/schemas/red-team-review.schema.json b/skills/product-design-harness/resources/schemas/red-team-review.schema.json new file mode 100644 index 000000000..55013991b --- /dev/null +++ b/skills/product-design-harness/resources/schemas/red-team-review.schema.json @@ -0,0 +1,111 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://cis2042.github.io/ux3-product-design-harness/schemas/red-team-review.schema.json", + "title": "Product Design Harness Red-Team Review", + "type": "object", + "additionalProperties": false, + "required": [ + "review_id", + "claim_ids", + "evidence_receipt_ids", + "failure_modes", + "disconfirming_tests", + "hidden_affected_people", + "current_workaround", + "substitute_threats", + "trust_risk", + "stop_condition", + "verdict" + ], + "properties": { + "review_id": { + "type": "string", + "minLength": 1 + }, + "claim_ids": { + "$ref": "#/$defs/non_empty_string_list" + }, + "evidence_receipt_ids": { + "$ref": "#/$defs/non_empty_string_list" + }, + "failure_modes": { + "type": "array", + "items": { + "type": "string", + "minLength": 1 + }, + "minItems": 5, + "uniqueItems": true + }, + "disconfirming_tests": { + "$ref": "#/$defs/non_empty_string_list" + }, + "hidden_affected_people": { + "$ref": "#/$defs/non_empty_string_list" + }, + "current_workaround": { + "type": "string", + "minLength": 1 + }, + "substitute_threats": { + "type": "object", + "additionalProperties": false, + "required": [ + "direct", + "indirect", + "platform", + "workflow", + "doing_nothing" + ], + "properties": { + "direct": { + "type": "string", + "minLength": 1 + }, + "indirect": { + "type": "string", + "minLength": 1 + }, + "platform": { + "type": "string", + "minLength": 1 + }, + "workflow": { + "type": "string", + "minLength": 1 + }, + "doing_nothing": { + "type": "string", + "minLength": 1 + } + } + }, + "trust_risk": { + "type": "string", + "minLength": 1 + }, + "stop_condition": { + "type": "string", + "minLength": 1 + }, + "verdict": { + "type": "string", + "enum": [ + "continue", + "verify", + "stop_reframe" + ] + } + }, + "$defs": { + "non_empty_string_list": { + "type": "array", + "items": { + "type": "string", + "minLength": 1 + }, + "minItems": 1, + "uniqueItems": true + } + } +} diff --git a/skills/product-design-harness/resources/schemas/review-result.schema.json b/skills/product-design-harness/resources/schemas/review-result.schema.json new file mode 100644 index 000000000..076c054be --- /dev/null +++ b/skills/product-design-harness/resources/schemas/review-result.schema.json @@ -0,0 +1,1080 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://cis2042.github.io/ux3-product-design-harness/schemas/review-result.schema.json", + "title": "Product Design Harness Canonical Review Result", + "type": "object", + "additionalProperties": false, + "required": [ + "schema_version", + "session_config", + "review_id", + "product_direction", + "mode", + "stage", + "actor_boundary", + "product_organization", + "stakeholder_effects", + "human_judgment_boundary", + "unresolved_assumptions", + "combined_verdict", + "weakest_flow", + "strongest_signal", + "riskiest_claim", + "main_uncertainty", + "confidence_level", + "evidence_tier", + "main_trade_off", + "human_owned_decision", + "human_decision_record_id", + "evidence_receipt_ids", + "reviews", + "next_smallest_action", + "execution_boundary", + "human_approval_gates", + "high_risk_actions", + "stop_conditions", + "context_pack_required" + ], + "properties": { + "schema_version": { + "const": "2.1" + }, + "session_config": { + "$ref": "session-config.schema.json" + }, + "review_id": { + "type": "string", + "minLength": 1 + }, + "product_direction": { + "type": "string", + "minLength": 1 + }, + "mode": { + "type": "string", + "enum": [ + "quick_gate", + "standard_gate", + "ux3_council" + ] + }, + "stage": { + "type": "string", + "enum": [ + "idea", + "prototype", + "launch", + "scale" + ] + }, + "actor_boundary": { + "$ref": "actor-boundary.schema.json" + }, + "product_organization": { + "type": "object", + "additionalProperties": false, + "required": [ + "organization", + "project_owner", + "issuer" + ], + "properties": { + "organization": { + "type": "string", + "minLength": 1 + }, + "project_owner": { + "type": "string", + "minLength": 1 + }, + "issuer": { + "type": "string", + "minLength": 1 + } + } + }, + "stakeholder_effects": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": false, + "required": [ + "stakeholder", + "effect" + ], + "properties": { + "stakeholder": { + "type": "string", + "minLength": 1 + }, + "effect": { + "type": "string", + "minLength": 1 + } + } + }, + "minItems": 1 + }, + "human_judgment_boundary": { + "type": "object", + "additionalProperties": false, + "required": [ + "human_owned_decisions", + "machine_supported_inputs", + "not_mechanized", + "approval_gates" + ], + "properties": { + "human_owned_decisions": { + "$ref": "#/$defs/string_list" + }, + "machine_supported_inputs": { + "$ref": "#/$defs/string_list" + }, + "not_mechanized": { + "$ref": "#/$defs/string_list" + }, + "approval_gates": { + "$ref": "#/$defs/named_human_gates" + } + } + }, + "unresolved_assumptions": { + "$ref": "#/$defs/non_empty_string_list" + }, + "combined_verdict": { + "type": "string", + "enum": [ + "continue", + "verify", + "stop_reframe" + ] + }, + "weakest_flow": { + "type": "string", + "enum": [ + "user", + "evidence", + "business" + ] + }, + "strongest_signal": { + "type": "string", + "minLength": 1 + }, + "riskiest_claim": { + "type": "string", + "minLength": 1 + }, + "main_uncertainty": { + "type": "string", + "minLength": 1 + }, + "confidence_level": { + "type": "string", + "enum": [ + "very_low", + "low", + "medium", + "high", + "very_high" + ] + }, + "evidence_tier": { + "type": "string", + "enum": [ + "t0", + "t1", + "t2", + "t3", + "t4" + ] + }, + "main_trade_off": { + "type": "string", + "minLength": 1 + }, + "human_owned_decision": { + "type": "string", + "enum": [ + "taste", + "risk", + "strategy", + "ethics", + "meaning", + "none" + ] + }, + "human_decision_record_id": { + "type": [ + "string", + "null" + ] + }, + "evidence_receipt_ids": { + "type": "array", + "items": { + "type": "string", + "minLength": 1 + }, + "minItems": 1, + "uniqueItems": true + }, + "reviews": { + "type": "object", + "additionalProperties": false, + "required": [ + "user", + "evidence", + "business" + ], + "properties": { + "user": { + "$ref": "#/$defs/lane_review" + }, + "evidence": { + "$ref": "#/$defs/lane_review" + }, + "business": { + "$ref": "#/$defs/lane_review" + } + } + }, + "next_smallest_action": { + "type": "string", + "minLength": 1 + }, + "execution_boundary": { + "type": "object", + "additionalProperties": false, + "required": [ + "may_do", + "must_not_do", + "must_ask" + ], + "properties": { + "may_do": { + "type": "array", + "items": { + "type": "string", + "minLength": 1 + }, + "minItems": 1 + }, + "must_not_do": { + "type": "array", + "items": { + "type": "string", + "minLength": 1 + }, + "minItems": 1 + }, + "must_ask": { + "type": "array", + "items": { + "type": "string", + "minLength": 1 + }, + "minItems": 1 + } + } + }, + "human_approval_gates": { + "$ref": "#/$defs/named_human_gates" + }, + "high_risk_actions": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": false, + "required": [ + "action", + "approval_gate", + "rollback_plan" + ], + "properties": { + "action": { + "type": "string", + "minLength": 1 + }, + "approval_gate": { + "$ref": "#/$defs/named_human_gate" + }, + "rollback_plan": { + "type": "string", + "minLength": 1 + } + } + } + }, + "stop_conditions": { + "type": "array", + "items": { + "type": "string", + "minLength": 1 + }, + "minItems": 1 + }, + "context_pack_required": { + "type": "boolean" + }, + "council_record": { + "type": "object", + "additionalProperties": false, + "required": [ + "independent_review_ids", + "challenges", + "unresolved_conflicts" + ], + "properties": { + "independent_review_ids": { + "type": "array", + "items": { + "type": "string", + "minLength": 1 + }, + "minItems": 3, + "uniqueItems": true + }, + "challenges": { + "type": "array", + "items": { + "$ref": "#/$defs/challenge" + }, + "minItems": 3 + }, + "unresolved_conflicts": { + "type": "array", + "items": { + "type": "string", + "minLength": 1 + } + } + } + }, + "proof_step": { + "type": "string", + "minLength": 1 + }, + "reframed_question": { + "type": "string", + "minLength": 1 + } + }, + "allOf": [ + { + "if": { + "properties": { + "mode": { + "const": "ux3_council" + } + }, + "required": [ + "mode" + ] + }, + "then": { + "required": [ + "council_record" + ] + } + }, + { + "if": { + "properties": { + "human_owned_decision": { + "const": "none" + } + }, + "required": [ + "human_owned_decision" + ] + }, + "then": { + "properties": { + "human_decision_record_id": { + "const": null + } + } + }, + "else": { + "properties": { + "human_decision_record_id": { + "type": "string", + "minLength": 1 + } + } + } + }, + { + "if": { + "properties": { + "combined_verdict": { + "const": "continue" + } + }, + "required": [ + "combined_verdict" + ] + }, + "then": { + "properties": { + "context_pack_required": { + "const": true + } + }, + "not": { + "anyOf": [ + { + "required": [ + "proof_step" + ] + }, + { + "required": [ + "reframed_question" + ] + } + ] + } + } + }, + { + "if": { + "properties": { + "combined_verdict": { + "const": "verify" + } + }, + "required": [ + "combined_verdict" + ] + }, + "then": { + "required": [ + "proof_step" + ], + "properties": { + "context_pack_required": { + "const": false + } + }, + "not": { + "required": [ + "reframed_question" + ] + } + } + }, + { + "if": { + "properties": { + "combined_verdict": { + "const": "stop_reframe" + } + }, + "required": [ + "combined_verdict" + ] + }, + "then": { + "required": [ + "reframed_question" + ], + "properties": { + "context_pack_required": { + "const": false + } + }, + "not": { + "required": [ + "proof_step" + ] + } + } + }, + { + "if": { + "properties": { + "reviews": { + "properties": { + "user": { + "properties": { + "verdict": { + "const": "stop_reframe" + } + }, + "required": [ + "verdict" + ] + } + }, + "required": [ + "user" + ] + } + }, + "required": [ + "reviews" + ] + }, + "then": { + "properties": { + "combined_verdict": { + "const": "stop_reframe" + } + } + } + }, + { + "if": { + "properties": { + "reviews": { + "properties": { + "evidence": { + "properties": { + "verdict": { + "const": "stop_reframe" + } + }, + "required": [ + "verdict" + ] + } + }, + "required": [ + "evidence" + ] + } + }, + "required": [ + "reviews" + ] + }, + "then": { + "properties": { + "combined_verdict": { + "const": "stop_reframe" + } + } + } + }, + { + "if": { + "properties": { + "reviews": { + "properties": { + "business": { + "properties": { + "verdict": { + "const": "stop_reframe" + } + }, + "required": [ + "verdict" + ] + } + }, + "required": [ + "business" + ] + } + }, + "required": [ + "reviews" + ] + }, + "then": { + "properties": { + "combined_verdict": { + "const": "stop_reframe" + } + } + } + }, + { + "if": { + "properties": { + "combined_verdict": { + "const": "continue" + } + }, + "required": [ + "combined_verdict" + ] + }, + "then": { + "properties": { + "reviews": { + "properties": { + "user": { + "properties": { + "verdict": { + "const": "continue" + } + } + }, + "evidence": { + "properties": { + "verdict": { + "const": "continue" + } + } + }, + "business": { + "properties": { + "verdict": { + "const": "continue" + } + } + } + } + } + } + } + }, + { + "if": { + "properties": { + "combined_verdict": { + "const": "verify" + } + }, + "required": [ + "combined_verdict" + ] + }, + "then": { + "properties": { + "reviews": { + "anyOf": [ + { + "properties": { + "user": { + "properties": { + "verdict": { + "const": "verify" + } + }, + "required": [ + "verdict" + ] + } + }, + "required": [ + "user" + ] + }, + { + "properties": { + "evidence": { + "properties": { + "verdict": { + "const": "verify" + } + }, + "required": [ + "verdict" + ] + } + }, + "required": [ + "evidence" + ] + }, + { + "properties": { + "business": { + "properties": { + "verdict": { + "const": "verify" + } + }, + "required": [ + "verdict" + ] + } + }, + "required": [ + "business" + ] + } + ] + } + } + } + }, + { + "if": { + "properties": { + "mode": { + "enum": [ + "quick_gate", + "standard_gate" + ] + } + }, + "required": [ + "mode" + ] + }, + "then": { + "not": { + "required": [ + "council_record" + ] + } + } + }, + { + "if": { + "properties": { + "combined_verdict": { + "const": "stop_reframe" + } + }, + "required": [ + "combined_verdict" + ] + }, + "then": { + "properties": { + "reviews": { + "anyOf": [ + { + "properties": { + "user": { + "properties": { + "verdict": { + "const": "stop_reframe" + } + }, + "required": [ + "verdict" + ] + } + }, + "required": [ + "user" + ] + }, + { + "properties": { + "evidence": { + "properties": { + "verdict": { + "const": "stop_reframe" + } + }, + "required": [ + "verdict" + ] + } + }, + "required": [ + "evidence" + ] + }, + { + "properties": { + "business": { + "properties": { + "verdict": { + "const": "stop_reframe" + } + }, + "required": [ + "verdict" + ] + } + }, + "required": [ + "business" + ] + } + ] + } + } + } + }, + { + "if": { + "properties": { + "execution_boundary": { + "properties": { + "may_do": { + "contains": { + "type": "string", + "pattern": "([Cc]ustomer-facing|[Pp]ermissions|[Dd]ata handling|[Pp]roduction schema|[Ee]xternal action|[Rr]emove human approval|[Aa]utonomous)" + } + } + }, + "required": [ + "may_do" + ] + } + }, + "required": [ + "execution_boundary" + ] + }, + "then": { + "properties": { + "high_risk_actions": { + "minItems": 1 + } + }, + "required": [ + "high_risk_actions" + ] + } + } + ], + "$defs": { + "string_list": { + "type": "array", + "items": { + "type": "string", + "minLength": 1 + } + }, + "non_empty_string_list": { + "type": "array", + "items": { + "type": "string", + "minLength": 1 + }, + "minItems": 1 + }, + "named_human_gates": { + "type": "array", + "items": { + "$ref": "#/$defs/named_human_gate" + } + }, + "named_human_gate": { + "type": "object", + "additionalProperties": false, + "required": [ + "gate_id", + "accountable_owner", + "condition" + ], + "properties": { + "gate_id": { + "type": "string", + "minLength": 1 + }, + "accountable_owner": { + "type": "string", + "minLength": 1 + }, + "condition": { + "type": "string", + "minLength": 1 + } + } + }, + "challenge": { + "type": "object", + "additionalProperties": false, + "required": [ + "reviewer", + "objection_to", + "counter_evidence", + "position_change" + ], + "properties": { + "reviewer": { + "type": "string", + "enum": [ + "user_flow", + "evidence_flow", + "business_flow" + ] + }, + "objection_to": { + "type": "string", + "enum": [ + "user_flow", + "evidence_flow", + "business_flow", + "none" + ] + }, + "counter_evidence": { + "type": "string", + "minLength": 1 + }, + "position_change": { + "type": "string", + "enum": [ + "unchanged", + "strengthened", + "weakened", + "reversed" + ] + } + }, + "allOf": [ + { + "not": { + "properties": { + "reviewer": { + "const": "user_flow" + }, + "objection_to": { + "const": "user_flow" + } + }, + "required": [ + "reviewer", + "objection_to" + ] + } + }, + { + "not": { + "properties": { + "reviewer": { + "const": "evidence_flow" + }, + "objection_to": { + "const": "evidence_flow" + } + }, + "required": [ + "reviewer", + "objection_to" + ] + } + }, + { + "not": { + "properties": { + "reviewer": { + "const": "business_flow" + }, + "objection_to": { + "const": "business_flow" + } + }, + "required": [ + "reviewer", + "objection_to" + ] + } + }, + { + "if": { + "properties": { + "objection_to": { + "const": "none" + } + }, + "required": [ + "objection_to" + ] + }, + "then": { + "properties": { + "position_change": { + "const": "unchanged" + } + } + } + } + ] + }, + "lane_review": { + "type": "object", + "additionalProperties": false, + "required": [ + "verdict", + "evidence_tier", + "strongest_signal", + "weakest_assumption", + "missing_evidence", + "disconfirming_evidence", + "stop_condition" + ], + "properties": { + "verdict": { + "type": "string", + "enum": [ + "continue", + "verify", + "stop_reframe" + ] + }, + "stop_reason_class": { + "type": "string", + "enum": [ + "actor", + "safety", + "core_evidence", + "irreversible_risk", + "business_viability", + "other" + ] + }, + "evidence_tier": { + "type": "string", + "enum": [ + "t0", + "t1", + "t2", + "t3", + "t4" + ] + }, + "strongest_signal": { + "type": "string", + "minLength": 1 + }, + "weakest_assumption": { + "type": "string", + "minLength": 1 + }, + "missing_evidence": { + "type": "string", + "minLength": 1 + }, + "disconfirming_evidence": { + "type": "string", + "minLength": 1 + }, + "stop_condition": { + "type": "string", + "minLength": 1 + } + }, + "allOf": [ + { + "if": { + "properties": { + "verdict": { + "const": "stop_reframe" + } + }, + "required": [ + "verdict" + ] + }, + "then": { + "required": [ + "stop_reason_class" + ] + }, + "else": { + "not": { + "required": [ + "stop_reason_class" + ] + } + } + } + ] + } + } +} diff --git a/skills/product-design-harness/resources/schemas/reviewer-verdict.schema.json b/skills/product-design-harness/resources/schemas/reviewer-verdict.schema.json new file mode 100644 index 000000000..8324407e6 --- /dev/null +++ b/skills/product-design-harness/resources/schemas/reviewer-verdict.schema.json @@ -0,0 +1,188 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://cis2042.github.io/ux3-product-design-harness/schemas/reviewer-verdict.schema.json", + "title": "Product Design Harness Reviewer Verdict", + "type": "object", + "additionalProperties": false, + "required": [ + "reviewer", + "review_round", + "verdict", + "strongest_signal", + "weakest_assumption", + "missing_evidence", + "disconfirming_evidence", + "evidence_tier", + "confidence_level", + "stop_condition", + "next_smallest_action" + ], + "properties": { + "reviewer": { + "type": "string", + "enum": [ + "user_flow", + "evidence_flow", + "business_flow" + ] + }, + "review_round": { + "type": "string", + "enum": [ + "independent", + "challenge" + ] + }, + "verdict": { + "type": "string", + "enum": [ + "continue", + "verify", + "stop_reframe" + ] + }, + "strongest_signal": { + "type": "string", + "minLength": 1 + }, + "weakest_assumption": { + "type": "string", + "minLength": 1 + }, + "missing_evidence": { + "type": "string", + "minLength": 1 + }, + "disconfirming_evidence": { + "type": "string", + "minLength": 1 + }, + "evidence_tier": { + "type": "string", + "enum": [ + "t0", + "t1", + "t2", + "t3", + "t4" + ] + }, + "confidence_level": { + "type": "string", + "enum": [ + "very_low", + "low", + "medium", + "high", + "very_high" + ] + }, + "objection_to": { + "type": "string", + "enum": [ + "user_flow", + "evidence_flow", + "business_flow", + "none" + ] + }, + "counter_evidence": { + "type": "string", + "minLength": 1 + }, + "position_change": { + "type": "string", + "enum": [ + "unchanged", + "strengthened", + "weakened", + "reversed" + ] + }, + "stop_condition": { + "type": "string", + "minLength": 1 + }, + "next_smallest_action": { + "type": "string", + "minLength": 1 + }, + "stop_reason_class": { + "type": "string", + "enum": [ + "actor", + "safety", + "core_evidence", + "irreversible_risk", + "business_viability", + "other" + ] + } + }, + "allOf": [ + { + "if": { + "properties": { + "review_round": { + "const": "challenge" + } + }, + "required": [ + "review_round" + ] + }, + "then": { + "required": [ + "objection_to", + "counter_evidence", + "position_change" + ] + }, + "else": { + "not": { + "anyOf": [ + { + "required": [ + "objection_to" + ] + }, + { + "required": [ + "counter_evidence" + ] + }, + { + "required": [ + "position_change" + ] + } + ] + } + } + }, + { + "if": { + "properties": { + "verdict": { + "const": "stop_reframe" + } + }, + "required": [ + "verdict" + ] + }, + "then": { + "required": [ + "stop_reason_class" + ] + }, + "else": { + "not": { + "required": [ + "stop_reason_class" + ] + } + } + } + ] +} diff --git a/skills/product-design-harness/resources/schemas/session-config.schema.json b/skills/product-design-harness/resources/schemas/session-config.schema.json new file mode 100644 index 000000000..9e9056dda --- /dev/null +++ b/skills/product-design-harness/resources/schemas/session-config.schema.json @@ -0,0 +1,26 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://cis2042.github.io/ux3-product-design-harness/schemas/session-config.schema.json", + "title": "UX3 Session Config", + "type": "object", + "additionalProperties": false, + "required": [ + "working_language", + "canonical_identifiers", + "fallback_language" + ], + "properties": { + "working_language": { + "type": "string", + "enum": ["en", "zh-TW", "zh-CN", "ja", "ko", "es", "fr", "de", "pt"] + }, + "canonical_identifiers": { + "type": "string", + "const": "en" + }, + "fallback_language": { + "type": "string", + "const": "en" + } + } +} diff --git a/skills/product-design-harness/resources/schemas/uncertainty-review.schema.json b/skills/product-design-harness/resources/schemas/uncertainty-review.schema.json new file mode 100644 index 000000000..e1ef6092a --- /dev/null +++ b/skills/product-design-harness/resources/schemas/uncertainty-review.schema.json @@ -0,0 +1,52 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://cis2042.github.io/ux3-product-design-harness/schemas/uncertainty-review.schema.json", + "title": "Product Design Harness Uncertainty Review", + "type": "object", + "additionalProperties": false, + "required": [ + "evidence_tier", + "confidence_level", + "risk_class", + "reversibility", + "main_uncertainty", + "false_confidence_risk", + "stale_evidence_ids", + "proof_bar", + "verdict_impact", + "human_owned_decision" + ], + "properties": { + "evidence_tier": { + "type": "string", + "enum": ["t0", "t1", "t2", "t3", "t4"] + }, + "confidence_level": { + "type": "string", + "enum": ["very_low", "low", "medium", "high", "very_high"] + }, + "risk_class": { + "type": "string", + "enum": ["r1", "r2", "r3", "r4"] + }, + "reversibility": { + "type": "string", + "enum": ["low", "medium", "high"] + }, + "main_uncertainty": { "type": "string", "minLength": 1 }, + "false_confidence_risk": { "type": "string" }, + "stale_evidence_ids": { + "type": "array", + "items": { "type": "string" } + }, + "proof_bar": { "type": "string", "minLength": 1 }, + "verdict_impact": { + "type": "string", + "enum": ["continue", "verify", "stop_reframe"] + }, + "human_owned_decision": { + "type": "string", + "enum": ["taste", "risk", "strategy", "ethics", "meaning", "none"] + } + } +} diff --git a/skills/product-design-harness/resources/schemas/verdict-override.schema.json b/skills/product-design-harness/resources/schemas/verdict-override.schema.json new file mode 100644 index 000000000..b7f562863 --- /dev/null +++ b/skills/product-design-harness/resources/schemas/verdict-override.schema.json @@ -0,0 +1,93 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://cis2042.github.io/ux3-product-design-harness/schemas/verdict-override.schema.json", + "title": "Product Design Harness Verdict Override", + "description": "Authorizes execution despite a verify or stop_reframe verdict. An override never modifies the review-result: the review's verdict stays on record, and this artifact records who chose to execute anyway, within what scope, until when, and what voids the authorization. Validate with scripts/check_override.py, which also cross-checks the referenced review.", + "type": "object", + "additionalProperties": false, + "required": [ + "override_id", + "review_id", + "overridden_verdict", + "acknowledged_weakest_flow", + "authorized_scope", + "accountable_owner", + "rationale", + "expires_at", + "tripwires", + "renewal_requires" + ], + "properties": { + "override_id": { + "type": "string", + "minLength": 1, + "description": "Stable identifier; any document that references the overridden review must carry it." + }, + "review_id": { + "type": "string", + "minLength": 1, + "description": "The review_id of the review-result being overridden." + }, + "overridden_verdict": { + "type": "string", + "enum": ["verify", "stop_reframe"], + "description": "Must equal the review's combined_verdict. A continue verdict needs no override." + }, + "acknowledged_weakest_flow": { + "type": "string", + "enum": ["user", "evidence", "business"], + "description": "Must equal the review's weakest_flow; the owner restates the gap they are accepting." + }, + "authorized_scope": { + "type": "object", + "additionalProperties": false, + "required": ["may_do", "must_not_do"], + "description": "Execution scope granted despite the verdict. No may_do entry may repeat an entry from the review's must_not_do.", + "properties": { + "may_do": { + "type": "array", + "items": {"type": "string", "minLength": 1}, + "minItems": 1 + }, + "must_not_do": { + "type": "array", + "items": {"type": "string", "minLength": 1}, + "minItems": 1 + }, + "must_ask": { + "type": "array", + "items": {"type": "string", "minLength": 1}, + "minItems": 1 + } + } + }, + "accountable_owner": { + "type": "string", + "minLength": 1, + "description": "A named person, not a team." + }, + "rationale": { + "type": "string", + "minLength": 1, + "description": "Why executing despite the verdict is the right call." + }, + "expires_at": { + "type": "string", + "format": "date-time", + "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?(Z|[+-]\\d{2}:\\d{2})$", + "description": "Every override is time-boxed. When it lapses, the original verdict is in force again." + }, + "tripwires": { + "type": "array", + "items": {"type": "string", "minLength": 1}, + "minItems": 1, + "description": "Measurable conditions; any one tripping voids the override immediately." + }, + "renewal_requires": { + "type": "array", + "items": {"type": "string", "minLength": 1}, + "minItems": 1, + "description": "Evidence a renewal review must present. Renewal is a new review, never an edit." + } + } +} diff --git a/skills/product-design-harness/resources/scripts/check_override.py b/skills/product-design-harness/resources/scripts/check_override.py new file mode 100644 index 000000000..925080c21 --- /dev/null +++ b/skills/product-design-harness/resources/scripts/check_override.py @@ -0,0 +1,90 @@ +#!/usr/bin/env python3 +"""Validate a verdict-override file against the canonical contract AND +cross-check it against the review-result it overrides. + +Usage: python scripts/check_override.py path/to/override.json path/to/review.json +Exit 0 = valid; exit 1 = violations printed to stderr. +""" +import json +import sys +from datetime import datetime, timezone +from pathlib import Path + +from jsonschema import Draft202012Validator + +ROOT = Path(__file__).resolve().parent.parent + + +def check(override, review, now=None): + problems = [] + schema = json.loads( + (ROOT / "schemas" / "verdict-override.schema.json").read_text() + ) + for error in Draft202012Validator(schema).iter_errors(override): + problems.append(f"schema: {error.json_path}: {error.message}") + if problems: + return problems + + if override["review_id"] != review["review_id"]: + problems.append( + "review_id mismatch: override targets " + f"{override['review_id']!r} but the review file is " + f"{review['review_id']!r}" + ) + if review["combined_verdict"] == "continue": + problems.append( + "a continue verdict needs no override; do not create one" + ) + elif override["overridden_verdict"] != review["combined_verdict"]: + problems.append( + "overridden_verdict must equal the review's combined_verdict: " + f"{override['overridden_verdict']!r} != " + f"{review['combined_verdict']!r}" + ) + if override["acknowledged_weakest_flow"] != review["weakest_flow"]: + problems.append( + "acknowledged_weakest_flow must equal the review's weakest_flow: " + f"{override['acknowledged_weakest_flow']!r} != " + f"{review['weakest_flow']!r}" + ) + + expires_at = datetime.fromisoformat( + override["expires_at"].replace("Z", "+00:00") + ) + if now is None: + now = datetime.now(timezone.utc) + if expires_at <= now: + problems.append( + f"override expired at {override['expires_at']}: the original " + "verdict is in force again; renew through a new review" + ) + + banned = { + entry.casefold() + for entry in review["execution_boundary"]["must_not_do"] + } + for entry in override["authorized_scope"]["may_do"]: + if entry.casefold() in banned: + problems.append( + "authorized_scope.may_do repeats an entry from the review's " + f"execution_boundary.must_not_do: {entry!r}" + ) + return problems + + +def main(): + if len(sys.argv) != 3: + print(__doc__, file=sys.stderr) + raise SystemExit(2) + override = json.loads(Path(sys.argv[1]).read_text()) + review = json.loads(Path(sys.argv[2]).read_text()) + problems = check(override, review) + if problems: + for problem in problems: + print(problem, file=sys.stderr) + raise SystemExit(1) + print("ok") + + +if __name__ == "__main__": + main() diff --git a/skills/product-design-harness/resources/scripts/check_review.py b/skills/product-design-harness/resources/scripts/check_review.py new file mode 100644 index 000000000..8e888f709 --- /dev/null +++ b/skills/product-design-harness/resources/scripts/check_review.py @@ -0,0 +1,175 @@ +#!/usr/bin/env python3 +"""Validate a review-result file against the canonical contract AND the +semantic rules that JSON Schema alone cannot fully express. + +Usage: python scripts/check_review.py path/to/review.json [--context-pack path/to/pack.json] +Exit 0 = valid; exit 1 = violations printed to stderr. +""" +import argparse +import json +import sys +from pathlib import Path + +from jsonschema import Draft202012Validator +from referencing import Registry, Resource + +ROOT = Path(__file__).resolve().parent.parent +SEVERITY = {"stop_reframe": 2, "verify": 1, "continue": 0} +PRIORITY = {"evidence": 0, "user": 1, "business": 2} +VERDICTS = ["continue", "verify", "stop_reframe"] + + +def expected_weakest_flow(reviews): + def sort_key(lane): + review = reviews[lane] + return ( + -SEVERITY[review["verdict"]], + review["evidence_tier"], + PRIORITY[lane], + ) + + return sorted(reviews, key=sort_key)[0] + + +def schema_errors(document, schema_name): + schema = json.loads( + (ROOT / "schemas" / schema_name).read_text() + ) + resources = [] + for external_name in ["session-config.schema.json", "actor-boundary.schema.json"]: + external_schema = json.loads((ROOT / "schemas" / external_name).read_text()) + resource = Resource.from_contents(external_schema) + resources.extend( + [ + (external_schema["$id"], resource), + (external_name, resource), + ( + f"https://cis2042.github.io/ux3-product-design-harness/schemas/{external_name}", + resource, + ), + ] + ) + registry = Registry().with_resources(resources) + return [ + f"schema: {error.json_path}: {error.message}" + for error in Draft202012Validator(schema, registry=registry).iter_errors(document) + ] + + +def check(document): + problems = schema_errors(document, "review-result.schema.json") + if problems: + return problems + + reviews = document["reviews"] + severities = [SEVERITY[lane["verdict"]] for lane in reviews.values()] + expected_combined = VERDICTS[max(severities)] + if document["combined_verdict"] != expected_combined: + problems.append( + "combined_verdict must equal the worst lane verdict: " + f"expected {expected_combined}, got {document['combined_verdict']}" + ) + + expected_weakest = expected_weakest_flow(reviews) + if document["weakest_flow"] != expected_weakest: + problems.append( + "weakest_flow must follow the deterministic selection: " + f"expected {expected_weakest}, got {document['weakest_flow']}" + ) + + min_lane_tier = min(lane["evidence_tier"] for lane in reviews.values()) + if document["evidence_tier"] != min_lane_tier: + problems.append( + "headline evidence_tier must equal the lowest lane tier: " + f"expected {min_lane_tier}, got {document['evidence_tier']}" + ) + + tier = document["evidence_tier"] + verdict = document["combined_verdict"] + if tier == "t0" and verdict != "stop_reframe": + problems.append( + "evidence tier t0 forces stop_reframe: internal belief with no " + f"traceable source cannot authorize {verdict}" + ) + if tier == "t1" and verdict == "continue": + problems.append( + "evidence tier t1 can never return continue: stated opinion or " + "isolated signals support at most a verify" + ) + + boundary = document.get("execution_boundary", {}) + allowed = {entry.strip().casefold() for entry in boundary.get("may_do", [])} + forbidden = {entry.strip().casefold() for entry in boundary.get("must_not_do", [])} + contradictions = sorted(allowed & forbidden) + if contradictions: + problems.append( + "execution_boundary contradicts itself; the same entry appears in " + f"may_do and must_not_do: {contradictions}" + ) + + if document.get("mode") == "ux3_council": + challenges = document.get("council_record", {}).get("challenges", []) + if len(challenges) != 3 or {challenge["reviewer"] for challenge in challenges} != { + "user_flow", "evidence_flow", "business_flow" + }: + problems.append( + "council challenge round must include exactly one reviewer per flow" + ) + if not any(ch.get("objection_to") != "none" for ch in challenges): + problems.append( + "council challenge round is vacuous: at least one challenge " + "must object to another lane (objection_to != none)" + ) + return problems + + +def check_handoff(document, context_pack): + """Validate an entire handoff once; no persistent cache or authorization.""" + problems = check(document) + problems.extend(schema_errors(context_pack, "context-pack.schema.json")) + if problems: + return problems + if document["combined_verdict"] != "continue": + problems.append("context pack requires a continue review") + fields = [ + "schema_version", "session_config", "review_id", "stage", + "combined_verdict", "actor_boundary", "product_organization", + "stakeholder_effects", "human_judgment_boundary", "unresolved_assumptions", + "execution_boundary", "human_approval_gates", "high_risk_actions", + "stop_conditions", + ] + for field in fields: + if context_pack.get(field) != document.get(field): + problems.append(f"context pack {field} must match the review") + if context_pack["scope"] != document["execution_boundary"]["may_do"]: + problems.append("context pack scope must match review execution_boundary.may_do") + if context_pack.get("evidence_snapshot_ids") != document.get("evidence_receipt_ids"): + problems.append("context pack evidence_snapshot_ids must match review evidence_receipt_ids") + return problems + + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("review") + parser.add_argument("--context-pack", help="Validate the review and linked handoff together") + args = parser.parse_args() + try: + document = json.loads(Path(args.review).read_text()) + if args.context_pack: + context_pack = json.loads(Path(args.context_pack).read_text()) + problems = check_handoff(document, context_pack) + else: + problems = check(document) + except (OSError, ValueError) as error: + print(f"cannot read artifact: {error}", file=sys.stderr) + return 1 + if problems: + for problem in problems: + print(problem, file=sys.stderr) + return 1 + print("ok") + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/skills/product-design-harness/resources/scripts/jev_gate.py b/skills/product-design-harness/resources/scripts/jev_gate.py new file mode 100644 index 000000000..3080ce6ca --- /dev/null +++ b/skills/product-design-harness/resources/scripts/jev_gate.py @@ -0,0 +1,164 @@ +#!/usr/bin/env python3 +import argparse +import copy +import json +import sys +from pathlib import Path + +SEVERITY = {"stop_reframe": 2, "verify": 1, "continue": 0} +VERDICTS = ["continue", "verify", "stop_reframe"] + +ROUTINE_KEYWORDS = [ + "typo", "css", "style", "format", "lint", "comment", "readme", + "docs", "rename", "cleanup", "refactor test", "fix test" +] + +HIGH_RISK_KEYWORDS = [ + "drop table", "alter table", "migration", "secret", "auth", + "payment", "billing", "token", "privacy", "delete user", + "external api", "webhook", "telemetry", "export data" +] + + +def classify_route_baseline(prompt, context=None): + if not isinstance(prompt, str): + raise ValueError("Task prompt must be a string.") + if context is not None: + if not isinstance(context, dict): + raise ValueError("Route context must be an object.") + files_changed = context.get("files_changed", 0) + if type(files_changed) is not int or files_changed < 0: + raise ValueError("files_changed must be a nonnegative integer.") + if files_changed > 5: + return "commitment" + prompt_lower = prompt.lower() + for kw in HIGH_RISK_KEYWORDS: + if kw in prompt_lower: + return "commitment" + for kw in ROUTINE_KEYWORDS: + if kw in prompt_lower: + return "routine" + return "discovery" + + +def evaluate_three_lanes_baseline(state): + if not isinstance(state, dict): + raise ValueError("Task state must be an object.") + prompt = state.get("prompt", "") + if not isinstance(prompt, str): + raise ValueError("Task prompt must be a string.") + prompt_lower = prompt.lower() + evidence_tier = state.get("evidence_tier", "t0") + if evidence_tier not in ("t0", "t1", "t2", "t3", "t4"): + raise ValueError("evidence_tier must be one of t0, t1, t2, t3, t4.") + + if evidence_tier == "t0" or any(kw in prompt_lower for kw in ["maybe", "i think", "someone said"]): + evidence_verdict = "stop_reframe" + evidence_tier = "t0" + elif evidence_tier == "t1": + evidence_verdict = "verify" + else: + evidence_verdict = "continue" + + if any(kw in prompt_lower for kw in ["bypass auth", "disable security", "free tier exploit"]): + business_verdict = "stop_reframe" + elif any(kw in prompt_lower for kw in ["billing", "payment", "paid"]): + business_verdict = "verify" + else: + business_verdict = "continue" + + if any(kw in prompt_lower for kw in ["everyone", "anyone", "all users"]) and "commitment" in prompt_lower: + user_verdict = "verify" + else: + user_verdict = "continue" + + lane_verdicts = { + "user_flow": user_verdict, + "evidence_flow": evidence_verdict, + "business_flow": business_verdict, + } + max_sev = max(SEVERITY[v] for v in lane_verdicts.values()) + combined_verdict = VERDICTS[max_sev] + + priority = {"evidence_flow": 0, "user_flow": 1, "business_flow": 2} + def flow_sort(flow): + return (-SEVERITY[lane_verdicts[flow]], priority[flow]) + weakest_flow = sorted(lane_verdicts.keys(), key=flow_sort)[0] + + return { + "advisory": True, + "user_flow": user_verdict, + "evidence_flow": evidence_verdict, + "business_flow": business_verdict, + "evidence_tier": evidence_tier, + "combined_verdict": combined_verdict, + "weakest_flow": weakest_flow, + } + + +def generate_boundary(state): + if not isinstance(state, dict) or not isinstance(state.get("review"), dict): + raise ValueError("A canonical review is required; task metadata cannot authorize execution.") + if __package__: + from .check_review import check, check_handoff + else: + from check_review import check, check_handoff + + review = state["review"] + problems = check(review) + if problems: + raise ValueError("Invalid review: " + "; ".join(problems)) + if review["combined_verdict"] == "continue": + pack = state.get("context_pack") + if not isinstance(pack, dict): + raise ValueError("A continue review requires its validated context_pack.") + problems = check_handoff(review, pack) + if problems: + raise ValueError("Invalid handoff: " + "; ".join(problems)) + + boundary = copy.deepcopy(review["execution_boundary"]) + boundary.update({ + "verdict": review["combined_verdict"], + "review_id": review["review_id"], + "weakest_flow": review["weakest_flow"], + }) + for field in ["stop_conditions", "human_approval_gates", "high_risk_actions", "proof_step", "reframed_question"]: + if field in review: + boundary[field] = copy.deepcopy(review[field]) + return boundary + + +def main(): + parser = argparse.ArgumentParser(description="Offline advisory routing and canonical review boundary validation.") + subparsers = parser.add_subparsers(dest="command", required=True) + + route_p = subparsers.add_parser("route") + route_p.add_argument("prompt", help="User intent or task description") + + eval_p = subparsers.add_parser("evaluate") + eval_p.add_argument("--task", required=True, help="Path to task JSON state") + + bound_p = subparsers.add_parser("boundary") + bound_p.add_argument("--task", required=True, help="JSON containing review and, for continue, context_pack") + + args = parser.parse_args() + + try: + if args.command == "route": + route = classify_route_baseline(args.prompt) + print(json.dumps({"route": route, "bypass": False, "review_required": True})) + return 0 + state = json.loads(Path(args.task).read_text(encoding="utf-8")) + if args.command == "evaluate": + res = evaluate_three_lanes_baseline(state) + else: + res = generate_boundary(state) + print(json.dumps(res, indent=2)) + return 0 + except (OSError, ValueError) as exc: + print(str(exc), file=sys.stderr) + return 1 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/skills/product-design-harness/resources/templates/README.md b/skills/product-design-harness/resources/templates/README.md new file mode 100644 index 000000000..98a4992fd --- /dev/null +++ b/skills/product-design-harness/resources/templates/README.md @@ -0,0 +1,13 @@ +# Templates + +| File | Use | +|---|---| +| `product-brief.md` | Input brief before review. | +| `gate-review.md` | UX3 review output. | +| `ux3-council-review.md` | Extended stage, claim, confidence, and council output. | +| `context-pack.md` | Handoff after Continue verdict. | +| `decision-log.md` | Durable decision record. | +| `override-ledger.md` | Active verdict overrides; three on one area force verify. | + +Every completed review uses `../schemas/review-result.schema.json`. Templates +are human-readable companions, not alternate contracts. diff --git a/skills/product-design-harness/resources/templates/context-pack.md b/skills/product-design-harness/resources/templates/context-pack.md new file mode 100644 index 000000000..5bbabd848 --- /dev/null +++ b/skills/product-design-harness/resources/templates/context-pack.md @@ -0,0 +1,117 @@ +# Context Pack Template + +Use this only after Product Design Harness returns `continue`. + +This template maps to `schemas/context-pack.schema.json`. + +## 1. Contract + +| Field | Answer | +|---|---| +| schema_version | 2.1 | +| working_language | en / zh-TW / zh-CN / ja / ko / es / fr / de / pt | +| canonical_identifiers | en | +| fallback_language | en | +| review_id | | +| stage | idea / prototype / launch / scale | +| combined_verdict | continue | + +## 2. Goal + +What outcome should execution achieve? + +## 3. Approved Product Boundary + +| Field | Answer | +|---|---| +| actor_boundary.target_population | | +| Operator | | +| Beneficiary | | +| Machine or agent actor | | +| Affected people | | +| Excluded groups | | +| Product organization | | +| Project owner | | +| Issuer | | +| Stakeholder effects | | +| Unresolved assumptions | | + +## 4. Human Judgment Boundary + +| Field | Answer | +|---|---| +| Human-owned decisions | | +| Machine-supported inputs | | +| Not mechanized | | +| Named human approval gate | | +| Accountable owner | | +| Condition | | + +## 5. Scope + +Copy the approved review's execution_boundary.may_do list exactly. Any new, +removed, reordered, or reworded scope item requires an updated review. + +## 6. Non-Goals + +What must not be done? + +## 7. User Rules + +| Rule | Notes | +|---|---| +| Actor boundary | | +| Affected people | | +| Excluded groups | | +| Mental model | | +| Recovery path | | + +## 8. Evidence Rules + +| Rule | Notes | +|---|---| +| Evidence snapshot IDs | | +| Measurement hooks | | +| Failure criteria | | +| Trace requirement | | +| Review point | | +| Evidence freshness | | + +## 9. Business Rules + +| Rule | Notes | +|---|---| +| Value | | +| Cost boundary | | +| Retention logic | | +| Distribution constraint | | + +## 10. Acceptance Criteria + +- + +## 11. Stop Conditions + +- + +## 12. Execution Boundary + +| Field | Answer | +|---|---| +| May do | | +| Must not do | | +| Must ask | | +| Named human approval gate | | +| Accountable owner | | +| Condition | | +| Rollback plan | | + +## 13. High-Risk Actions + +| Action | Named human approval gate | Accountable owner | Condition | Rollback plan | +|---|---|---|---|---| +| | | | | | + +## 14. Handoff Notes + +What should execution know before starting? diff --git a/skills/product-design-harness/resources/templates/decision-log.md b/skills/product-design-harness/resources/templates/decision-log.md new file mode 100644 index 000000000..da5332425 --- /dev/null +++ b/skills/product-design-harness/resources/templates/decision-log.md @@ -0,0 +1,48 @@ +# Decision Log Template + +## Identity + +| Field | Answer | +|---|---| +| Decision ID | | +| Review ID | | +| Date | YYYY-MM-DD | +| Stage | idea / prototype / launch / scale | +| Verdict | continue / verify / stop_reframe | +| Evidence tier | t0 / t1 / t2 / t3 / t4 | + +## Decision + +What did we decide? + +## Evidence Used + +| Evidence ID | Signal | Tier | Freshness | Decision impact | +|---|---|---|---|---| +| | | | | | + +## Trade-Off + +What did we protect, and what did we sacrifice? + +## Human-Owned Judgment + +| Field | Answer | +|---|---| +| Decision type | taste / risk / strategy / ethics / meaning / none | +| Accountable owner | | +| Options considered | | +| Rationale | | +| Reversal conditions | | + +## Next Action + +One action only: + +## Stop Conditions + +- + +## Review Date + +When should this decision be revisited? diff --git a/skills/product-design-harness/resources/templates/gate-review.md b/skills/product-design-harness/resources/templates/gate-review.md new file mode 100644 index 000000000..41ef259c0 --- /dev/null +++ b/skills/product-design-harness/resources/templates/gate-review.md @@ -0,0 +1,97 @@ +# Gate Review Template + +Human-readable companion to `schemas/review-result.schema.json`. + +## 1. Contract + +| Machine field | Answer | +|---|---| +| schema_version | 2.1 | +| working_language | en / zh-TW / zh-CN / ja / ko / es / fr / de / pt | +| canonical_identifiers | en | +| fallback_language | en | +| review_id | | +| product_direction | | +| mode | quick_gate / standard_gate | +| stage | idea / prototype / launch / scale | + +## 2. Product Context + +| Field | Answer | +|---|---| +| actor_boundary.target_population | | +| Operator | | +| Beneficiary | | +| Machine or agent actor | | +| Affected people | | +| Excluded groups | | +| Product organization | | +| Project owner | | +| Issuer | | +| Stakeholder effects | | +| Unresolved assumptions | | + +## 3. Human Judgment Boundary + +| Field | Answer | +|---|---| +| Human-owned decisions | | +| Machine-supported inputs | | +| Not mechanized | | +| Named human approval gate | | +| Accountable owner | | +| Condition | | + +## 4. Canonical Result + +| Machine field | Answer | +|---|---| +| combined_verdict | continue / verify / stop_reframe | +| weakest_flow | user / evidence / business | +| strongest_signal | | +| riskiest_claim | | +| main_uncertainty | | +| confidence_level | very_low / low / medium / high / very_high | +| evidence_tier | t0 / t1 / t2 / t3 / t4 | +| main_trade_off | | +| human_owned_decision | taste / risk / strategy / ethics / meaning / none | +| human_decision_record_id | | +| evidence_receipt_ids | | +| next_smallest_action | | +| context_pack_required | true / false | + +## 5. Lane Reviews + +| Flow | Verdict | Evidence tier | Strongest signal | Weakest assumption | Missing evidence | Disconfirming evidence | Stop condition | +|---|---|---|---|---|---|---|---| +| User | | | | | | | | +| Evidence | | | | | | | | +| Business | | | | | | | | + +## 6. Execution Boundary + +| Field | Answer | +|---|---| +| May do | | +| Must not do | | +| Must ask | | + +## 7. Human Approval Gates + +| Named human approval gate | Accountable owner | Condition | +|---|---|---| +| | | | + +## 8. High-Risk Actions + +| Action | Named human approval gate | Accountable owner | Condition | Rollback plan | +|---|---|---|---|---| +| | | | | | + +## 9. Verdict Branch + +| Field | Answer | +|---|---| +| proof_step for verify | | +| reframed_question for stop_reframe | | +| stop_conditions | | diff --git a/skills/product-design-harness/resources/templates/override-ledger.md b/skills/product-design-harness/resources/templates/override-ledger.md new file mode 100644 index 000000000..c5052ded6 --- /dev/null +++ b/skills/product-design-harness/resources/templates/override-ledger.md @@ -0,0 +1,27 @@ +# Override Ledger + +One row per verdict override, kept where every reviewer can see it. +The ledger exists because one override is judgment and ten quiet +overrides are policy nobody agreed to. + +Rules: + +- Any new review of a direction with an active override must list that + override in its inputs. +- Three or more active overrides on one product area force a `verify` + on the next review of that area, with this ledger cited as evidence. +- A row leaves the Active table only by expiry, a fired tripwire, or a + renewal review - never by deletion. Move it to History with the exit + reason. + +## Active + +| override_id | review_id | accountable_owner | overridden_verdict | expires_at | tripwire status | +|---|---|---|---|---|---| +| | | | | | | + +## History + +| override_id | exit reason (expired / tripwire fired / renewed by review) | date | +|---|---|---| +| | | | diff --git a/skills/product-design-harness/resources/templates/product-brief.md b/skills/product-design-harness/resources/templates/product-brief.md new file mode 100644 index 000000000..d49ebf348 --- /dev/null +++ b/skills/product-design-harness/resources/templates/product-brief.md @@ -0,0 +1,118 @@ +# Product Brief Template + +This template maps to `schemas/product-brief.schema.json`. + +## 1. Contract + +| Field | Answer | +|---|---| +| schema_version | 2.1 | +| working_language | en / zh-TW / zh-CN / ja / ko / es / fr / de / pt | +| canonical_identifiers | en | +| fallback_language | en | + +## 2. Product Direction + +What are we considering? + +## 3. Accountable Owner + +Who owns the final human decision? + +## 4. Stage + +Choose one: + +- Idea +- Prototype +- Launch +- Scale + +## 5. Actor Boundary + +| Field | Answer | +|---|---| +| actor_boundary.target_population | | +| Operator | | +| Beneficiary | | +| Machine or agent actor | | +| Affected people | | +| Excluded groups | | + +## 6. Business Boundary + +| Field | Answer | +|---|---| +| Product organization | | +| Project owner | | +| Issuer | | +| Customers | | +| Buyers | | +| Operators | | +| Partners | | +| Funders | | +| Platforms | | +| Regulators | | +| Externality bearers | | +| Decision authority | | +| Value exchange | | + +## 7. Human Judgment Boundary + +| Field | Answer | +|---|---| +| Human-owned decisions | | +| Machine-supported inputs | | +| Not mechanized | | +| Named human approval gate | | +| Accountable owner | | +| Condition | | + +## 8. Unresolved assumptions + +- + +## 9. Execution Boundary + +| Field | Answer | +|---|---| +| May do | | +| Must not do | | +| Must ask | | + +## 10. Problem Hypothesis + +Write one sentence: + +`[actor] in [situation] faces [problem] with [frequency/cost], currently solves it by [workaround], and we will know it is real if [evidence standard].` + +## 11. Current Evidence + +| Signal | Source | Evidence tier | Collected at | Decision it supports | +|---|---|---|---|---| +| | | | | | + +## 12. Business Goal + +What business outcome matters? + +## 13. Constraints + +| Constraint | Notes | +|---|---| +| Time | | +| Budget | | +| Data | | +| Brand | | +| Legal / policy | | +| Technical | | + +## 14. Proposed Next Step + +What do we want to do next? + +## 15. Known Risks + +| Risk | Reversibility | Accountable owner | Condition | Rollback plan | +|---|---|---|---|---| +| | | | | | diff --git a/skills/product-design-harness/resources/templates/ux3-council-review.md b/skills/product-design-harness/resources/templates/ux3-council-review.md new file mode 100644 index 000000000..a4b6062d3 --- /dev/null +++ b/skills/product-design-harness/resources/templates/ux3-council-review.md @@ -0,0 +1,50 @@ +# UX3 Review Template + +Use `templates/gate-review.md` for the canonical final result. + +## Claim Graph + +| ID | Type | Claim | Support | Counter-signal | Depends on | Breaks if false | Proof step | Stop condition | +|---|---|---|---|---|---|---|---|---| +| | | | | | | | | | + +## Independent Reviews + +Each reviewer returns `schemas/reviewer-verdict.schema.json` with +`review_round: independent`. + +| Reviewer | Verdict | Evidence tier | Strongest signal | Weakest assumption | +|---|---|---|---|---| +| User Flow | | | | | +| Evidence Flow | | | | | +| Business Flow | | | | | + +## Challenge Round + +| Reviewer | objection_to | counter_evidence | position_change | +|---|---|---|---| +| User Flow | | | | +| Evidence Flow | | | | +| Business Flow | | | | + +## Uncertainty + +| Field | Answer | +|---|---| +| Evidence tier | t0 / t1 / t2 / t3 / t4 | +| Confidence level | very_low / low / medium / high / very_high | +| Risk class | r1 / r2 / r3 / r4 | +| Reversibility | low / medium / high | +| Main uncertainty | | +| Freshness risk | | +| Proof bar | | + +## Human Judgment + +| Field | Answer | +|---|---| +| Decision type | taste / risk / strategy / ethics / meaning | +| Accountable owner | | +| Options considered | | +| Rationale | | +| Reversal conditions | | From c9e35bbd8e016b0c9546f64a4a0d9e5b89126e3e Mon Sep 17 00:00:00 2001 From: cis2042 Date: Fri, 23 Oct 2026 12:21:10 +0800 Subject: [PATCH 2/2] fix: preserve schema matching with spelling-compatible regex --- .../resources/schemas/context-pack.schema.json | 2 +- .../resources/schemas/review-result.schema.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/skills/product-design-harness/resources/schemas/context-pack.schema.json b/skills/product-design-harness/resources/schemas/context-pack.schema.json index 11022f8b8..8de46d7ba 100644 --- a/skills/product-design-harness/resources/schemas/context-pack.schema.json +++ b/skills/product-design-harness/resources/schemas/context-pack.schema.json @@ -210,7 +210,7 @@ "may_do": { "contains": { "type": "string", - "pattern": "([Cc]ustomer-facing|[Pp]ermissions|[Dd]ata handling|[Pp]roduction schema|[Ee]xternal action|[Rr]emove human approval|[Aa]utonomous)" + "pattern": "([Cc]ustomer-facing|[Pp]ermissions|[Dd]ata handling|(?:Production|production) schema|[Ee]xternal action|[Rr]emove human approval|[Aa]utonomous)" } } }, diff --git a/skills/product-design-harness/resources/schemas/review-result.schema.json b/skills/product-design-harness/resources/schemas/review-result.schema.json index 076c054be..b37684f1f 100644 --- a/skills/product-design-harness/resources/schemas/review-result.schema.json +++ b/skills/product-design-harness/resources/schemas/review-result.schema.json @@ -805,7 +805,7 @@ "may_do": { "contains": { "type": "string", - "pattern": "([Cc]ustomer-facing|[Pp]ermissions|[Dd]ata handling|[Pp]roduction schema|[Ee]xternal action|[Rr]emove human approval|[Aa]utonomous)" + "pattern": "([Cc]ustomer-facing|[Pp]ermissions|[Dd]ata handling|(?:Production|production) schema|[Ee]xternal action|[Rr]emove human approval|[Aa]utonomous)" } } },