productfoo 0.0.0-stage → 1.0.1

package/skills/product-copywriting/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: product-copywriting
+description: "Use when working on ThisProduct copy, reducing jargon, explaining the product, editing the static prototype under design system/thisproduct, or deciding whether terms like Spec, Cross-functional Spec, drift, evidence, provenance, source packets, tokens, routing, or agents should appear in user-facing language."
+---
+
+## Human-facing voice
+
+Before writing for a person, load `foo skill product-copywriting/references/foo-voice.md`
+and apply it within this skill's required output format. Keep the evidence record
+and workflow responsibilities intact. If the reference cannot be loaded, report
+the delivery gap and preserve evidence, uncertainty and dissent explicitly.
+
+## Usage
+
+Use this skill when its frontmatter description matches the user request. Follow the workflow and constraints below.
+
+
+# ThisProduct Copywriting
+
+Use this skill to make ThisProduct understandable without flattening the product. The working test is: a product leader should be able to explain the screen out loud after reading it once.
+
+## Source Of Truth
+
+Before rewriting, read the smallest relevant set:
+
+- `AGENTS.md` for product constraints and source boundaries.
+- `README.md` for the current product definition.
+- `docs/prototypes/2026-06-11-thisproduct-jargon-audit.md` for the full jargon backlog.
+- `design system/thisproduct/components.jsx` and `design system/thisproduct/data.js` when changing prototype UI text.
+
+Do not import private Obsidian notes, meeting notes, or local context into repo copy unless the user explicitly asks.
+
+## Protected Product Language
+
+Keep these terms, but define or contextualize them early:
+
+- `ThisProduct`: product name.
+- `Initiative`: the main unit of product work.
+- `Cross-functional Spec`: the core spec object. Use this exact capitalization.
+- `Spec`: product-facing shorthand. Use `Spec`, not `Adaptive Spec Packet`, in UI and marketing copy.
+- `Evidence`: the trust layer behind every claim.
+- `Agent`: acceptable because ThisProduct is about people working with agents.
+- `Drift`: acceptable only after explaining it as work changing from the approved plan.
+
+Use repo paths such as `specs/<name>/` only when they are real implementation source references. Product-facing labels should say `Spec`.
+
+## Default Translations
+
+Use these replacements unless the source context requires the exact technical term:
+
+| Avoid | Prefer |
+|---|---|
+| Adaptive Spec Packet | Spec |
+| Cross-functional spec | Cross-functional Spec |
+| provenance | where this came from |
+| source-backed | with links back to the source |
+| source-agnostic | works across your tools |
+| demo substrate | demo source |
+| source packets | approved source bundles |
+| expected output fixture | expected result |
+| thisproduct graph | initiative map |
+| lens | view |
+| product implication | why this matters |
+| agent decision | what the agent changed |
+| result contract | agent result report |
+| trace | record of what happened |
+| telemetry | usage data or activity data |
+| routing receipts | savings proof |
+| task class | type of work |
+| callsite | AI call |
+
+## Page Jobs
+
+Rewrite page by page. Do not try to explain the whole system on every screen.
+
+- Home: answer what is happening, what needs attention, and what can be trusted.
+- Initiative Spec: explain the Cross-functional Spec before showing views, requirements, or source links.
+- Drift: say what changed, why it matters, and what the user should do.
+- Spend and Impact: make cost decision-oriented before showing tokens, routing, or ROI.
+- Routing: first say ThisProduct helps spend less on AI calls without lowering quality; only then introduce modes or receipts.
+- Ideas: emphasize grouped inputs and a ranked list; keep scoring methods secondary.
+- Forecast: separate real forecasts from demo forecasts, then say what action changes a date.
+- Activity: keep it as a plain event feed.
+
+## Voice Rules
+
+The shared productfoo voice reference loaded above governs human explanations across
+products. The protected ThisProduct terms and prototype paths in this skill are
+local product rules, not a vocabulary to impose on every productfoo answer.
+
+- Lead with the user job, then introduce the ThisProduct noun.
+- Prefer concrete nouns and verbs over category language.
+- Keep one idea per section.
+- Show uncertainty directly; do not turn weak evidence into certainty.
+- Preserve source boundaries. Synthetic data must be labeled synthetic.
+- Do not use hype words such as `revolutionary`, `seamless`, `innovative`, or `AI-powered` unless quoted from a source.
+- Do not make token savings the parent thesis. The parent thesis is making product work legible to people and agents.
+
+## Editing Workflow
+
+When changing prototype copy:
+
+1. Find visible strings in `design system/thisproduct/components.jsx`, `design system/thisproduct/data.js`, and `design system/thisproduct/app.jsx`.
+2. Update tests before production copy when behavior or canonical terms change.
+3. Keep source paths and Proof document routes working.
+4. Preserve demo-vs-real boundaries; do not invent operating data for ThisProduct dogfood mode.
+5. Run the prototype checks after editing:
+
+```bash
+node "design system/thisproduct/prototype-smoke.test.mjs"
+node "design system/thisproduct/data-mode.test.mjs"
+node "design system/thisproduct/decision-accordion.test.mjs"
+node "design system/thisproduct/spend-action.test.mjs"
+```
+
+6. Run a terminology sweep:
+
+```bash
+rg -n "Adaptive Spec Packet|cross-functional spec|Cross-functional spec|Full spec|What this spec is planning" "design system/thisproduct"
+```
+
+Uppercase `Adaptive Spec Packet` should not appear in product-facing prototype copy. Product-facing labels should say `Spec`; repo-path references may use `specs/<name>/` when needed.
+
+## Error Handling
+
+- If required files, tools, connectors, credentials, or source artifacts are unavailable, state the blocker clearly and continue only with safe local evidence.
+- If the user request requires missing product judgment or source-boundary approval, ask one focused question before proceeding.

package/skills/product-copywriting/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "ThisProduct Copywriting"
+  short_description: "Plain-language copy rules for ThisProduct"
+  default_prompt: "Use $product-copywriting to rewrite the current ThisProduct prototype page in product-facing language."

package/skills/product-copywriting/references/foo-voice.md

@@ -0,0 +1,26 @@
+## productfoo voice for people
+
+When briefing a person, give the recommendation, its concrete reason, what is
+uncertain or disputed, and the useful next action. Follow the required output
+format; this guidance changes phrasing, not fields or workflow responsibilities.
+
+- Use concrete nouns and verbs. Keep a specialist term when it is more precise,
+  and explain it when the reader needs that meaning to decide.
+- Say what you actually inspected and what it supports. Distinguish evidence
+  from inference in ordinary sentences: “The test covers X” and “I expect Y,
+  but have not checked it.” Name the specific unknown and what would settle it.
+- Keep material dissent, source limits and required approvals in the answer,
+  with their original strength. A shorter or warmer answer must not turn an
+  unresolved risk into reassurance. Keep citations close to their claims.
+- Be candid and respectful. Dry humor can name frustrating work; aim it at the
+  situation, not the person. Describe missing evidence without guessing motives
+  or implying deception. Do not invent feelings, experience, checks or praise.
+- Ask the unresolved choice the person needs to make, with your recommendation
+  and tradeoff. Use the active workflow's question budget and consultation rules.
+- End with the concrete next step. Skip repeated process narration and stock
+  offers to continue; carry out work already authorized by the person.
+
+Structured records retain their evidence types, confidence, dissent, owners and
+machine status values. Translate those distinctions for the reader; do not erase
+them. Specialist lenses keep their craft. These rules do not change source
+permissions, expert consultation, sequencing, required questions or output schemas.

package/skills/product-shape-interview/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: product-shape-interview
+description: "Run a one-question-at-a-time shaping interview before generating an HTML artifact, scenario prototype, workbench, Build Preview, or visual app exploration from a spec packet, PRD-like spec, approved intake summary, or swarm report. Use when the user wants one solid artifact optimized for a product bet rather than multiple divergent directions, when realistic dummy data is needed to make an app feel real, or when the artifact generator needs a packet-local Shape Brief and exact next generator prompt."
+---
+
+# Product Shape Interview
+
+Shape one artifact before generation. This skill decides what one HTML artifact should prove, what scenario it should make feel real, and what generator prompt should run next.
+
+## Usage
+
+Use with a spec packet, PRD-like spec, approved `interview-me` intake summary, `spec-swarm` report, or existing artifact critique:
+
+```text
+Use $product-shape-interview on <packet-or-spec-path> before generating an artifact.
+```
+
+If no source artifact is provided, ask for the spec packet, spec path, intake summary, swarm report, or artifact critique before shaping.
+
+## Core Rule
+
+Do not generate UI, HTML, Build Previews, scenario prototypes, or mockups during this skill. Produce a Shape Brief first. The next generator must consume that brief.
+
+Default away from multiple directions. Recommend one artifact job unless the source material shows comparison itself is the product question.
+
+## Clarity-First Defaults
+
+The brief must steer the generator toward a clear artifact, not a dense one. Bake these into `Visual And Interaction Posture` and `Design Review Plan` so the downstream generator inherits them. The artifact has failed if a developer finds it confusing.
+
+- One decision per screen, three choices or fewer; trade-offs as a labeled spectrum with exactly one recommendation.
+- Plain language leads; commands, JSON, event schemas, and requirement IDs go behind a "show detail" disclosure, never the default surface.
+- Outcomes shown as plain cards and state chips, not command output.
+- Fix detector P0/P1 before the first show, do not merely report them; treat "busy" or "confusing" as a blocking defect.
+
+## Inputs
+
+Read the provided source artifact and extract:
+
+- Product bet
+- Primary user, buyer, reviewer, or operator
+- Core workflow or broken decision
+- Product objects and relationships
+- Agent behavior, if any
+- Human approval or steering boundaries
+- Trust, provenance, confidence, dissent, and privacy requirements
+- Existing realistic data hints, source constraints, and fake precision risks
+- Required states: empty, loading, populated, error, stale, ambiguous, rejected, approved, regenerated
+- MVP boundary, explicit non-goals, and open questions
+- Prior critique of generated artifacts, if available
+
+Do not use raw private notes, transcripts, or source dumps unless the user explicitly approved them for this shaping run.
+
+## Shaping Interview
+
+Before asking the user, inspect the source artifact and decide what is already answered. Ask only questions that require unique product judgment, taste, appetite for risk, source-boundary approval, or a choice between materially valid options.
+
+### Announce and teach (productfoo brand presence, R-004)
+
+Before the first question, emit the signature frame and a compact announce-and-teach block so the user knows productfoo has taken over the agent's default behavior and learns the loop in the same beat (full on the first interview of a session, one line thereafter):
+
+```
+── foo ▸ shape ──────────────────────────  specs over vibes ──
+You're in foo: I'll ask a few focused questions, then shape the artifact — not autocomplete a guess.
+I've read what you gave me, so I'll only ask what it can't tell me — about 4 questions.
+Say "go deeper" for more, or "just write it" to skip.
+Progress: Q1 / ~4
+```
+
+Say what is about to happen, in the user's words. Do **not** list the fields a spec contains: "the product bet", "source and approval boundaries", "MVP scope and the validation bar", "what still needs human judgment" are productfoo's filing labels, not a first-time user's language, and a list of them is the machinery showing through on the first screen anyone ever sees. The one thing worth teaching is the loop itself — productfoo reads the source artifact and asks only the gaps (that is the whole point of the preflight above) — so say that, and get to Q1. State one count only, the depth you are actually running, and make the progress counter match it. Name the escape hatches explicitly, and drop the box-drawing when output is piped or read by an agent (R-008).
+
+Ask one question at a time. Use numbered options with a recommendation when defensible:
+
+```text
+Question: What should this artifact optimize for first?
+
+1. **End-to-end scenario realism (Recommended)**
+   Best when the current artifact does not feel like real software yet.
+2. Agent behavior and approval
+   Best when the product depends on what the agent reads, infers, proposes, and waits on.
+3. Product model clarity
+   Best when the app category, objects, and workflow shape are still unclear.
+4. Visual application realism
+   Best when the product model is settled but the screens need to feel credible.
+```
+
+Rules:
+
+- Keep options numbered `1` through `4` when practical.
+- Mark exactly one option with `(Recommended)` when evidence supports it.
+- Bold the recommended option label in Markdown.
+- If no recommendation is defensible, say `No recommendation yet` before the options.
+- Wait for the user's answer before asking the next question.
+- Do not ask for facts that the spec, packet, code, design system, or approved context can answer.
+
+High-value shaping questions:
+
+- What should the artifact optimize for first: product model, agent behavior, end-to-end workflow, realistic data, visual credibility, or decision export?
+- What kind of artifact should exist: scenario prototype, product model explorer, agent trace player, app mock, decision workbench, or hybrid?
+- What one scenario should the user feel from start to finish?
+- Which object model should anchor the artifact: task, case, packet, source, user journey, decision, queue item, or agent run?
+- What must the agent see, believe, propose, ask approval for, revise, and export?
+- What realistic dummy data would make the product feel real?
+- What states or edge cases must appear so the artifact does not feel fake?
+- What should the human be able to decide after using the artifact?
+- What should stay out of the artifact because it would create fake precision or false product truth?
+- What exact generator should run next?
+
+## Shape Brief Contract
+
+Write the accepted brief inside the source packet:
+
+```text
+<packet>/artifacts/shapes/<run-id>/shape.md
+```
+
+If the input is not a packet, write the brief beside the input artifact in the nearest reasonable `artifacts/shapes/<run-id>/shape.md` location and explain the location.
+
+Use a timestamped, slugged run ID such as `2026-06-19-scheduling-scenario`.
+
+The Shape Brief must include:
+
+```markdown
+# Product Shape Brief
+
+Source:
+Run ID:
+Status:
+Created:
+
+## Optimization Target
+
+## Artifact Type
+
+## Primary Scenario
+
+## Primary Reviewer
+
+## Product Model
+
+## Core Objects
+
+## Agent Loop
+
+## Human Decision
+
+## Realistic Dummy Data Contract
+
+## Required States
+
+## Trust And Provenance
+
+## Visual And Interaction Posture
+
+## Design Review Plan
+
+## Non-Goals
+
+## Open Questions
+
+## Generator Prompt
+```
+
+### Field Guidance
+
+- `Optimization Target`: name the main thing the artifact must prove, not a list of all goals.
+- `Artifact Type`: choose one primary type such as `scenario prototype`, `product model explorer`, `agent trace player`, `application mock`, or `decision workbench`.
+- `Primary Scenario`: describe the one workflow slice the artifact must make feel real.
+- `Product Model`: name the app shape, such as queue, cockpit, canvas, wizard, inbox, review room, ledger, timeline, or operating surface.
+- `Core Objects`: list the objects the artifact must make tangible, with relationships.
+- `Agent Loop`: show `read -> infer -> propose -> approval boundary -> revise -> outcome/export` when the product is agentic.
+- `Realistic Dummy Data Contract`: define plausible records, names, statuses, timestamps, source labels, masked/private fields, stale evidence, errors, and edge cases. Avoid gray placeholder bars as primary content.
+- `Required States`: include enough states to make the product behavior credible.
+- `Trust And Provenance`: define what evidence, source boundary, confidence, dissent, or privacy markers must be visible.
+- `Visual And Interaction Posture`: state the design system, density, motion, and app realism expectations without turning the brief into a full design spec. Default to clarity-first: plain language leads, three choices or fewer, and implementation detail (commands, JSON, requirement IDs) sits behind progressive disclosure.
+- `Design Review Plan`: name which post-generation review should run, usually `$impeccable critique <artifact>`, plus `$impeccable audit <artifact>` or `$impeccable polish <artifact>` when the artifact promises responsive, accessible, production-like behavior. Require P0/P1 fixed before the first show, not merely reported. If Impeccable is unavailable, require a manual review gap to be recorded.
+- `Non-Goals`: explicitly forbid four divergent directions unless comparison is the chosen artifact job.
+- `Generator Prompt`: include the exact next prompt an agent can run.
+
+## Generator Prompt Contract
+
+End every brief with a directly runnable prompt:
+
+```text
+Use $scenario-workbench on <path-to-shape.md>.
+Generate one HTML artifact optimized for the approved Shape Brief. Do not generate four directions unless the Shape Brief says comparison is the optimization target.
+After generation, run the Shape Brief's Design Review Plan and report the critique snapshot path, score, P0/P1 findings, and remaining gaps.
+```
+
+If `scenario-workbench` does not exist yet, route to the closest available generator and make the gap explicit:
+
+```text
+Use $preview-swarm on <path-to-shape.md>, but treat the Shape Brief as authoritative: generate one scenario workbench, not divergent Build Preview directions.
+After generation, run the Shape Brief's Design Review Plan and report the critique snapshot path, score, P0/P1 findings, and remaining gaps.
+```
+
+## Event Logging
+
+If working inside a spec packet with `events.jsonl`, append an event only after the user accepts the Shape Brief or explicitly asks to record it. The event should point to the shape path and summarize the optimization target. Do not treat the shape as canonical product truth until accepted.
+
+## Output
+
+Return:
+
+- Shape Brief path
+- Optimization target
+- Artifact type
+- Primary scenario
+- Dummy data contract summary
+- Generator prompt
+- Remaining user-judgment questions, if any
+
+## Error Handling
+
+- If the source artifact is missing, ask for the packet, spec path, intake summary, swarm report, or artifact critique before shaping.
+- If the source is too thin to choose an optimization target, route back to `interview-me` before writing a fake Shape Brief.
+- If the user wants immediate artifact generation, explain that this skill is a pre-generation gate and ask whether to skip the gate explicitly.
+- If the artifact should use private sources, ask for source-boundary approval before including private-derived facts in the Shape Brief.
+- If the run is not packet-local, explain where the brief will be written before writing it.
+- If no generator skill exists for the chosen artifact type, write the brief anyway and put the generator gap in the prompt section.

package/skills/product-shape-interview/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Product Shape Interview"
+  short_description: "Shape one artifact before generation."
+  default_prompt: "Use $product-shape-interview on this spec packet before generating an artifact."

package/skills/ready-for-release/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: ready-for-release
+description: "Use when a product change needs an evidence-backed Build, Beta, GA, or release-note readiness decision."
+---
+
+# Ready For Release
+
+## Usage
+
+Issue a readiness result only from inspected proof. A retrieval failure is a
+blocked assessment, never a readiness verdict.
+
+1. Confirm the release stage and approved packet or local release source.
+2. Inspect requirement proof, tests, rollout and rollback plan, owner decisions,
+   customer impact, documentation, privacy/legal status, and unresolved risks.
+3. Use approved sanitized evidence or validated research when a readiness claim
+   depends on customers or the market. Connector access alone is not approval.
+4. Return exactly one result: `READY`, `NOT READY`, or `BLOCKED`. `READY` requires
+   every stage-critical check to have proof; unknown is not pass.
+5. List blocking checks, dissent, owners, and exact next actions. Draft release
+   notes locally only when explicitly requested; do not send them.
+
+### Source ledger
+
+- **Sources used** — proof/reference, approval, retrieval outcome, and receipt status.
+- **Sources omitted** — every optional release-information lane not used and why.
+- **Trust status** — verified proof, approved evidence, owner decision, or unknown.
+- **Limits** — checks not assessable and human sign-offs still required.
+
+Optional omissions appear in both the human result and any release artifact.
+
+## Error Handling
+
+- On a required retrieval failure, issue no readiness verdict. Return `status:
+  blocked`, `did_not_run: release readiness`, `missing: <source>`, `next action:
+  <exact recovery step>`, and `exit: nonzero`.
+- If an optional source fails, list it under **Sources omitted** and lower the
+  scope or confidence; never replace it with general knowledge.
+- If proof conflicts, return `NOT READY` or `BLOCKED` with the conflict visible.

package/skills/ready-for-release/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Ready For Release"
+  short_description: "Make an evidence-backed release-readiness decision."
+  default_prompt: "Use $ready-for-release for the relevant workflow."

package/skills/redact-transcripts/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: redact-transcripts
+description: "Use when transcript handling needs a redaction plan but observing or rewriting the source would require private-file access."
+---
+
+# Redact Transcripts
+
+## Usage
+
+This draft keeps its file-ingress boundary. It may provide an in-chat redaction
+checklist or local outline without seeing the transcript; it must stop before
+opening, enumerating, fingerprinting, rewriting, or reporting metadata about a file.
+
+The checklist covers direct identifiers, quasi-identifiers, credentials, private
+URLs, company-confidential facts, quoted third parties, and re-identification risk.
+It is not proof that an unseen transcript is safe.
+
+## Error Handling
+
+- When a path or upload is supplied, return `status: blocked`, `did_not_run:
+  transcript observation`, `missing: safe file-ingress`, `next action: use the
+  approved in-memory discovery flow to produce sanitized evidence`, `exit: nonzero`.
+- Do not ask the user to paste raw content into chat as a workaround.

package/skills/redact-transcripts/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Redact Transcripts"
+  short_description: "Plan redaction without observing a private transcript file."
+  default_prompt: "Use $redact-transcripts for the relevant workflow."

package/skills/research-brief/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: research-brief
+description: "Use when a product question needs a scoped research plan, study brief, hypotheses, participant criteria, or evidence plan before research begins."
+---
+
+# Research Brief
+
+## Usage
+
+Create a decision-oriented research plan from explicit intent and approved
+context. Do not inspect a private source merely because a connector can see it.
+
+1. Frame the decision, target segment, known evidence, deadline, and what would
+   change as a result of the study.
+2. Use repo facts and approved sanitized material already in context. Do not
+   open, read, or inspect any new local or private material. For connector data,
+   require `foo source discover` plus packet-scoped `foo source approve` before
+   reading; connector access is not approval.
+3. Write research questions and falsifiable hypotheses, then choose the smallest
+   method and participant set that can answer them.
+4. Specify recruitment, consent, privacy, analysis, evidence labels, decision
+   owner, and stop conditions. Raw transcripts and PII stay out of Git.
+5. Present a short proposal for human confirmation before the full brief. Return
+   in chat by default; write only to an explicitly approved local destination.
+
+### Brief shape
+
+Decision · background · hypotheses · questions · method · participants · source
+plan · consent/privacy · analysis · risks · timeline · decisions needed.
+
+### Source ledger
+
+- **Sources used** — source class, approval scope, and stable reference.
+- **Sources omitted** — every optional prior-study, customer, or analytics lane not used.
+- **Trust status** — repo fact, approved sanitized evidence, or hypothesis.
+- **Limits** — evidence gaps and decisions that remain with a person.
+
+Optional omissions are named in both the human summary and the brief artifact.
+
+## Error Handling
+
+- If the decision, required private-source approval, consent, or access is
+  missing, do not inspect the private source. Return `status: blocked`, name
+  what did not run, give the exact `next action`, and set `exit: nonzero`.
+- If an optional source is unavailable, continue only when the remaining plan
+  is still valid and list it under **Sources omitted**.
+- If the requested study would collect unnecessary sensitive data, propose a
+  lower-data method and require human approval before proceeding.

package/skills/research-brief/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Research Brief"
+  short_description: "Plan a decision-oriented study from approved context."
+  default_prompt: "Use $research-brief for the relevant workflow."

package/skills/research-refresh/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: research-refresh
+description: "Use when new approved evidence should refresh an existing research brief, digest, or strategic analysis through decision-relevant amendments or an explicit no-change result."
+---
+
+# Research Refresh
+
+## Usage
+
+Refresh what the evidence changes about a named decision. Preserve the existing
+artifact's structure; a newer source alone is not a reason to rewrite it.
+
+1. Identify the existing artifact, its decision or working thesis, the currency
+   window, and the claims to check. Derive materiality from that decision: an
+   affected choice, buying criterion, constraint, confidence, or next evidence
+   step. Use criteria already supplied before asking for missing judgment.
+2. Read repo truth, explicitly approved packet evidence, or approved sanitized
+   findings. Research papers must pass `foo research validate <paper.md>` before
+   use. If more public research is needed, use the governed research workflow;
+   connector access alone never authorizes new private-source reads.
+3. Compare new evidence against existing claims. Distinguish unchanged,
+   superseded, contradicted, newly material, and unresolved claims. An event
+   outside the requested window can establish a baseline, but cannot be
+   presented as a new development inside it.
+4. Propose only the smallest decision-relevant amendments. Every proposal names
+   the old claim and locator, new evidence and date, relation, changed decision
+   implication, and replacement text. Preserve uncertainty and counterevidence;
+   a contradiction stays visible even when it changes no recommended action.
+5. If nothing material changed, return **No material updates in the checked
+   scope**, the window and sources checked, omissions, and unresolved claims.
+   This is a result of a completed comparison, not reassurance about unchecked
+   sources or stale evidence.
+6. Return proposals in chat by default, or at a requested local destination.
+   Apply edits only within the user's requested scope. After editing a governed
+   research paper, obtain fresh proof through its research workflow and rerun
+   `foo research validate <paper.md>` before downstream use; the old receipt
+   binds the old bytes. Evidence updates do not automatically change accepted
+   specs, requirements, tasks, or human decisions.
+
+### Review output
+
+Lead with the changed implication or scoped no-change result. Follow with a
+small amendment table: **Existing claim · New evidence · Relation · Decision
+implication · Proposed edit**. Keep contradictions and unresolved claims visible.
+Include **Sources used**, **Sources omitted**, **Trust status**, and **Limits**,
+with clickable references, source dates, confidence and dissent. For examples
+of materiality, no-op and incomplete coverage, read
+[the worked cases](references/worked-cases.md).
+
+This method is invoked on demand. Scheduling, publishing, and automatic PRs
+are separate work; a refresh does not authorize them.
+
+## Error Handling
+
+- If the decision or materiality criterion is missing, use supplied context to
+  resolve it or ask one focused question. Do not invent a universal threshold.
+- If required evidence is inaccessible, unapproved, or fails validation, return
+  `status: blocked`, name the check that did not run, give the next action, and
+  mark the wrapper `exit: nonzero`. Never turn this into a no-change result.
+- If optional sources are missing, continue within the checked scope when the
+  remaining evidence supports an honest comparison, and disclose the omissions.
+- If only raw private material is offered, use productfoo's proof-gated discovery
+  workflow; do not read it here or request a raw paste as a workaround.

package/skills/research-refresh/references/worked-cases.md

@@ -0,0 +1,44 @@
+# Worked refresh cases
+
+These are fictional instruction examples, not observed customer evidence. Use
+them to reason about the decision consequence; do not infer universal thresholds
+or actual skill effectiveness from them.
+
+## A changed constraint warrants an amendment
+
+Decision: choose a supplier whose approved deployment region includes Region A.
+Existing claim: supplier supports Region A; the supplied baseline reference
+records that support. New approved evidence: the supplied current reference
+states that new deployments there are unavailable.
+
+Propose replacing the availability claim and reopening the affected shortlist
+decision. Cite both supplied references and dates. Do not rewrite unrelated
+capability sections or automatically change the decision itself.
+
+## Routine news yields a scoped no-op
+
+Decision: choose a supplier by deployment region and audit requirements. New
+approved evidence: a launch announcement about a cosmetic interface update,
+with no change to either criterion.
+
+Return no material updates in the checked scope, including the window and
+announcement reference. Preserve the original analysis. Do not force a new
+recommendation merely to make the refresh look productive.
+
+## Contradiction remains visible without an immediate decision change
+
+Decision: shortlist suppliers; deployment coverage is still awaiting verification.
+Two current approved references disagree about Region A availability.
+
+Record both claims and their dates as contradictory evidence. Propose a lower
+confidence statement or explicit verification question; do not choose the
+convenient source or omit the conflict because the shortlist has not changed.
+
+## Missing required coverage cannot prove no change
+
+Decision: reassess a shortlist after a required compliance check. That required
+source is unavailable or its paper fails validation.
+
+Report the incomplete comparison and the next action. Do not report a no-op.
+An unavailable optional source may instead be listed as omitted, with any
+conclusion restricted to the evidence actually checked.