Skip to content

rosetta-research plugin

Seven-stage Product Family Research Pipeline. Takes a Salesforce Data Foundations product family from corpus consultation through to deployable Cypher seed data for db/seeds/.

  • Latest shipped bundle: the current rosetta-research-<version>.zip in this directory, regenerated by make plugin-bundle-rosetta-research (rosetta-research-0.14.0.zip as of v0.14.0)
  • Slash commands: /rosetta-research:intake, /rosetta-research:extract, /rosetta-research:author-nodes, /rosetta-research:author-patterns, /rosetta-research:provenance, /rosetta-research:author-adrs (v0.13.0), /rosetta-research:validate, plus /rosetta-research:run-all (v0.7.0 orchestrator — runs all seven stages in one chat). All eight commands accept a v0.8.0 opt-in --bootstrap flag and a v0.10.0 opt-in --target-patterns=N flag (PRODUCT_FAMILY [--bootstrap] [--target-patterns=N]). --bootstrap is for foundational runs that initialize the graph from a clean slate. --target-patterns=N (bootstrap-only, cap N=30) asks Stage 4 to author N patterns; if corpus capacity is short, Stage 4 pauses and surfaces three options.
  • Skill: product-family-research
  • License: Proprietary — © 2026 Keenan Vision LLC (see the repo LICENSE)

For the full method spec, read skills/product-family-research/SKILL.md. The extracted form under util/plugins/rosetta-research/ is the source of truth per Approach C; the shipped zip above is regenerated from it via make plugin-bundle-rosetta-research.

ADR authoring — new Stage 6 (v0.13.0)

v0.13.0 grows the pipeline from six stages to seven by inserting a new authoring stage, author-adrs, between Provenance (now Stage 5) and Validate (now Stage 7). The new Stage 6 emits corpus-baseline ADR Cypher as a first-class canonical node type — joining the six node types Stages 3-4 already author — with (adr)-[:GOVERNS]->(cp) edges to the patterns each decision constrains, (sa)-[:CITED_BY]->(adr) edges reusing the governed patterns' SF-tethered sources, and a ProvenanceEvent per ADR (performedBy="rosetta-research:author-adrs" — honest plugin-run attribution). It runs after Provenance so the GOVERNS targets (ContextPattern, 08L) and CITED_BY sources (SourceArtifact, 09L) already exist; the ADR file (<NN>L-<product>-adrs.cypher, generally source-artifacts-prefix + 1, e.g. 10g) loads after them. Each family carries 3-7 corpus-baseline ADRs, one per major irreversible architectural decision shared across patterns (not one-per-pattern). This is the sustainable, plugin-authored path the transitional hand-authored db/seeds/10g-data-360-adrs.cypher converges toward; v0.13.0 builds the path but does not retire 10g. Ratifying DT: docs/decision-traces/d360-adr-authoring-plugin-path.md (Option 1, conditional on the structural-constraint precondition); operationalized by E3-S2-WP11.

The ADR emit is born behind the three structural-constraint layers that closed the v0.12.0 enum drift, not free-form runtime authoring: (1) templated emit — commands/author-adrs.md ships concrete MERGE-on-qualifiedKey templates with "STOP and surface; do NOT substitute a close-enough value" language on every enum-valued field (status, GOVERNS scope); (2) static self-gate — Stage 7 (validate) hard-fails on ADR shape, GOVERNS contract, and provenance-coverage violations and refuses to ship a non-conformant bundle; (3) live-graph gate — scripts/neo4j/d360-invariants.sh gains INV-D16 (ADR shape), INV-D17 (GOVERNS contract), and INV-D18 (ADR provenance coverage), enforced at load time alongside INV-D1…D15. No db/schema/ change — the existing ADR label and GOVERNS contract are used as-is.

Bootstrap mode (v0.8.0)

All eight slash commands accept an opt-in --bootstrap flag that signals a foundational run: the graph is initialized from a clean slate rather than extended on top of existing coverage. The flag is parsed from $ARGUMENTS by literal-token match — pass it exactly once at any stage (or once at the orchestrator) and the mode propagates through the cumulative bundle's MANIFEST.md.

What changes in bootstrap mode:

  • Stage 1 (intake). Step 5 (existing-coverage inventory) is skipped; research-notes.md records "Bootstrap mode — no prior graph content assumed." Corpus consultation, glossary capture, and alias-table normalization run normally.
  • Stage 3 (author-nodes) and Stage 5 (provenance). UID ranges allocate from the canonical first slot per node label (vt-<letter>-001, sa-<letter>-001, etc.), contiguous, with no header comment claiming continuation of any prior range.
  • Stage 4 (author-patterns). Cross-pattern wiring (INTEGRATES_WITH / BUILDS_ON) targets only patterns authored within the same bundle — no MATCH against an assumed pre-existing graph node. Bundles with fewer than 3 patterns cannot satisfy the ≥2 within-bundle wiring requirement; the plugin halts with a pause-and-ask.
  • Stage 7 (validate). Three additional invariants fire: (a) every MATCH resolves to a node authored within the bundle (no external MATCH); (b) UID ranges per node label are contiguous 001..N; (c) header text and inline comments do not claim continuation of any prior range (soft warning).
  • Bundle. Filename embeds bootstrap infix (rosetta-research-<product>-bootstrap-stage7-<ts>.zip); MANIFEST.md records mode: bootstrap.

What does not change: the v0.4.0+ corpus tethering, scope discipline, glossary normalization, alias-table normalization, five-field identity, ProvenanceEvent emission, and producer-only contract all apply identically. Bootstrap mode affects how the run interprets prior graph state; it does not relax any constitutional or content-quality guard.

Omit the flag for normal extension runs (the v0.7.0 default).

Evidence-corpus discipline (v0.4.0+, refined v0.5.0, v0.6.0, v0.9.0)

The evidence-corpus contract described here was finalized at v0.9.0 and carries forward unchanged. The plugin is hard-tethered to the operator-curated corpus at docs/evidence/document-inventory.csv:

  • Product Line filter (added v0.5.0). Stage 1 filters the CSV to rows whose Product Line matches the $ARGUMENTS product family before applying the scope and relevance filters.
  • Scope-aware admissibility. The CSV's Scope column maps to the rosetta-platform domain hierarchy: SF rows ground canonical content, KV rows are admissible only as supporting citations alongside ≥1 SF source, NTO rows are out of scope for this plugin entirely (they belong to rosetta-archaeology).
  • Corpus-first source inventory. Stage 1 consults the CSV before any web research; web sources are admitted only to fill documented Corpus Coverage Gaps.
  • evidenceSources on every canonical content node (v0.9.0). v0.6.0 required evidenceSources on every authored ContextPattern; v0.9.0 extends the contract to every inheritable-label canonical content node — VocabularyTerm, SemanticEntity, PlatformObject, EngineFunction, BusinessIntent. Stage 4 (patterns) and Stage 3 (other nodes) require ≥1 SF-scoped corpus reference, or an explicit corpusGap=true operator-acknowledged liability marker. Stage 5 emits (SourceArtifact)-[:CITED_BY]->(node) edges to every cited canonical node, not just patterns. Stage 7 (validate) mirrors the per-pattern gate onto all five sibling labels.
  • corpusInventoryRef / corpusScope / corpusGap on every SourceArtifact. Stage 5 marks every source's origin and scope tier in the graph, with the same pair echoed in the ProvenanceEvent payload for C-6 audit.
  • Per-row INGESTED tracking retired in v0.5.0. v0.4.0 emitted an evidence-ingestion-delta.csv for the operator to apply on PR merge; the source CSV no longer carries an INGESTED column, so the delta artifact is dropped. Sessions are now independent.
  • Glossary + product-name-alternatives normalization (added v0.6.0). Two operator-curated reference tables at docs/evidence/glossary.csv (verbatim definitions for terms cited as VocabularyTerm, with a default Type filter that excludes general business jargon) and docs/evidence/product-name-alternatives.csv (canonical-product alias graph for Stage 2 product-reference normalization and Stage 3 PlatformObject.alternateNames authoring). VocabularyTerm.aliases and PlatformObject.alternateNames are new node properties added in v0.6.0.

Full protocol: skills/product-family-research/references/evidence-corpus.md.

Bundle regeneration after future edits is one Make target away: make plugin-bundle-rosetta-research. See the util/plugins/README.md "Bundles are derived" note.

Installation

When you run claude from a rosetta-platform checkout, this plugin is auto-discovered via .claude/settings.json. The /rosetta-research:* slash commands become available automatically; first-run users get a "trust this folder?" prompt, subsequent runs are silent. No install step beyond the trust prompt.

This is the right path for plugin authoring and repo-internal use. Cowork upload (next section) is the right path for production research sessions where the user is iterating on uploads.

Claude (web / Cowork)

  1. Open a Cowork chat.
  2. Customize → Plugins → + → upload the current rosetta-research-<version>.zip regenerated by make plugin-bundle-rosetta-research.
  3. Confirm /rosetta-research:intake appears in the slash-command palette and that its argument-hint shows PRODUCT_FAMILY [--bootstrap] (v0.8.0 sanity check).

Claude Code (CLI)

The bundle follows the standard plugin layout (.claude-plugin/plugin.json, commands/, skills/), so it can also be loaded as a local Claude Code plugin:

mkdir -p ~/.claude/plugins
unzip -o util/plugins/rosetta-research/rosetta-research-<version>.zip \
  -d ~/.claude/plugins/

Restart your Claude Code session and the /rosetta-research:* commands become available. Refer to the Claude Code plugin documentation for marketplace-style registration if you prefer a managed install path.

No connector wiring is needed. The plugin runs entirely off uploaded files; it never reaches into your local checkout, your Neo4j, or your MySQL.

Inputs every session expects

Drop these in the chat's uploads area before invoking the slash command:

Stage Required uploads
1 — /rosetta-research:intake rosetta-platform-VERSION.zip
2 — /rosetta-research:extract repo zip + rosetta-research-<product>-stage1-*.zip
3 — /rosetta-research:author-nodes repo zip + Stage 2 bundle
4 — /rosetta-research:author-patterns repo zip + Stage 3 bundle
5 — /rosetta-research:provenance repo zip + Stage 4 bundle
6 — /rosetta-research:author-adrs repo zip + Stage 5 bundle
7 — /rosetta-research:validate repo zip + Stage 6 bundle
All — /rosetta-research:run-all repo zip only (v0.7.0 orchestrator runs Stages 1-7 in one chat; per-stage bundles produced as checkpoints; v0.8.0 --bootstrap flag propagates from the orchestrator invocation through every stage's bundle)

Produce the repo zip from a clean checkout:

cd ~/path/to/rosetta-platform
git archive --format=zip HEAD > /tmp/rp.zip

Each stage emits ONE cumulative zip — Stage 7's bundle contains everything Stages 1–6 produced plus the validation outputs. Re-upload that bundle as the prior-stage input to the next stage.

Applying the output to your checkout

Stage 7 (validate) emits a VALIDATION-CHECKLIST.md (located inside the bundle at outputs/plugins/rosetta-research/<run-id>/VALIDATION-CHECKLIST.md per the v0.9.0 ADR-PA-008 layout). Follow it from your local clone:

cd ~/path/to/rosetta-platform
unzip -o ~/Downloads/rosetta-research-<product>-stage7-*.zip
# Canonical Cypher lands at db/seeds/ (committed); non-canonical
# artifacts (MANIFEST.md, STATIC-ANALYSIS-REPORT.md,
# VALIDATION-CHECKLIST.md, research-notes.md, extraction.md,
# sources.md) land at outputs/plugins/rosetta-research/<run-id>/
# (gitignored).
cat outputs/plugins/rosetta-research/<run-id>/VALIDATION-CHECKLIST.md
make intake-validate              # pre-flight: round-trip + invariants
make seed-compile && make seed-deploy
make db-invariants
make d360-invariants              # v0.13.0: INV-D16/D17/D18 gate ADR shape/GOVERNS/provenance

Then open a PR labelled rosetta-core/proposal per the content author checklist.

If make intake-validate fails:

  • exit 1 (round-trip drift) — the script names the offending file and the remediation make target;
  • exit 2 (metamodel invariant) — fix the missing five-field identity on the offending node;
  • exit 3 (pre-condition) — Neo4j unreachable, or util/seed/{content,generated}/ is dirty before unzip.

ADR-PA-008 compliance (v0.9.0)

ADR-PA-008 establishes that plugin runtime outputs (manifests, validation checklists, eval invocation scripts, run logs) land at outputs/plugins/rosetta-research/<run-id>/ in the repo root, gitignored, never auto-promoted.

v0.9.0 ships compliance. The bundle's internal layout now places every non-canonical artifact (MANIFEST.md, STATIC-ANALYSIS-REPORT.md, VALIDATION-CHECKLIST.md, research-notes.md, extraction.md, sources.md) under outputs/plugins/rosetta-research/<run-id>/ paths inside the bundle, where <run-id> is <product>-stage<N>-<timestamp> (extension) or <product>-bootstrap-stage<N>-<timestamp> (bootstrap). Canonical Cypher continues to land at db/seeds/ per ADR-PA-002 — that convention is unchanged.

Tracker entry in util/plugins/README.md § "Migration to ADR-PA-008" drops rosetta-research from TODO to Complete at v0.9.0.

Constitutional alignment

The plugin operates within the rosetta-platform invariants (CLAUDE.md): C-2 (Cypher canonical), C-4 (Make is the user surface), C-5 + metamodel v1.11.0 §5 + §6 (five-field identity plus projectId), C-6 (ProvenanceEvent on every mutation), C-7 (producer-only — never references rosetta-app-server).

It produces; you operate. The plugin never invokes make, cypher-shell, mysql, docker, or any command on your machine.

Reporting issues

File against this repo with tag [plugin]. Include:

  • the bundle filename (carries the version),
  • which stage you were running,
  • the upload manifest the plugin echoed in its first response,
  • any failing assertion text from make intake-validate or VALIDATION-CHECKLIST.md.