Brief: User-Journey Test Pathways + Hook-Method Validation

A repository document, rendered for the site. View source markdown.

New to cub? Install the cub CLI first. You can pull and render public catalog packages without an account. Commands that save or change ConfigHub data require you to sign in.

Generated at: 2026-07-30T12:38:02.000Z UTC · source: committed helm-expt evidence for this rendered repository document.

Audience: the next helm-expt working session (fresh Opus 4.8 chat). Status: UNOFFICIAL/EXPERIMENTAL planning brief. Do the research pass first; do not build from assumption.

Update (2026-06-20) - research pass done; Pathway 1 shipped. The verified research map, the pathway matrix, and the build plan are in the companion user-journey-test-pathways-plan.md. Read it alongside this brief - it corrects four specifics below that the research pass falsified: (1) several charts named here are source-scan only, not in the catalog (kafka, minio, thanos, airflow, kong, datadog, kubernetes-dashboard, keycloak, gitlab) - do not anchor pathways on them; (2) only cub-scout compare three-way --dry-from is shipped - compare object-set --dry-from / ObjectSetDiffReceipt (the "#498" in §2d) are design/branch-only, not on main; (3) the "62" (§4, §7) is the lifecycle-lane cell count, not a single named field; (4) the persona PRD has 6 personas (this brief's 5 is a subset). Pathway 1 - "Route a chart's hooks, transparently" - is built: pathway-route-hooks-transparently.md.

1. Mission

Two intertwined goals:

  1. Construct standard "test pathways" - real user journeys. A pathway = (user type / persona) × (the key decisions they make) × (a class of charts, especially quirky ones). Each pathway is a named, runnable walkthrough that answers the question a real user asks: "How do I figure out the way to run THIS chart with cub, and what are my options?"
  1. Validate the hook-handling method (convince the team and ourselves): prove that "render parity proves the non-hook object set + hooks are explicit, non-automatic lifecycle routes (visible, runnable, receipted)" works well - via a few worked, live, side-by-side exemplars on quirky hook charts.

These are the same work: a hook chart's pathway is "how do I run its hook, transparently." The exemplars double as the most important pathways.

Deeper why. This ultimately tests whether helm-expt proves the Generative GitOps thesis (white-paper draft ~/Downloads/DRAFT w-paper Generative GitOps.pdf; durable in-repo versions: docs/user/generative-gitops-fit.md, why-this-exists.md, why-this-does-not-collapse.md). The hook method is the thesis's hardest case - the last hidden imperative step in a Helm install - so convincingly routing hooks (visible, runnable, receipted) is strong evidence for the whole argument. Frame the convince-the-team work against that thesis.

2. Required research (DO THIS FIRST - full pass)

Read before building. Verify claims against the generated surfaces / receipts, not prose (prose can be stale vs the data).

2a. The model - how proof + disposition work

2b. Quirks - the chart classes to bucket pathways over

2c. Hooks / lifecycle - the method under test

2d. Personas + existing journey material (BUILD ON THIS - do not restart)

2e. Planning context

3. The user-journey framework to build

Spine (from generative-gitops-fit.md): helm serverless → add server → add app (write-green | load-brown) → make changes + variants → day-1 (preview / dry-run / lifecycle / other) → day-2. Cross-cutting: SecOps · platforms · fleets · stacks.

A test pathway = persona × decision-sequence × chart-class:

Each pathway maps to the matrix lanes + the chart-page cards + the exact day-1 cub / cub-scout commands, stating the honest disposition at each step (including where the proof stops). "Our dry-run has to be better than ArgoCD's" and the journey must work for all charts, not be tied to one.

4. The hook-method validation challenge (convince-the-team artifact)

Build 3–4 worked, live, side-by-side exemplars on quirky hook charts. For each:

  1. render parity proves the non-hook objects;
  2. the post-deploy hook run as its explicit route on a live kind cluster + verified by a receipt;
  3. shown next to "what Helm/Argo would have done silently."

Span hook classes: post-apply Job · test hook · cleanup/delete-policy · CRD-bootstrap · webhook-cert.

5. Deliverables

  1. A persona × decision × chart-class pathway matrix (which pathways, which charts, why).
  2. ~4–6 fully-written test pathways (the most important journeys), each runnable end-to-end.
  3. 3–4 worked live hook exemplars (side-by-side visible-vs-silent, receipted), spanning hook classes.
  4. The convince-the-team writeup: the argument + the exemplars + the falsification framing.

6. Operating constraints (honor these - learned the hard way)

7. Current state (start here)

All merged to main this session:

The matrix is complete as far as testing takes it. What remains is catalog/lifecycle/ external work - including the 62 lifecycle-observed cells, which is the hook-method work in §4. That, plus the user-journey pathways, is this brief.