reference-compare

Imported from some-marketing/mythos (.claude/skills/research/reference-compare/SKILL.md). Install upstream with npx skills add some-marketing/mythos --skill reference-compare. Copyright stays with the author.

name: research/reference-compare description: Compare a NEW artifact (research report, design brief, technical spec, audit) against a KNOWN-GOOD reference artifact from a prior successful project. Scores parity on N named dimensions, produces a verdict (SUFFICIENT / SUFFICIENT-WITH-NOTES / GAPS-TO-BACKFILL) with specific gaps, mitigation effort estimates, and a readiness assessment. Activates when the operator says "compare this research to ", "is this report deep enough", "benchmark this brief against the brief", or names a new artifact alongside a prior reference. Output is qualitative analysis MD; success is operator-judged not grep-able. status: provisional graduation_criteria: Promote to stable after 3+ successful invocations across at least 2 distinct artifact types (e.g., research report, technical spec, audit) with operator confirmation that the verdict + gaps drove a correct downstream decision in each case. Do not graduate on lower evidence per LEARNING_AND_AUTOMATION_DOCTRINE §Promotion Rule. Reason the threshold is this specific: the underlying pattern has exactly one successful execution at authoring time ({CLIENT_CODE}-vs-maher-research-comparison.md, 2026-04-22). Three invocations across two artifact types provides repeat-success across distinct shapes; single-shape repeats would not falsify the heuristic that the pattern only fits research reports.

This skill exists because "is the new work deep enough?" is asked over and over across projects, and the answer is almost always reached the same way: pull the closest prior win, list the dimensions that mattered there, walk both artifacts dimension-by-dimension, and surface specific gaps with mitigation effort. The pattern was proven this session at _dev/reports/analysis/{CLIENT_CODE}-vs-maher-research-comparison.md ({CLIENT_CODE} vs Maher Mechanical Perplexity research, 6 dimensions, SUFFICIENT-WITH-NOTES verdict, drove a correct "proceed to mockup with one <30 min reference pull" decision).

<prompt_type>Worker</prompt_type>

<execution_mode>REVIEW_ONLY — reads two artifacts, produces analysis MD. No mutation of input artifacts or downstream surfaces.</execution_mode>

<model_recommendation>sonnet — qualitative reasoning over two text artifacts; opus is overkill, haiku misses subtle parity calls</model_recommendation>

<quick_start>

/reference-compare \
  --new <path-to-artifact-under-evaluation> \
  --reference <path-to-known-good-reference-artifact> \
  --scope <client-code|system> \
  [--dimensions <comma-separated-list>] \
  [--name <comparison-name-for-output-file>]

Example:

/reference-compare \
  --new clients/{CLIENT_CODE}/projects/elsweb/research/perplexity-deep-research-raw-output.md \
  --reference clients/MAHR/projects/maher-website/research/web_dev_framework_reference.pdf \
  --scope {CLIENT_CODE} \
  --name research-set-comparison

</quick_start>

<execution_rules> [PROTOCOL] — REFUSE to run if --new or --reference paths do not exist or are not readable. Report the missing path and stop. [PROTOCOL] — REFUSE to run if --scope is missing. Output path depends on it; cannot guess. [PROTOCOL] — Read both artifacts fully before assessing any dimension. PDF support via Read tool's pages parameter (chunk by 20 pages if large). [PROTOCOL] — Every dimension finding must cite specific section/file from each artifact. If a citation cannot be produced for a side, mark that side "absent" rather than asserting parity. [PROTOCOL] — Never modify either input artifact. This is REVIEW_ONLY. [PROTOCOL] — Verdict must be exactly one of: SUFFICIENT / SUFFICIENT-WITH-NOTES / GAPS-TO-BACKFILL. No softer verdicts, no scores, no percentages. [PROTOCOL] — Each enumerated gap must include a mitigation suggestion AND a coarse effort estimate (e.g., "<30 min", "~2 hr", "half-day", "blocked on operator input"). [PROTOCOL] — When invoked from a subagent context, write to _dev/reports/analysis/ may be denied (documented gap I-2 in _dev/reports/analysis/run-debrief__elsweb-kickoff-2026-04-22.md). Fallback contract: return findings inline as the final assistant message; the parent context persists. Do not silently skip the artifact. [PROTOCOL] — Dimensions come from --dimensions flag if provided; otherwise from artifact-type heuristic (see context). Do not invent ad-hoc dimensions mid-comparison. </execution_rules>

Inputs and paths

• --new: absolute or repo-relative path to the artifact under evaluation. May be .md, .pdf, .txt, or any text-readable format.
• --reference: absolute or repo-relative path to the known-good reference artifact. Same format constraints.
• --scope: one of system (cross-cutting analysis) or a client code ({CLIENT_CODE}, MAHR, {CLIENT_CODE}, etc.).
• --dimensions (optional): comma-separated dimension names. If omitted, infer from artifact type.
• --name (optional): kebab-case slug for the output filename. Default: <new-basename>__vs__<reference-basename>.

Output paths

• System scope: _dev/reports/analysis/<name>__system.md
• Client scope: clients/<CODE>/projects/<project>/outputs/<name>.md — if <project> cannot be inferred from the --new path, fall back to clients/<CODE>/comparisons/<name>.md and warn.

Dimension heuristics (when --dimensions not provided)

If artifact type cannot be inferred, ask the operator OR refuse with a list of supported types.

Reference exemplar

_dev/reports/analysis/{CLIENT_CODE}-vs-maher-research-comparison.md — the proof-of-pattern artifact. Future invocations should match its shape: bold one-line verdict at top, 3-5 line summary, side-by-side table, per-dimension findings with file-path citations, specific-gaps section with mitigation+effort, readiness assessment, recommended next move.

<automated_workflow>

</automated_workflow>

# <Comparison Title>

**Captured:** <YYYY-MM-DD>
**New artifact:** <path>
**Reference artifact:** <path>
**Dimensions:** <comma-separated list, source: flag|heuristic>

## Verdict

**<SUFFICIENT | SUFFICIENT-WITH-NOTES | GAPS-TO-BACKFILL>** — <one-sentence justification>

## Summary

- 3-5 bullets capturing the headline parity story

## Side-by-side summary table

| Dimension | Reference coverage | New coverage | Parity verdict |
|---|---|---|---|
| ... | ... | ... | NEW stronger / parity / REFERENCE stronger / NEW lacks |

## Per-dimension findings

### N. <Dimension name>
- **Reference** (`<file>` §<section>): <substantive details with citations>
- **New** (`<file>` §<section>): <substantive details with citations>
- **Delta:** <one-sentence judgment>

(repeat for each dimension)

## Specific gaps (Reference had, New lacks)

1. **<Gap name>.** <What the reference had.> *Mitigation:* <action>. *Effort:* <estimate>. *Blocking:* yes|no.

(repeat for each gap)

## Readiness assessment

<Two paragraphs: can next phase proceed; what's blocking vs optional>

## Recommended next move

**<Proceed | Backfill <items> then proceed | Escalate>** — <specific next command or decision>

<success_criteria>

• Both input artifacts read fully and cited specifically
• Dimensions selected from --dimensions flag or heuristic, not invented mid-flight
• Each dimension has citations from both sides (or explicit "absent on side X")
• Verdict is one of the three allowed values
• Each enumerated gap has mitigation + effort estimate
• Readiness assessment distinguishes blocking from optional
• Recommended next move is a concrete action, not "consider X"
• Output written to correct path per scope, OR fallback inline return when write denied
• No mutation of either input artifact </success_criteria>