thematic-analysis

Thematic Analysis Assistant Tool (Thematic Analysis)

This skill is based on the reflexive thematic analysis framework of Braun & Clarke (2006, 2019), and supports the complete analysis workflow from raw interview texts to a candidate theme structure.

Important positioning: Theme naming is an analytical act that reflects the researcher's theoretical judgment, and the final naming must be made by the researcher. In the naming stage, this skill only provides alternatives and does not make determinations.

Methodological premise: Braun & Clarke's reflexive TA requires the researcher toallconduct initial coding independently for each interview, then aggregate all codes into a unified coding pool before proceeding to the theme search stage.

Start: Confirm the input type

After being triggered,the first step must be to confirm the input type：

"You are now preparing to conduct thematic analysis—what you have on hand is: A. Raw interview texts (not yet coded) B. Completed initial codes (one or more) Which case is it?"

Case A: Provide raw interview texts → enter the initial coding stage

Case B: Provide existing initial codes → ask whether they have been aggregated, and enter coding pool processing

Coding style confirmation (for Case A only, optional)

After confirming it is Case A, before formally starting coding, ask the researcher whether they wish to provide demonstration coding:

"Before formal coding, you can choose: A. Researcher demonstration: You first perform demonstration coding on any small passage of the text (3–5 sentences); the AI will identify your coding style, and then complete the subsequent coding according to your style B. AI direct coding: Skip the demonstration, and the AI starts directly according to standard principles

Which method? (If you choose B or do not respond, it will start directly)"

If the researcher chooses A (researcher demonstration):

Ask the researcher to provide the demonstration passage and its corresponding codes (format:"原文" → [编码标签]）
The AI analyzes the stylistic features of the demonstration coding and clearly states:
- Granularity: finer (sentence-by-sentence) or coarser (paragraph-by-paragraph)?
- Wording: mainly in-vivo (the interviewee's own words), or mainly the researcher's summarizing language?
- Length: how many characters are the code labels usually?
- Descriptive orientation: more inclined to describe behavior, or to describe emotions/attitudes?
Output style confirmation:

"I understand your coding style to be: [description]. I will complete the subsequent coding according to this style. If there is any deviation, please correct me at any time."
Continue executing steps 1–2.5 according to the researcher's style

If the researcher chooses B or does not respond:

Proceed directly to step 1 and code according to standard principles.

Initial coding stage (Case A)

There is an essential difference between initial coding in TA and open coding in grounded theory:

	TA initial coding	GT open coding
Goal	Capture meaning units and stay close to the language of the data	Prepare for category construction and require conceptual abstraction
Granularity	Phrase-level, using the interviewee's own words as much as possible	Can be summarized at a higher level
Subsequent	Search for themes after aggregation (parallel structure)	Merge categories and analyze attribute dimensions (hierarchical structure)

Single interview coding operation

After the researcher provides the original interview text, execute the following steps:

Step 1: Read through the full text and identify meaning units

Scan the full text sentence by sentence.Onlythe following two categories may be skipped, and they must be marked as "skipped" in the coding results:

Pure single-word responses that stand alone as sentences (such as only "mm" "right" "okay")
The interviewer's question statements themselves (not the interviewee's speech)

All other statements,regardless of how informative they appear, are treated as meaning units and given codes. Whether a sentence is important is the researcher's right to judge, not the AI's right to judge. When uncertain, give a descriptive code (such as "repeats previous viewpoint" "expresses uncertainty") rather than skipping it.

Step 2: Generate initial codes unit by unit

Coding principles:

Stay close to the data: coding vocabulary should come as much as possible from the interviewee's language, not the researcher's theoretical terminology
Descriptive: codes describe "what happened" or "what the interviewee expressed," not explain "why"
Fine-grained: one meaning unit is given only one most accurate code, without merging
in-vivo priority: if a certain expression by the interviewee is particularly precise, use the original words directly as the code
Prohibit neat parallelism: the word count and syntactic structure of code labels should be determined by the data content, not by the output form. In-vivo codes can be long or short, and descriptive codes vary according to the complexity of the meaning unit.If upon later review you find that most codes have similar word counts and the same structure (such as all being "Y of X" or "Z toward X"), it indicates that form is being optimized rather than remaining faithful to the data, and this sense of neatness must be actively broken so that the length and form of codes reflect the diversity of the data itself.

Output format:

【访谈 N】初始编码
（被访者简称 / 编号）

原文片段 → 编码
"......" → [编码标签]
"......" → [编码标签]
...

本份编码总数：N 条

Step 2.5: Automatically save coding results to a file (mandatory, cannot be skipped)

After the coding output is completed,the Write tool must be called immediatelyto write the codes to a file. It is not permitted to only output in the conversation without writing to a file.

File naming rules:coding_[被访者编号或简称].md (such as coding_A.md、coding_P1.md）

Save path: current working directory (that is, the project directory root)

File content format:

# 【访谈 X】初始编码
被访者：[编号/简称]
编码日期：[日期]

## 编码列表
"原文片段" → [编码标签]
"原文片段" → [编码标签]
...

## 统计
本份编码总数：N 条

After the Write tool call is completed, inform the researcher:

"This coding has been saved via the Write tool to coding_[被访者编号].md。"

Step 3: Ask whether to continue to the next one

"[Interview N] initial coding completed, N items in total. Is there a next interview text? If so, please provide it; if this is the last one, we will proceed to coding aggregation."

After all interview coding is completed, automatically enter the assisted aggregation process.

Code pool processing (Case B)

When the researcher already has initial codes, ask about the aggregation status:

"How many interviews do your existing initial codes come from? Have they already been aggregated into one list?"

Already aggregated → directly proceed to subsequent information collection

Not aggregated → execute assisted aggregation

The researcher provides the codes for each interview in turn:

【访谈 N】（被访者简称或编号）
编码1
编码2
...

Supplementary summary

Regardless of whether it comes from Situation A or Situation B, all codes are summarized and output:

汇总编码池
总编码数：N 条
来源访谈：P1, P2, ... PN

跨访谈重复出现的编码（出现 ≥2 次）：
- [编码名]：出现于 P1, P3
- ...

单份访谈独有的编码：
- [编码名] [P2]
- ...

After the summary is complete, collect the necessary follow-up information:

Required: Research question—State in one sentence what the research is asking, as the basic reference for judging topic relevance.

Optional: Theoretical perspective—If available, indicate the dialogic relationship between the topic and the theory during the topic review stage.

Optional: Current confusion—If there are already doubts about the attribution of certain codes, mark them first and handle them first.

Execution process

After confirming that the code pool is complete,automatically execute continuouslythe following four stages, without waiting for user confirmation at each step.

Stage 1: Full scan of codes

Before entering clustering, first conduct an overall scan of all codes and output:

Total number of codes
The rough distribution characteristics of the codes (which conceptual domains appear frequently)
Preliminary identified "code clusters" (prototype clusters not yet named)
Mark the ones you consider "isolated codes" (lacking connection with other codes)

The purpose of this step is to let the researcher see the overall terrain of the codes before entering formal clustering.

Stage 2: Candidate theme clustering

Group the codes into candidate themes and output 5–8 candidate themes(may be reduced if the number of codes is very small).

Clustering principles:

Semantic relevance takes priority: Codes within the same theme should point to the same type of experience or meaning
Do not force merging: It is better to leave out "boundary-ambiguous codes" than to classify them far-fetchedly
Do not determine themes by frequency: High-frequency codes do not equal independent themes, and low-frequency codes may be important themes
Allow hierarchical structure: If a theme can clearly be divided into two sub-directions internally, a theme + subthemes may be proposed

Output format for each candidate theme:

候选主题 [序号]：[暂定名称（描述性，非最终）]

核心含义：用1-2句话说明这个主题在捕捉什么经验或意义

包含编码：
- [编码1]
- [编码2]
- ...

边界模糊编码（归属不确定，需研究者判断）：
- [编码X]：模糊原因
- [编码Y]：模糊原因

Stage 3: Theme review

Review each candidate theme from the following three dimensions and output review opinions:

Internal consistency

Do the codes within this theme all describe the same type of experience or meaning? Or are some codes actually different phenomena that have been forcibly grouped together?

External distinctiveness

Is the boundary between this theme and other candidate themes clear? If two themes overlap highly, point out where their differences lie and whether they should be merged or split.

Relevance to the research question

Does this theme truly respond to the research question? Or is it merely a high-frequency phenomenon in the material but weakly related to the research question?

In the review results, give a clear judgment for each candidate theme:

Keep: internally consistent, externally clear, and relevant to the research question
Suggest merging: highly overlapping with a certain theme; explain the basis for merging
Suggest splitting: internally contains two different directions; explain the basis for splitting
Suggest downgrading: can serve as a subtheme of a certain theme rather than an independent theme
Uncertain, pending judgment: Internal consistency or relevance is not yet certain; the researcher must decide

Memo prompt (optional): During the theme review process, if a theme sparks a theoretical association for you—feeling that "this theme is very similar to some theoretical concept" or "what does the tension between these two themes explain"—you can now switch to analytic-memo, and write this thought as an analytical memo. TA's memos do not need to follow the grounded theory structure; just state your thoughts directly.

Phase Four: Naming Suggestions and Handover

This is the key point at which the skill hands over to the researcher.

For each theme that passes review, provide:

Naming suggestions (2–3 alternatives)

Each alternative name is accompanied by an explanation:

What does this name capture?
What does it omit?
What position does it theoretically imply?

Format:

备选名称 A：[名称]
- 优点：...
- 局限：...
- 理论暗示：...

备选名称 B：[名称]
- 优点：...
- 局限：...
- 理论暗示：...

Theoretical positioning follow-up questions

After presenting the alternative names for all themes, output the following follow-up questions:

The theoretical stance behind naming is worth pausing on for an extra step. Different alternative names often imply different directions of theoretical dialogue— for themes that make you hesitate, you can ask yourself:

Is this name describing a phenomenon, or explaining a mechanism?

Which existing theoretical concept is it closer to? Is this closeness what you want?

If you change to another name, your study will join a different theoretical conversation—which one do you want to join?

Handover statement

After all naming suggestions, output the following fixed text:

Naming judgment is handed over to the researcher. Theme naming reflects the researcher's theoretical stance; the above alternative names are for reference only. Please ask the researcher to judge the following questions themselves and inform us, so that subsequent work can proceed:

Which theme names have been finalized?

Which theme names need revision?

Do certain themes need to be merged, split, or deleted?

Mandatory: Automatic saving of the theme summary table

After the researcher confirms the theme naming,the following saving steps must be performed immediately (cannot be skipped)：

Call the Write tool to save the final theme structure to the project directory:

File naming:themes_[研究主题].md(e.g., themes_快车司机.md、themes_平台工人.md) Save path: current working directory (project root directory)

File content:

Research question (one sentence)
Theme structure table (including theme number, name, core meaning, number of included codes, representative statements)
Handling records for boundary-ambiguous codes

After Write is completed, inform the researcher:

"themes_[研究主题].md has been saved to the project directory for subsequent ta-methods-writer、ta-findings-writer and other skills to automatically read."

Optional follow-up operations

After the researcher confirms the theme naming, they may also continue to request any of the following operations:

Operation A: Generate a theme structure summary

Output a complete theme structure table in the following format:

Theme number	Theme name	Core meaning	Number of included codes	Representative statements (if original text is available)

Operation B: Follow up on a specific theme

Conduct a deeper analysis of a specific topic designated by the researcher:

How is this topic manifested in the material?
Are there internal tensions or contradictions within it?
Which theoretical concept is it closest to? Where does the gap lie?

Operation C: Identify relationships between themes

Analyze whether the following exist between candidate themes:

Causal or conditional relationships
Oppositional or tension relationships
Hierarchical or containment relationships
Temporal sequence relationships

Output a thematic relationship map (text version).

Operation D: Save the thematic structure locally

Save the finalized thematic structure as a Markdown file.

File name format:YYYY-MM-DD_themes_<研究主题关键词>.md

Default save path:~/Documents/research-memos/themes/

File contents include: research question, thematic structure table, explanations of each theme's meaning, and records of handling boundary-ambiguous coding.

Relationship with other skills

Skill	Positioning	When to use
`thematic-analysis`	Initial coding + theme identification and structuring	The complete TA process from raw interview text to candidate themes
`grounded-coding`	Open coding and category construction (GT-specific)	Systematic coding and constant comparison requiring procedural grounded theory
`negative-case-finder`	Counterexample and boundary condition identification	After themes are determined, challenge the universality of the themes
`analytic-memo`	Analytic memos (AI-assisted writing)	Analytical intuitions arise during theme review and need to be recorded quickly

Recommended workflow:

thematic-analysis（逐份初始编码 → 汇总编码池 → 候选主题）
    ↓
negative-case-finder（挑战主题的边界）
    ↓
analytic-memo（深化核心主题的理论思考）

References

Braun, V., & Clarke, V. (2006). Using thematic analysis in psychology. Qualitative Research in Psychology, 3(2), 77–101.
Braun, V., & Clarke, V. (2019). Reflecting on reflexive thematic analysis. Qualitative Research in Sport, Exercise and Health, 11(4), 589–597.
Clarke, V., & Braun, V. (2017). Thematic analysis. Journal of Positive Psychology, 12(3), 297–298.

Note:

The 2006 paper is the most core methodological source for thematic analysis
The 2019 paper is Braun & Clarke's important revision of "reflexive thematic analysis," explicitly opposing mechanical execution of the six steps
The design of this skill is guided by a reflexive orientation, emphasizing researcher-led judgment and avoiding turning thematic analysis into process execution

Language

Default Chinese
If the user inputs in English, output in English, and keep frontmatter field names in English