---
name: knowledge-refresh
description: 'Use when a knowledge artifact needs review before sharing or execution. Runs strategic and data reviewers in parallel, merges P1/P2/P3/Clean findings, and blocks ordinary shipping on P1. Don''t use for tasks that require source or remote-system changes.'
---

# Knowledge review

## Contract

| Field | Bound contract |
|---|---|
| Trigger | User asks to review or validate a knowledge artifact before sharing or executing it. |
| Authority | Read-only review: no file, VCS, credential, paid, published, deployed, or remote mutation during the review. Any fix is a separate, explicitly user-authorized edit performed after the review completes. |
| Side effect | Reads the target and references and emits merged findings. No write occurs during the review. A fix, if the user explicitly authorizes one after the review, is a separate edit outside the review's authority. |
| Done | Strategic and data reviewers run in parallel; findings merge into P1/P2/P3 plus Clean; external content gets an editorial check; every P1 blocks ordinary shipping and receives explicit next choices. |

## Inputs

Required:
- **Artifact**: a file path or paste of content to review.

Optional:
- Referenced data context files.
- Explicit indication that content is external-facing (published, emailed, or posted publicly).

If the input is ambiguous, ask the user to supply a file path or paste the content.

## Procedure

1. **Load the artifact.**
   - If a file path is given, read the file.
   - If pasted content is given, use it directly.
   - If content references data (metrics, conversion rates, financial figures), also load any data context files cited in the artifact.
   Done when: the artifact content is loaded and any cited data context files are read.

2. **Run both reviewers in parallel.**
   a. Launch a strategic alignment review using the full artifact content. Evaluate:
      - goal clarity: the goal connects to a measurable outcome;
      - hypothesis falsifiability: the hypothesis uses a testable "if-then" form;
      - success metrics: metrics are defined and connected to the goal; flag vanity metrics;
      - scope proportionality: effort is proportional to expected impact;
      - resource awareness: time, people, tools, and budget are stated;
      - strategic consistency: the artifact is consistent with stated project goals;
      - opportunity cost: what is not being done and whether this is the best use of effort here.
   b. Launch a data accuracy review using the full artifact content and data context files. Evaluate:
      - source citation: every number has a cited source with a file path, dashboard name, or calculation;
      - comparison baselines: every comparison has a stated baseline; flag incomplete comparisons;
      - canonical definitions: metrics match the project's canonical definitions;
      - freshness: flag data older than 48 hours with a warning and data older than 7 days as P2;
      - caveats: known limitations of data sources are stated;
      - hardcoded vs live: identify hardcoded numbers that should be live-queried;
      - baseline appropriateness: watch for seasonal skew or cherry-picked timeframes.
   c. Wait for both reviewers to return before proceeding.
   Done when: both reviewers have returned their findings.

3. **Editorial check for external-facing content.**
   - If the artifact will be published, emailed, or posted publicly: check for AI writing patterns (generic phrasing, stock transitions, vague claims) and tone or voice consistency with the project's style guides.
   - If the artifact is internal (plan, brief, analysis for the team): skip this step.
   Done when: the editorial check is run for external-facing content or skipped for internal content.

4. **Merge findings.**
   Combine findings from both reviewers. Group all findings by severity:

   | Severity | What qualifies |
   |---|---|
   | P1 Critical | Factual error, wrong data source, missing goal, unfalsifiable hypothesis |
   | P2 Important | Missing source citation, stale data older than 7 days, unclear success metric |
   | P3 Nice-to-have | Minor framing, additional context, formatting |
   | Clean | Sections that passed all checks |

   Done when: all findings are grouped into P1, P2, P3, or Clean.

5. **Present findings.** Present a grouped review report with P1 (blocks shipping, most critical first), P2 (should fix), P3 (nice to have), and Clean (what passed) sections. Each finding is specific: "Revenue cited as $X but [source] shows $Y as of [date]" rather than "Revenue might be wrong." Done when: the grouped report is presented with specific findings in severity order.

6. **Offer next steps.** Ask: "Review complete. [N] findings ([P1 count] critical, [P2 count] important). What next?" Options: (1) Fix P1/P2 issues now: address findings inline, then re-review; (2) Ship as-is: acknowledge findings and proceed without fixing. Done when: the user is offered the two next-step options.

7. **Execute the chosen action only after the review completes.**
   - If the user chooses to fix: the review is complete. The fix is a separate, explicitly user-authorized edit. Make targeted edits, then re-run the review as a new invocation.
   - If the user chooses to ship as-is: acknowledge the outstanding findings and stop.
   Done when: the chosen action is executed (fixes applied and re-reviewed as a separate step, or findings acknowledged and stopped).

## Failure and recovery
| Failure class | Recovery |
|---|---|
| Ambiguous artifact | Ask the user to provide a file path or paste the content. Do not guess. |
| One reviewer returns empty | A missing reviewer makes that review's checks unverifiable. Flag them as unverifiable at P2 minimum (matching the data-source-inaccessible rule) and block Done until both reviewers return. |
| Data source inaccessible | Flag the data claim as unverifiable (P2 at minimum) rather than assuming it is correct. |
| User declines to choose a next step | Stop. The review is complete; do not proceed unilaterally. |
| External content check finds AI patterns | Present the finding as a P2; do not rewrite the content. |

## Output

A grouped review report with P1, P2, P3, and Clean sections (each finding specific with source and date), where P1 findings explicitly block ordinary shipping and receive the next-steps prompt.