journeys-enrich

name

journeys-enrich

description

Improves existing docs/journeys/*.md spec files — fills in gaps flagged by journeys-extract, refines vague steps, and links plausible test_ids by searching the repo's test suite — without a full rediscovery pass and without clobbering fields owned by journeys-verify. Always proposes a before/after diff and waits for explicit approval before writing (plan-validate-execute), then applies via journeys-extract's upsert script so the verified→stale invariant stays enforced in one place. Use when a journey is marked draft or stale and needs deepening or test-linking — not for discovering new journeys (journeys-extract) or for mechanically checking existing links (journeys-verify).

Journeys: Enrich

Deepen and link existing journey specs incrementally. Unlike journeys-extract (full rediscovery, always overwrites the body from scratch) this skill proposes targeted improvements to specific journeys and requires approval before writing anything — it must never silently clobber a hand-edited journey.

When to Use

• A journey is status: draft (usually: no test_ids linked yet, or gaps noted)
• A journey is status: stale and you want to investigate + fix it, rather than just re-run journeys-extract
• NOT for finding journeys that don't exist yet (journeys-extract) or for mechanically re-checking links you already believe are correct (journeys-verify)

Input

/journeys:enrich [slug ...]

• No args: target every journey with status: draft or status: stale in docs/journeys/
• One or more slugs: target only those journeys

Instructions to Claude

Step 1: Select Targets

List docs/journeys/*.md (excluding README.md), filter by args or by status: draft|stale. If more than ~3 journeys are targeted, process them with one lean agent per journey in parallel (same context-saving trick as journeys-extract: each agent writes its full proposal to /tmp/journey-enrich-<slug>.md and returns only a small JSON summary). For 1-3 journeys, do it inline.

Step 2: Propose Per Journey

For each target, read the journey file and its source_refs files. Propose:

• Refined steps: resolve vagueness, fill gaps listed under "## Gaps / Notes" by reading the actual code/UI at source_refs
• Candidate test_ids: search the repo's test suite (Grep for the journey's title/step keywords across test directories) for tests that plausibly already cover this flow. Only propose a test_id you found verbatim in an actual test file — never invent one. If nothing plausible exists, say so explicitly rather than proposing a weak match.
• Updated trigger/emotion/diagram if the investigation revealed they were wrong

Each proposal (agent or inline) returns/produces:

{
  "slug": "<journey_id>",
  "before": {"steps": [...], "gaps": [...], "test_ids": [...]},
  "after": {"steps": [...], "gaps": [...], "test_ids": [...], "trigger": "...", "emotion": "...", "diagram": "..."},
  "candidate_test_ids_rejected": ["<match too weak to include, with reason>"]
}

Step 3: Gate — Show the Diff, Wait for Approval

Present each journey's before/after as a compact diff (not the full file) and ask the user to approve, per-journey or in batch. Do not write anything before approval — this is the one step in the whole journeys family that touches existing content non-mechanically, so it's the one that must be gated.

Step 4: Apply (only approved journeys)

Reuse journeys-extract's upsert script — do not duplicate its stale-flip logic here. Build a payload from the approved "after" state and pipe it in:

echo '{
  "journey_id": "<slug>",
  "title": "<unchanged from file>",
  "user_types": ["<unchanged from file>"],
  "trigger": "<approved>",
  "emotion": "<approved>",
  "steps": ["<approved>", "..."],
  "gaps": ["<remaining unresolved gaps, if any>"],
  "source_refs": ["<unchanged from file>"],
  "diagram": "<approved, or unchanged>",
  "test_ids": ["<approved candidates merged with existing test_ids>"]
}' | uv run .claude/skills/journeys-extract/scripts/upsert_journey.py upsert

Only include "test_ids" in the payload if you're actually changing it (adding newly-found candidates) — omitting the key preserves whatever journeys-verify already set. If the journey's body content changed while status was verified, the upsert script will correctly flip it to stale — that's expected; the new/changed test_ids haven't been mechanically confirmed yet.

Step 5: Report Back, Recommend Verify

Tell the user which journeys were enriched, which candidate test_ids were added vs. rejected (and why), and which gaps remain unresolved. Recommend running journeys-verify next to confirm the new test_ids actually resolve — enrich only proposes links, it doesn't validate them.

Anti-Patterns

• Don't write before approval — this skill's entire reason to exist separately from journeys-extract is the human gate; skipping it makes it indistinguishable from a silent overwrite.
• Don't invent test_ids — a fabricated string that happens to not exist yet will just get flagged stale by journeys-verify on the next run, wasting a round trip. Only propose strings you actually found in a test file.
• Don't touch status, last_verified, or unrelated verify_notes directly — let the upsert script's existing invariant (verified + content-changed → stale) handle status; hand-setting it here would fight journeys-verify's ownership.
• Don't re-run full discovery — if a journey needs rediscovery from scratch (e.g. the flow was rebuilt entirely), that's journeys-extract, not this skill.