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