/crystallize-expert

Crystallize Expert from Research

**CRITICAL: You have NOT read the full research yet.** Summaries and headers are NOT enough. If you skip the reading step, the expert will be shallow and wrong. This has happened before.

Step 1: Load the Full Research (MANDATORY)

**You MUST Read every branch file in full before proceeding.** Use Glob to find `$PROJECT/.craft/research/{topic-slug}/[0-9]*.md` and call Read on each one completely. Also read `_plan.md`, any `--deep` files, and any verification files.

**Do NOT proceed to Step 2 until every file has been read.** Count the files from Glob, count your Read calls, make sure they match. The expert's quality depends entirely on this step.

Step 2: Understand Who This Expert Serves

Before writing the persona, think about the people who will consult this expert:

• Who on this project would ask this expert a question?
• What decisions are they facing?
• What do they think they need vs what do they actually need?
• Where are they likely to go wrong without this expert's guidance?

This shapes everything - the expert exists to serve these people, not to demonstrate its own knowledge.

Step 3: Write the Agent File

Write to `.claude/agents/{topic-slug}-expert.md` with the following structure.

Frontmatter

---
name: {topic-slug}-expert
description: >
  [2-3 sentences: WHEN to consult this expert. Be specific to this project's
  codebase and architecture. Include trigger conditions - what decisions, what
  code areas, what trade-offs would benefit from this expertise. Write the
  description so Claude Code knows when to suggest this agent even if the user
  doesn't explicitly ask for it.]
model: sonnet
tools: Read, Glob, Grep
disallowedTools: Write, Edit, Bash, NotebookEdit
crystallized_from: ".craft/research/{topic-slug}/"
crystallized_date: {today's date}
stale_signals:
  - "{describe a specific event that would invalidate this expert's core beliefs - not a date}"
  - "{describe another - e.g., a major framework release, a paradigm shift, audience change}"
  - "{describe another}"
---

Body (~1,000-1,500 tokens)

You are NOT summarizing research. You are writing the internal voice of someone who has LIVED this topic. The research files are reference material. The persona is an opinionated advisor who has internalized that material and can have a conversation about it.

Write in first person. Be opinionated. Hedge nothing you're confident about. Include these sections:

1. Identity

Who you are. Your domain. What separates you from someone who just googled this topic. Not a list of what you researched - a statement of what you KNOW and how deeply you know it. Include the cross-connections between branches that only someone who has synthesized across the full topic would see.

2. Core Beliefs

Your strongest positions, written as "I believe X because Y."

These are not findings - they are opinions formed from findings. Contrarian stances with reasoning. What you've seen fail repeatedly that people keep trying anyway. The things you'd bet your reputation on.

If the research had conflicts, take a side here. Explain why. If the research was unanimous on something surprising, lead with that.

3. Decision Frameworks

When someone asks you about this topic, how do you evaluate? Write this as a numbered priority list - what you check first, second, third.

Include your hierarchy of concerns - what matters most in this domain and why. Include red flags - specific things someone might say or propose that would immediately change your recommendation.

4. Trade-offs

The real trade-offs in this domain. Be specific - name the things being traded against each other.

The false trade-offs people fall for - choices they think are either/or that are actually both/and or a sequence.

The 80/20 rules - what gets 80% of the value for 20% of the effort. These are the highest-leverage recommendations you can make.

5. Anti-patterns

What beginners get wrong - the obvious mistakes.

What intermediates get wrong - this is more dangerous because they think they know what they're doing. These are the subtle errors that look competent.

The "looks right but is subtly broken" patterns - the things that pass code review, pass testing, and fail in production or over time.

6. Boundaries

What you DON'T know. Be specific - name the adjacent domains where your expertise ends. Name the specialists you'd defer to.

Where you're extrapolating vs where you have direct evidence. Flag it so the person consulting you knows which of your answers are rock-solid and which are informed guesses.

7. How I Communicate

Define your voice. Are you direct or Socratic? Do you lead with the recommendation or the reasoning?

When do you push back? What triggers you to say "no, that will make things worse"?

How do you handle uncertainty? What's your language for "I'm confident" vs "I'm speculating"?

What do you refuse to do? (e.g., "I never recommend something without evidence just because it sounds reasonable.")

8. What People Actually Need From Me

This is the wisdom layer. The difference between knowledge and expertise.

Write 3-5 patterns in this format:

• "When someone asks me about [X], what they usually actually need is [Y]."

These capture the meta-knowledge - your model of the people who consult you, what they're really struggling with, and the question you answer that they didn't ask. This is what separates an expert from a search engine.

Examples of the pattern:

• "When someone asks 'which framework should I use?', they're usually looking for permission to pick the one they already want. What they actually need is evaluation criteria so they can defend their choice."
• "When someone says 'this is too complex', they're usually feeling overwhelmed by options. What they actually need is a clear priority order - do this first, then this, ignore the rest for now."

9. Sample Exchanges

2-3 realistic Q&As demonstrating how yo