feat: add user research workflow with skills, command, and agent

[mattthomps1]

Summary

Adds an optional Research phase to the compound engineering loop. Just as Plan grounds work in codebase context and Review catches issues before shipping, Research grounds product decisions in user evidence — personas, interview insights, and identified opportunities.

1 command, 3 skills, 1 agent. Integrates into brainstorm and plan workflows but is entirely optional — teams without research data experience zero behavioral change.

New Components

Component	Type	Description
/workflows:research	Command	Orchestrates 3 phases: plan research, process transcripts, build personas
research-plan	Skill	Create structured research plans with Teresa Torres methodology
transcript-insights	Skill	Process interview transcripts into tagged insight snapshots
persona-builder	Skill	Synthesize personas from interviews with confidence tracking
user-research-analyst	Agent	Search research artifacts for evidence relevant to planning

How It Fits the Loop

         ┌──────────────────────────────────────────┐
         │          COMPOUND ENGINEERING LOOP        │
         │                                           │
         │   Research (optional, feeds into Plan)    │
         │       ↓                                   │
         │   Plan → Work → Review → Compound         │
         └──────────────────────────────────────────┘

Key Decisions

1. "Do No Harm" — Producer Messages, Consumer Silences

The most important design constraint: existing workflows must behave identically when no research data exists.

How it works: user-research-analyst runs in parallel during brainstorm/plan. When docs/research/ is empty, the agent returns "No data found." But the consuming workflows don't surface that — they skip silently:

# In brainstorm.md:
If `user-research-analyst` returns relevant findings, briefly summarize them.
If no research data exists, skip the summary silently and proceed directly
to the collaborative dialogue — do not mention the absence of research
or suggest running `/workflows:research`.

Pattern: the producer handles absence with a message; the consumer handles absence with silence. This prevents nagging users who don't use research.

2. Privacy by Design

Transcripts contain PII and are gitignored by default. Only anonymized snapshots and personas get committed. Skills enforce PII stripping with MUST language, not advisory "consider" language.

Directory	Contents	Committed?
docs/research/plans/	Research plans with hypotheses	Yes
docs/research/transcripts/	Raw interview transcripts (PII)	No (gitignored)
docs/research/interviews/	Anonymized interview snapshots	Yes
docs/research/personas/	Living persona documents	Yes

3. No Hard Prerequisites Between Phases

Transcripts can be processed without creating a research plan first — select "Ad-hoc / no plan" during processing. The phase recommender prioritizes actionable data (unprocessed transcripts) over missing prerequisites (no plan).

4. Single Canonical Reference — Extensible by Design

discovery-playbook.md (Teresa Torres + Mom Test methodology, 414 lines / 10 sections) lives in research-plan/references/ and is referenced by the other two skills via relative path. No duplication.

5. Parallel Execution

user-research-analyst runs alongside repo-research-analyst (brainstorm) and learnings-researcher (plan). No serial bottleneck added.

Also Included

• Wired research context into existing /workflows:brainstorm and /workflows:plan commands
• Compound learnings doc: docs/solutions/integration-issues/adding-optional-workflow-phases-with-graceful-degradation.md
• Solution doc for workflow routing fix and transcript input mismatch
• Removed PII sample data and deduplicated discovery playbook during review

Test Plan

"Do no harm" tests (most important):

• Run /workflows:brainstorm with NO research data — verify zero behavioral change (no mention of research)
• Run /workflows:plan with NO research data — verify zero behavioral change

Feature tests:

• Run /workflows:research plan — verify research plan created at docs/research/plans/
• Run /workflows:research process with a transcript — verify anonymized snapshot at docs/research/interviews/
• Run /workflows:research process without a plan — verify "Ad-hoc / no plan" option works
• Run /workflows:research personas with existing snapshots — verify persona at docs/research/personas/
• Run /workflows:brainstorm WITH research data — verify personas/insights surfaced before dialogue
• Run /workflows:plan WITH research data — verify user evidence in Step 1.6 consolidation

Extensibility:

• Edit discovery-playbook.md — verify all 3 skills load updated content on next invocation

Verification:

• .gitignore includes docs/research/transcripts/*.md

Post-Deploy Monitoring & Validation

No additional operational monitoring required: plugin-only change with no runtime/server component. Existing workflows remain unaffected when docs/research/ is empty.

---

🤖 Generated with Claude Code