--- name: review-evidence description: Weekly evidence review — sweep the product/ artifacts created since the last review against the unverified beliefs in product/overview.md, propose belief-status annotations, report what's drifting, and log human corrections to AI proposals argument-hint: "[review window, e.g. \"last 2 weeks\"; defaults to since the last review]" disable-model-invocation: true --- # /review-evidence The PM's weekly sweep. The other skills produce evidence — interviews, insights, survey analyses, research — but evidence that never updates a belief is filing, not learning. This workflow closes the loop: it reads the new artifacts, contrasts them against the unverified beliefs in `product/overview.md`, and proposes updates. Input: $ARGUMENTS ## Workflow 1. **Establish the window and gather the evidence.** Read `product/overview.md` (the beliefs) and `product/corrections.md` if it exists — its most recent entry marks the last review; the arguments may override the window; if neither exists, this is the first review: cover everything and say so. Then list every artifact under `product/` created or modified in the window: prefer `git log` when the repo is under git; without git, fall back to the `{YYYY-MM-DD-HHMM}-` filename prefixes (and note that in-place revisions — a spec edited after a critique — are invisible to filenames alone). 2. **Contrast the new evidence against each belief.** For every belief — whatever its scope tag, `[product]`, `[opportunity: {slug}]`, or `[feature: {slug}]`; the three are annotated the same way — ask of the new artifacts: does any confirm it, contradict it, or leave it untouched? Cite the evidence file for every verdict — no verdict without a file behind it. Respect the provenance hierarchy, `source: real` > `survey` > `secondary` > `synthetic` (metrics and feedback analyses in `product/insights/` carry the same `source:` header — usage observed from real exposure is `real`): - Real interviews and survey results can confirm or contradict a belief (surveys within the limits their analysis states — small or self-selected samples weaken rather than confirm). - Secondary research raises or lowers a belief's priority, but market evidence cannot verify beliefs about your users (see the `secondary-research` skill). - Synthetic evidence never confirms a belief on its own. Supporting synthetic evidence makes the belief *promising* — say so in the report, propose no annotation. Contradicting synthetic evidence can at most propose `weakened`. 3. **Propose updates to the overview.** For each affected belief, propose an annotation appended on the belief's own line: ``` - {The belief as written} — confirmed by [product/insights/2026-08-20-1430-onboarding.md] (2026-08-20) ``` The three status keywords — `confirmed`, `contradicted`, `weakened` — are fixed English tokens (like `source:` values) so they stay consistent and searchable; the surrounding text follows the file's language. No status = still unverified. Annotations accumulate: when new evidence conflicts with an existing annotation, surface the conflict for the user to resolve — never silently overwrite. Show every proposed edit and get the user's approval before writing. Never delete a belief; only annotate it. 4. **Report what's drifting.** The pendings the loop tends to lose: - Beliefs with no evidence yet, from any source. - Opportunity briefs in `product/opportunities/` whose research agenda has no artifact against it yet — a framed problem nobody started researching — and, once an opportunity's beliefs are contradicted, idea briefs that still hang from it. - Opportunities whose `[value]` beliefs already carry `survey` or `real` evidence and have no solutions file in `product/solutions/` — a problem that holds and nobody compared ways to solve it (`/explore-solutions`). - Idea briefs in `product/ideas/` with a parent opportunity that neither name a solutions file nor declare `solutions explored: no (declared)` — an idea that skipped the comparison silently. - Solutions files with `status: testing-several` (or `chosen`) and no tests file in `product/tests/` naming them — alternatives chosen for testing that nobody designed a test for (`/design-solution-tests`). - Tests files in `product/tests/` with `status: designed` whose tests need material (Material needed is not `none needed`) and have none — tests that cannot run yet (`/build-solution-test`). - Tests files still `designed` or `ready` whose duration or time box has elapsed with no Results section — tests run, or never run, and never analyzed (`/analyze-solution-tests`). - Specs in `product/specs/` written over an alternative from a solutions file whose riskiest belief was neither tested (no tests file, or `not run`) nor declared as untested under *Tested before spec* — a spec that skipped the test silently. - Exposure-plan levels already revealed — by the plan's dates and level durations — with no metrics file in `product/metrics/` naming the spec: a feature in users' hands that nobody defined how to measure (`/design-metrics`). - Metrics files still `status: designed` whose level's duration has elapsed with no metrics analysis in `product/insights/` (`{YYYY-MM-DD-HHMM}-metrics-{spec-slug}.md`): a level revealed and never read (`/analyze-metrics`). - Metrics analyses with a metric `below target` and no feedback analysis (`{YYYY-MM-DD-HHMM}-feedback-{slug}.md` naming it in `metrics-analysis:`) covering the same period: a low number nobody asked why about (`/analyze-feedback`). - `source: synthetic` insights never verified against real users. - Surveys in `product/surveys/` whose first-review date has passed with no analysis in `product/insights/` (a `source: survey` file naming the design) — responses nobody read; and surveys with no Distribution section at all, flagged as "no distribution plan". - Specs in `product/specs/` with no matching critique (`{YYYY-MM-DD-HHMM}-critique-{spec-slug}.md` in `product/insights/`). - If `product/hypotheses/` exists: hypothesis files whose Outcome section is still empty — an experiment exposed but never scored. 5. **Ask the correction question:** "What did you correct this week of what the AI proposed, and why?" Append each correction to `product/corrections.md` — a single living file, no timestamp prefix, dated entries appended at the end (create the file on first use): ```markdown ## {YYYY-MM-DD} - **Artifact:** {file the correction applies to} **AI proposed:** {what} **Human decided:** {what instead} **Why:** {the reasoning — the valuable part} ``` If there were no corrections, don't invent any — record the review anyway (a dated entry noting no corrections), so the next `/review-evidence` knows where the last one ended. 6. **Close with a one-screen summary:** belief status at a glance (confirmed / contradicted / weakened / promising / untouched), the drift report prioritized by what most blocks learning, and the suggested next step in one line — name the workflow to run on the top pending item: `/design-interview` or `/design-survey` to take a belief or a synthetic insight to real users, `/critique-spec` for a spec that skipped its panel, `/analyze-survey` for unanalyzed results, `/explore-solutions` for an opportunity that holds and has no alternatives compared, `/design-solution-tests` for alternatives chosen for testing with no tests file, `/build-solution-test` for a designed test still waiting for its material, `/analyze-solution-tests` for a test whose time box elapsed without analysis, `/design-metrics` for a revealed level with no metrics defined, `/analyze-metrics` for a level whose duration elapsed without reading its data, `/analyze-feedback` for a metric below target with no feedback read, `/stakeholder-review` to rehearse how a stakeholder will read an update or results report before sending it. (Name these explicitly — user-invoked workflows never auto-load, so their names are not otherwise in context.) ## Language Conversation, annotations, and `corrections.md` entries (field labels included) in the language of the conversation. The only exception is the three status keywords, which stay in English as fixed tokens.