0xhoneyjar/importing-research

Importing Research

Bulk migrate legacy user research profiles to the User Truth Canvas (UTC) format with automatic JTBD classification and learning status inference.

---

Trigger

/import-research
/import-research --user {username}
/import-research --dry-run

Examples:

/import-research                    # Migrate all pending users
/import-research --user ncs         # Migrate single user
/import-research --dry-run          # Preview without writing

---

Workflow

Step 1: Scan Source Directory

Find all legacy user profiles:

grimoires/pub/research/users/*.md

Compare against existing UTCs:

grimoires/keeper/canvas/*.md

Build list of pending migrations.

Step 2: Parse Legacy Format

For each legacy file, extract:

1. User Profile:

• Username (from filename)
• Type (if documented)
• Status
• Community/segment

2. Key Quotes:

• Direct quotes with > "..." syntax
• Source (Discord, survey, DM) if noted
• Dates if available

3. Goals/Pain Points:

• Validated Behaviors section
• Insights Contributed

4. Notes:

• Any additional context

Step 3: Infer JTBD

Map extracted data to JTBD taxonomy based on signal patterns:

| Signal Pattern | JTBD Label | |----------------|------------| | "checking", "verifying", "confirm" | [J] Reassure Me This Is Safe | | "understand", "how does", "explain" | [J] Find Information | | "confused", "unclear", "don't know" | [J] Help Me Feel Smart | | "set and forget", "automatic", "passive" | [J] Give Me Peace of Mind | | "waiting", "anxious", "stressed" | [J] Reduce My Anxiety | | "deposit", "claim", "stake", "withdraw" | [J] Make Transaction | | "organize", "manage", "sort" | [J] Organize Assets | | "show off", "status", "badge" | [J] Help Me Look Smart, Cool | | "insider", "exclusive", "alpha" | [J] Help Me Feel Like An Insider | | "express", "identity", "customize" | [J] Let Me Express My Identity |

Select primary JTBD from strongest signal. Secondary if multiple strong signals.

Step 4: Determine Learning Status

Based on evidence strength:

| Evidence Level | Learning Status | |----------------|-----------------| | Single quote, one user | smol-evidence | | Multiple quotes, same theme | directionally-correct | | 5+ users expressing same need | strongly-validated | | Insight marked as "Validated" in tracker | strongly-validated |

Cross-reference with grimoires/keeper/tracker.md for validated insights.

Step 5: Generate UTC File

Create file at grimoires/keeper/canvas/{username}.md:

---
type: user-truth-canvas
user: {username}
created: "{ISO-8601}"
updated: "{ISO-8601}"
learning_status: {smol-evidence|directionally-correct|strongly-validated}
source: {team-internal|dm-to-team|analytics|discord-support}
jtbd_primary: "[J] {label}"
jtbd_secondary: "[J] {label}" | null
linked_journeys: []
linked_issues: []
migrated_from: "grimoires/pub/research/users/{username}.md"
---

# {username} — User Truth Canvas

## 1. Qualitative Evidence

> "{quote 1}"
> — {source}, {date}

> "{quote 2}"
> — {source}, {date}

---

## 2. Quantitative Evidence

| Metric | Value | Source |
|--------|-------|--------|
| Insights contributed | {N} | tracker.md |

*Additional quantitative data if available*

---

## 3. The User Story

**Who**: {User type, segment, community}

**Where**: {Part of product/journey - inferred from quotes}

**When**: {Trigger moment - inferred from quotes}

---

## 4. Inferred Job-To-Be-Done

**Primary**: `[J] {label}` — {One sentence explanation}

**Secondary**: `[J] {label}` — {One sentence explanation} *(if applicable)*

---

## 5. Expectation Gap

| Expected (User Reality) | Actual (Code Reality) | Gap Type | File:Line | Resolution |
|-------------------------|----------------------|----------|-----------|------------|
| {From quotes if evident} | *pending /ground* | TBD | — | pending |

---

## Linked Artifacts

- Legacy Profile: `grimoires/pub/research/users/{username}.md`
- Tracker Insights: {list insight numbers if referenced}

Step 6: Update State

Update grimoires/keeper/state.yaml:

canvases:
  {username}:
    format: utc
    created: "{timestamp}"
    updated: "{timestamp}"
    quotes_count: {n}
    jtbd_primary: "[J] {label}"
    learning_status: {status}
    linked_journeys: []
    migrated_from: "grimoires/pub/research/users/{username}.md"

migration:
  completed:
    - {username}
  pending: []  # Remove migrated users
  last_run: "{timestamp}"

Step 7: Report Output

Import Research Complete

Source: grimoires/pub/research/users/
Users Found: {N}
Already Migrated: {N}
New Imports: {N}

Migration Summary:
┌────────────────┬─────────────────────┬──────────────────┬────────────────┐
│ User           │ Status              │ JTBD (Primary)   │ Learning Status│
├────────────────┼─────────────────────┼──────────────────┼────────────────┤
│ ncs            │ ✓ Imported          │ [J] Find Info    │ validated      │
│ adeitasuna     │ ✓ Imported          │ [J] Reduce Anx   │ directional    │
│ turingog       │ ⊘ Already exists    │ -                │ -              │
│ ...            │ ...                 │ ...              │ ...            │
└────────────────┴─────────────────────┴──────────────────┴────────────────┘

UTCs created: grimoires/keeper/canvas/

Next steps:
- Review migrated UTCs for accuracy
- Run /shape to update journeys
- Run /ground to populate Code Reality columns

---

Dry Run Mode

With --dry-run, show what would be created without writing:

[DRY RUN] Would migrate 9 users:

1. ncs
   - JTBD: [J] Find Information
   - Status: strongly-validated (9 insights)
   - Quotes: 15

2. adeitasuna
   - JTBD: [J] Reduce My Anxiety
   - Status: directionally-correct
   - Quotes: 3

...

No files written. Remove --dry-run to execute.

---

Migration Priority

From PRD, migrate in priority order:

| Priority | User | Insight Count | Reason | |----------|------|---------------|--------| | 1 | ncs | 9 | Highest insight contribution | | 2 | adeitasuna | 2 | Multiple insights | | 3 | satanelrudo | 1 | Insight contributor | | 4 | madcopi79 | 1 | Insight contributor | | 5+ | Others | 0-1 | Complete coverage |

---

Error Handling

| Error | Resolution | |-------|------------| | Legacy file not found | Skip with warning | | UTC already exists | Skip (don't overwrite) unless --force | | Parse error | Log error, continue with others | | No quotes found | Create minimal UTC with note | | JTBD unclear | Default to [J] Find Information |

---

Validation

After migration:

• [ ] All UTC files have valid YAML frontmatter
• [ ] Quotes preserved exactly from source
• [ ] JTBD assigned with rationale
• [ ] Learning status matches evidence level
• [ ] state.yaml updated with all canvases
• [ ] No data lost from legacy files

---

Related

• /observe - Create/update individual canvases
• /shape - Extract journeys from canvases
• tracker.md - Insight validation reference