agentleFS
carlszcarlsz/ux-agent-skills/skills/spec-cuj/SKILL.md

spec-cuj

Skill18 starsChanged 4 months agoMITView on GitHub

Interview the user one question at a time to author critical user journeys, then store each as its own .ux/cujs file with actor, preconditions, numbered steps and expected outcomes, and regenerate the journey index in the host SPEC.md. Use for "define a CUJ", "author journeys", "write our user journeys", "ux spec".

The file

We split this skill into the rules it gives an agent

12 rules. About 0 are common, 5 are distinctive, and 7 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 7

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    No target argument: journeys describe the whole app, not a URL.

    line 27
  2. Very specific:

    Run python3 scripts/validate_cuj.py --dir .ux/cujs first if the directory exists.

    line 32
  3. Very specific:

    Check whether agent-skills:interview-me is available.

    line 42
  4. Distinctive:

    Never degrade silently. A missing dependency that nobody mentions is indistinguishable from a worse tool.

    line 51
  5. Distinctive:

    Wait for each answer and follow up before moving on.

    line 55
  6. Very specific:

    Never invent: If they can't answer something, record the gap and stop.

    line 79
  7. Distinctive:

    Could I establish every precondition from a fresh install?: If not, this journey will report "skipped, precondition unmet" forever — and …

    line 112
  8. Very specific:

    Could any of these expect lines actually fail?: If a broken app would still pass this journey, it is decoration.

    line 120
  9. Very specific:

    Every step has an expect naming something a person or a browser can observe — no "it works", no "the state updates".

    line 172
  10. Very specific:

    Every precondition is establishable from a fresh install, re-establishable on a second run, and none contradicts a step's exact value.

    line 176
  11. Distinctive:

    No step, field, or justification was invented — including no manufactured rationale for the user's own answer.

    line 182
  12. Very specific:

    If interview-me was unavailable, the fallback was used and disclosed.

    line 188

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Spec CUJ — author a critical user journey

Interview the person who knows the product, and turn what they say into a critical user journey: a durable, executable description of something the app exists to do. Each journey becomes one file in .ux/cujs/ conforming to the CUJ file contract, and the host's SPEC.md gets a generated index pointing at them.

Adopt the cuj-author persona. Its refusals are the whole point of this skill: validate_cuj.py can reject an empty expected outcome, but only a person reading English can reject an unobservable one. "It works" parses fine and verifies never.

This skill writes to the host repo. Journeys go in .ux/cujs/ freely; the host's SPEC.md is ask-first, always with a diff.


Inputs

  • --cuj <id> — revise an existing journey instead of authoring a new one. Optional.
  • No target argument: journeys describe the whole app, not a URL.

Workflow

  1. Locate the host repo root and read what's already there. Run python3 scripts/validate_cuj.py --dir .ux/cujs first if the directory exists. Never author on top of a broken directory — fix or report the existing violations before adding to them. Read the existing journeys — you need them to avoid writing a near-duplicate, and to sanity-check this one's criticality against real peers rather than against a headcount.

    Compute the next free id (CUJ-001 if none exist). If .ux/cujs/ is absent, create it — no need to ask.

  2. Pick the interview. Check whether agent-skills:interview-me is available.

    • Available → drive it, one question at a time, until you're confident you have the journey.
    • Not installed → fall back to references/interview-fallback.md, and disclose it: tell the user interview-me isn't installed and you're using the built-in question set. Offer to install it; never auto-install. They should know which interview they got.

    Never degrade silently. A missing dependency that nobody mentions is indistinguishable from a worse tool.

  3. Interview — one question at a time. Wait for each answer and follow up before moving on. A wall of questions gets a wall of shallow answers and throws away the follow-up, which is where the real answer lives.

    Apply the persona's refusals as you go — especially the observable-outcome bar on every step's expect. Walk the journey with them in order, asking "…and then what do you see happen?" after each action.

    Cover every field the contract requires, whichever interview is running. interview-me doesn't know this schema; it will happily finish without ever asking entry_point or criticality. Anything it skips is yours to ask — an unasked field silently becomes an invented one.

    Guess the description; the three graded fields are elicited, never guessed. interview-me's method is a guess attached to every question, and that is welcome here — for most of the schema. Let it lead with a hypothesis on the descriptive fields (actor, goal, title, entry_point, preconditions, each step's action, the narrative); the user reacts to a wrong guess faster than they build an answer from nothing. But for the three fields audit-cuj grades against — each step's expect, the success_criteria, and criticality — take the interview open and refuse a bare "yes": a guessed expect confirmed with "…right?" becomes a step that may not exist in a critical journey, and a guessed criticality becomes a priority clamp nobody earned. See the persona's "guess the description, elicit the oracle" and "source checks the answer, it never supplies the answer".

    Never invent. If they can't answer something, record the gap and stop. An incomplete journey marked incomplete beats a fabricated one that looks finished — a guessed step becomes the standard audit-cuj grades against forever, and it will pass, because you wrote it to match what you imagined. This includes never inventing agreement: if they push back and they're right, say so plainly rather than manufacturing a rationale for why they're right.

  4. Draft, and read it back. Show the journey — actor, goal, criticality, every step and its expected outcome, the success criteria — and get confirmation before writing anything. When they correct you, the correction is the answer: record that, not your paraphrase.
  5. Write .ux/cujs/<id>-<slug>.md. The filename carries the slug; there is no slug key. Ten keys, no provenance block, no author — see the contract. Body is ## Narrative and ## Out of scope.
  6. Self-check.

    python3 scripts/validate_cuj.py .ux/cujs/<id>-<slug>.md
    python3 scripts/validate_cuj.py --dir .ux/cujs

    The --dir pass is not redundant: it catches duplicate ids and filename/frontmatter mismatches, which a single file structurally cannot reveal. Fix anything it reports before continuing.

    Show the validator's real output — do not summarise it. "Both files validate" is a claim; the two lines the script printed are evidence. A skill whose whole argument is that an unfalsifiable assertion is worthless does not get to launder its own tool output into prose.

    Then read the journey back as if you were audit-cuj, and ask the three questions the validator cannot:

    • Could I establish every precondition from a fresh install? If not, this journey will report "skipped, precondition unmet" forever — and never running looks nothing like failing.
    • Could I run it twice in a row? A precondition that expires — "nothing harvested today", "first visit" — is true once and false after, so run two fails a healthy app. Say how each one is re-established, or pick a state that doesn't decay.
    • Do the preconditions and the steps agree? A range ("5-8 tasks") under a step that asserts an exact value ("the count reads '5 tasks growing'") fails a working app.
    • Could any of these expect lines actually fail? If a broken app would still pass this journey, it is decoration.
  7. Regenerate the host's SPEC.md index — and ASK first.

    python3 scripts/validate_cuj.py --index .ux/cujs

    Generate the block. Never write that table by hand or from memory — the block is a pure function of .ux/cujs/, and only a script keeps regeneration byte-identical. An agent re-rendering it from memory breaks that quietly.

    Then:

    • Replace only the bytes between the ux-agent-skills:cuj-index markers. Everything above and below is theirs and stays untouched.
    • Show the diff and ask before writing. This is the one file you touch that the user owns.
    • Markers absent, or no SPEC.md at all → ask before inserting the section or creating the file. Append at the end; never reorder their existing sections.
    • If they decline, stop. The journey files stand alone — the index is a convenience, not the source of truth. Say that, so declining doesn't feel like losing the work.
  8. Confirm the footprint.
    python3 scripts/audit_safety.py <host-repo> --profile authoring
    The authoring profile permits .ux/cujs/ and SPEC.md. If it reports anything else, you touched something you shouldn't have — revert it. Note this is the only skill in the suite that runs a profile other than audit.

Boundaries

  • Never edit, refactor, or "fix" host application code. You capture what the user tells you about their app; you don't change it. Journeys and the SPEC.md index block are the only things you write.
  • .ux/cujs/ needs no permission. Creating it and writing journeys there is expected.
  • The host's SPEC.md is ask-first, with a diff, and only ever the marker block.
  • Never fabricate a step, actor, precondition, criticality — or a justification for the user's own answer. Inventing support is still inventing.
  • Never record an author, date, revision, or capture method. Git answers all of it. validate_cuj.py rejects author / authored / by / email outright.
  • Never install anything — offer, and let the user decide.
  • Never route around a permission gate, and never copy this plugin's tooling into the host repo. Blocked from reading a reference or running validate_cuj.py? Ask for access. Do not cp the script into .ux/, do not inline it, do not reimplement it. The suite's promise is that it leaves nothing behind but the journeys — dodging a prompt by littering the user's tree trades that promise for a few seconds, and a gate is the user deciding. Blocked and honest beats unblocked and littering.

Exit criteria (done when)

  • One or more .ux/cujs/<id>-<slug>.md exist and pass both validate_cuj.py <file> and validate_cuj.py --dir .ux/cujs.
  • Every step has an expect naming something a person or a browser can observe — no "it works", no "the state updates".
  • success_criteria says something true after the journey, not a restatement of the last step.
  • Every precondition is establishable from a fresh install, re-establishable on a second run, and none contradicts a step's exact value. Narrative colour stayed in ## Narrative.
  • The validator's actual output was shown, not summarised.
  • Nothing was copied into the host repo to dodge a permission prompt.
  • criticality was asked, not inferred, and its ## Narrative says what breaks.
  • No step, field, or justification was invented — including no manufactured rationale for the user's own answer.
  • The user confirmed the draft before it was written.
  • The host's SPEC.md index is regenerated or the user declined and was told the journeys stand alone. If written: generated by --index, spliced only between the markers, diff shown first.
  • If interview-me was unavailable, the fallback was used and disclosed.
  • audit_safety.py --profile authoring exits 0 on both halves — every change confined to .ux/cujs/ and SPEC.md, and the journeys this run wrote observed inside them.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.