core-ux-detective

name

core-ux-detective

description

Discover, define and canonicalize the core user tasks and user paths of the application. Use when (1) mapping what users can actually do in the app, (2) defining canonical user journeys/flows, (3) creating the AI-readable user model (core-user-model.json), (4) reviewing whether a new feature introduces a new core path, (5) other skills (help, marketing, onboarding) need authoritative task/path definitions to consume. Triggers: "core tasks", "user paths", "user journeys", "UX model", "what can users do", "core flows", "user model", "canonical tasks", file types: core-user-model.json.

Core UX Detective

Discover and canonicalize the TRUE core user tasks and user paths.

This skill is the single source of truth for what users can do in the application. Other skills (help, marketing, onboarding) MUST consume this output and MUST NOT redefine core tasks or paths independently.

Authority

• ONLY this skill identifies core user actions
• ONLY this skill defines user paths
• ONLY this skill names steps canonically
• ONLY this skill decides primary vs secondary flow

Workflow

1. Gather Inputs

Collect from any available source:

• Codebase: Routes, pages, components, hooks (especially src/pages/, src/components/)
• PRD: Docs/01-PRD.md
• Feature lists: Docs/context/packages-map.md, Docs/context/repo-structure.md
• Existing model: Docs/ai/core-user-model.json (if it exists)
• UI screenshots or verbal descriptions from user

2. Identify Core User Tasks

Extract user-facing actions. Rules:

• User-facing only — not technical internals (no "hydrate cache", "run migration")
• Clear, neutral language — no marketing ("revolutionary") or help tone ("click here")
• Finnish labels — this is a Finnish-first app; use Finnish for label
• Conservative — fewer well-defined tasks > many vague tasks

Each task needs:

{
  "id": "snake_case_stable_id",
  "label": "Finnish label",
  "intent": "Why the user does this (English)",
  "appears_in": ["page_or_context_ids"],
  "draft": false
}

Mark "draft": true if uncertain about the task's scope or permanence.

3. Define User Paths

Group tasks into meaningful journeys. Each path:

• Has a clear user intent
• Has ordered steps (referencing task IDs)
• Has a beginning and an end
• Is explicitly defined (overlapping steps between paths is fine)

{
  "id": "path_snake_case",
  "label": "Finnish path label",
  "intent": "What the user accomplishes (English)",
  "primary": true,
  "steps": ["task_id_1", "task_id_2", "task_id_3"]
}

• primary: true = core journey most users follow
• primary: false = secondary/power-user flow

4. Output Schema

Save to Docs/ai/core-user-model.json:

{
  "$schema": "core-user-model-v1",
  "updated": "YYYY-MM-DD",
  "core_tasks": [ ... ],
  "user_paths": [ ... ]
}

5. Validate

After writing the model:

• Every step in user_paths[].steps must reference a valid core_tasks[].id
• No orphan tasks (every task appears in at least one path, or is marked draft)
• No duplicate IDs
• Labels are Finnish, intents are English

Rules

• Conservative: fewer paths > many vague paths
• Clarity over completeness: a well-defined subset beats a fuzzy comprehensive list
• Stable IDs: once an ID is published, do not rename it (add new, deprecate old)
• No marketing or instructional text in the model
• Draft flag: if unsure, set "draft": true — other skills skip draft items

Discovery Strategy

When analyzing the codebase to find core tasks:

1. Routes — each route = potential user task or context
2. Page components — what actions does each page enable?
3. Hooks with user state — useAuth, useReelDraft, useBookmarks etc. reveal capabilities
4. UI action buttons — buttons/links with Finnish labels reveal user-facing actions
5. Database tables with user_id — each user-owned table hints at a core task

For detailed discovery patterns, see references/discovery-patterns.md.

Consuming the Model

Other skills read Docs/ai/core-user-model.json and:

• Use core_tasks[].id as canonical references
• Use core_tasks[].label for Finnish UI text
• Use user_paths for onboarding flows, help guides, marketing funnels
• Never redefine or rename tasks — request changes via this skill