Core UX Detective Skill

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:

Routes — each route = potential user task or context
Page components — what actions does each page enable?
Hooks with user state — useAuth, useReelDraft, useBookmarks etc. reveal capabilities
UI action buttons — buttons/links with Finnish labels reveal user-facing actions
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

Agent Skills: Core UX Detective

Install this agent skill to your local

Skill Files