| name | thematic-analysis |
| description | 基于 Braun & Clarke 反思性主题分析框架的质性研究辅助工具。
支持两种输入模式：
（1）直接提供原始访谈文本 → skill 逐份完成 TA 初始编码，汇总后进入主题识别；
（2）提供已有初始编码池 → 直接进入聚类、审查、命名建议流程。
输出结构化候选主题表，明确标注边界模糊编码与待研究者裁定的命名建议。
当用户提到"主题分析"“主题编码”"帮我聚类编码""从编码提炼主题""Braun Clarke""候选主题"
"这些编码怎么归主题""帮我看看主题结构""对访谈做主题分析"时触发此 skill。
注意与 grounded-coding 的区别：grounded-coding 面向程序化扎根理论的类属建构与理论关系；
thematic-analysis 面向 Braun & Clarke 路线的语义主题识别，输出主题结构而非理论命题。
|
主题分析辅助工具（Thematic Analysis）
本 skill 基于 Braun & Clarke（2006, 2019）的反思性主题分析框架，支持从原始访谈文本
到候选主题结构的完整分析流程。
重要定位：主题命名是分析行为，体现研究者的理论判断，最终命名必须由研究者作出。
本 skill 在命名阶段只提供备选，不做裁定。
方法论前提：Braun & Clarke 的反思性 TA 要求研究者对所有访谈逐份独立完成初始编码，
再将全部编码汇总为统一的编码池，然后才进入主题搜寻阶段。
启动：确认输入类型
触发后，第一步必须确认输入类型：
"你现在准备做主题分析——你手上有的是：
A. 原始访谈文本（尚未编码）
B. 已完成的初始编码（一份或多份）
哪种情况？"
情况 A：提供原始访谈文本 → 进入初始编码阶段
情况 B：提供已有初始编码 → 询问是否已汇总，进入编码池处理
编码风格确认（情况 A 专用，可选）
确认为情况 A 后，在正式开始编码前，询问研究者是否希望提供示范编码：
"在正式编码前，你可以选择：
A. 研究者示范：你先对文本中任意一小段（3–5 句）做示范编码，AI 会识别你的编码风格，然后按你的风格完成后续编码
B. AI 直接编码：跳过示范，AI 按照标准原则直接开始
哪种方式？（选 B 或不回应则直接开始）"
若研究者选择 A（研究者示范）：
- 请研究者提供示范片段及其对应编码（格式：
"原文" → [编码标签]）
- AI 分析示范编码的风格特征，明确说明：
- 粒度：偏细（逐句）还是偏粗（逐段）？
- 用词：in-vivo（受访者原话）为主，还是研究者概括语言为主？
- 长度：编码标签通常几个字？
- 描述取向：倾向描述行为，还是描述情绪/态度？
- 输出风格确认：
"我理解你的编码风格是：[描述]。我将按照此风格完成后续编码。如有偏差，请随时纠正。"
- 按研究者风格继续执行步骤 1–2.5
若研究者选择 B 或未回应：
直接进入步骤 1，按标准原则编码。
初始编码阶段（情况 A）
TA 的初始编码与扎根理论的开放编码有本质差异：
| TA 初始编码 | GT 开放编码 |
|---|
| 目标 | 捕捉意义单元，贴近数据语言 | 为类属建构准备，需要概念抽象 |
| 粒度 | 短语级，尽量用受访者原话 | 可更高度概括 |
| 后续 | 汇总后搜寻主题（并列结构） | 归并类属、属性维度分析（层级结构） |
单份访谈编码操作
研究者提供原始访谈文本后，执行以下步骤：
步骤 1：通读全文，识别意义单元
逐句扫描全文。只有以下两类才可跳过，且必须在编码结果中标注"已跳过"：
- 纯粹的单词应答，独立成句（如仅有"嗯""对""好的"）
- 访谈者的提问语句本身（非受访者发言）
其余所有语句，无论看起来信息量多少，都作为意义单元处理并给出编码。某句话是否重要，是研究者的判断权，不是 AI 的判断权。当不确定时，给出一个描述性编码（如"重复前述观点""表达不确定"），而不是跳过。
步骤 2：逐单元生成初始编码
编码原则：
- 贴近数据：编码词汇尽量来自受访者的语言，而非研究者的理论术语
- 描述性：编码描述"发生了什么"或"受访者表达了什么"，不解释"为什么"
- 细粒度：一个意义单元只给一个最准确的编码，不做归并
- in-vivo 优先：若受访者某个表达特别精准，直接用原话作为编码
- 禁止对仗整齐：编码标签的字数和句法结构应由数据内容决定，而非由输出形式决定。in-vivo 编码可长可短，描述性编码因意义单元的复杂程度而异。如果回头检查发现大多数编码字数相近、结构相同（如全部是"X的Y"或"对X的Z"），说明在优化形式而非忠实于数据，必须主动打破这种整齐感，让编码长短形态反映数据本身的多样性。
输出格式：
【访谈 N】初始编码
（被访者简称 / 编号）
原文片段 → 编码
"......" → [编码标签]
"......" → [编码标签]
...
本份编码总数：N 条
步骤 2.5：自动保存编码结果到文件（强制执行，不可跳过）
编码输出完成后，必须立即调用 Write 工具将编码写入文件。不得仅在对话中输出而不写文件。
文件命名规则：coding_[被访者编号或简称].md
（如 coding_A.md、coding_P1.md）
保存路径：当前工作目录（即项目目录根目录）
文件内容格式：
# 【访谈 X】初始编码
被访者：[编号/简称]
编码日期：[日期]
## 编码列表
"原文片段" → [编码标签]
"原文片段" → [编码标签]
...
## 统计
本份编码总数：N 条
Write 工具调用完成后，告知研究者：
"本份编码已通过 Write 工具保存至 coding_[被访者编号].md。"
步骤 3：询问是否继续下一份
"【访谈 N】初始编码完成，共 N 条。
还有下一份访谈文本吗？如有，请提供；
如果这是最后一份，我们进入编码汇总。"
所有访谈编码完成后，自动进入辅助汇总流程。
编码池处理（情况 B）
研究者已有初始编码时，询问汇总状态：
"你已有的初始编码来自几份访谈？是否已经汇总到一份列表里？"
已汇总 → 直接进入后续信息收集
未汇总 → 执行辅助汇总
研究者依次提供各份访谈的编码：
【访谈 N】（被访者简称或编号）
编码1
编码2
...
辅助汇总
无论来自情况 A 还是情况 B，所有编码汇总后输出：
汇总编码池
总编码数：N 条
来源访谈：P1, P2, ... PN
跨访谈重复出现的编码（出现 ≥2 次）：
- [编码名]：出现于 P1, P3
- ...
单份访谈独有的编码：
- [编码名] [P2]
- ...
汇总完成后，收集后续必要信息：
必填：研究问题——用一句话说明研究在问什么，是判断主题相关性的基本参照。
选填：理论视角——若有，在主题审查阶段提示主题与理论的对话关系。
选填：当前困惑——若对某些编码归属已有疑虑，先行标注，优先处理。
执行流程
确认编码池完整后，自动连续执行以下四个阶段，无需每步等待用户确认。
第一阶段：编码全貌扫描
在进入聚类之前，先对全部编码做一次整体扫描，输出：
- 编码总数
- 编码的大致分布特征（哪些概念域出现频繁）
- 初步识别出的"编码聚集带"（尚未命名的雏形聚类）
- 标记出你认为"孤立编码"（与其他编码缺少关联的）
这一步的目的是让研究者在进入正式聚类前，先看到编码的整体地形。
第二阶段：候选主题聚类
将编码归入候选主题，输出 5–8 个候选主题（若编码数量极少可减少）。
聚类原则：
- 语义相关性优先：同一主题内的编码应指向同一类经验或意义
- 不强行归并：宁可留出"边界模糊编码"，也不牵强归类
- 不以频率决定主题：高频编码不等于独立主题，低频编码可能是重要主题
- 允许层级结构：若某主题内部明显可分为两个子方向，可提出主题+子主题
每个候选主题的输出格式：
候选主题 [序号]：[暂定名称（描述性，非最终）]
核心含义：用1-2句话说明这个主题在捕捉什么经验或意义
包含编码：
- [编码1]
- [编码2]
- ...
边界模糊编码（归属不确定，需研究者判断）：
- [编码X]：模糊原因
- [编码Y]：模糊原因
第三阶段：主题审查
对每个候选主题从以下三个维度进行审查，输出审查意见：
内部一致性
这个主题内部的编码，是否都在描述同一种经验或意义？
还是有些编码其实属于不同的现象被勉强归在一起？
外部区分度
这个主题与其他候选主题之间的边界是否清晰？
如果有两个主题高度重叠，指出它们的差异在哪里，以及是否应该合并或拆分。
与研究问题的相关性
这个主题是否真正在回应研究问题？
还是它只是材料中的一个高频现象，但与研究问题关系较弱？
审查结果中，对每个候选主题给出明确判断：
- 保留：内部一致、外部清晰、与研究问题相关
- 建议合并：与某主题高度重叠，说明合并依据
- 建议拆分：内部包含两个不同方向，说明拆分依据
- 建议降级：可作为某主题的子主题，而非独立主题
- 存疑待判：内部一致性或相关性尚不确定，需研究者决定
备忘录提示（可选）： 主题审查过程中，如果某个主题让你产生了理论联想——觉得"这个主题和某个理论概念很像"或"这两个主题之间的张力说明了什么"——现在就可以切到 analytic-memo，把这个想法写成分析备忘录。TA 的备忘录不需要遵循扎根理论的结构，直接说出你的想法即可。
第四阶段：命名建议与移交
这是 skill 移交给研究者的关键节点。
对每个通过审查的主题，提供：
命名建议（2–3 个备选）
每个备选名称附说明：
- 这个名称捕捉了什么？
- 它遗漏了什么？
- 它在理论上暗示了什么立场？
格式：
备选名称 A：[名称]
- 优点：...
- 局限：...
- 理论暗示：...
备选名称 B：[名称]
- 优点：...
- 局限：...
- 理论暗示：...
理论定位追问
在呈现完所有主题的备选名称后，输出以下追问：
命名背后的理论立场值得多停一步。
不同的备选名称往往暗示不同的理论对话方向——
对于让你犹豫的主题，可以问自己：
- 这个名称是在描述现象，还是在解释机制？
- 它更靠近哪个已有的理论概念？这种靠近是你想要的吗？
- 如果换一个名称，你的研究会加入一场不同的理论对话——你想去哪场？
移交声明
在所有命名建议之后，输出以下固定文字：
命名判断移交研究者。
主题命名体现研究者的理论立场，以上备选名称仅供参考。
以下问题请研究者自行判断后告知，以便进入后续工作：
- 哪些主题的名称已确定？
- 哪些主题的名称需要修改？
- 是否需要对某些主题进行合并、拆分或删除？
强制：主题汇总表自动保存
研究者确认主题命名后，必须立即执行以下保存步骤（不可跳过）：
调用 Write 工具，将最终主题结构保存至项目目录：
文件命名：themes_[研究主题].md（如 themes_快车司机.md、themes_平台工人.md）
保存路径：当前工作目录（项目根目录）
文件内容：
- 研究问题（一句话）
- 主题结构表（含主题编号、名称、核心含义、包含编码数、代表性语句）
- 边界模糊编码的处理记录
Write 完成后告知研究者：
"themes_[研究主题].md 已保存至项目目录，供后续 ta-methods-writer、ta-findings-writer 等 skill 自动读取。"
可选后续操作
研究者确认主题命名后，还可继续请求以下任意操作：
操作 A：生成主题结构摘要
输出一份完整的主题结构表，格式如下：
| 主题编号 | 主题名称 | 核心含义 | 包含编码数 | 代表性语句（若有原文） |
|---|
操作 B：追问特定主题
对研究者指定的某个主题，做更深入的分析：
- 这个主题在材料中是如何被体现的？
- 它内部是否存在张力或矛盾？
- 它与哪个理论概念最接近？距离在哪里？
操作 C：识别主题之间的关系
分析候选主题之间是否存在：
- 因果或条件关系
- 对立或张力关系
- 层级或包含关系
- 时间序列关系
输出主题关系图谱（文字版）。
操作 D：保存主题结构到本地
将最终确认的主题结构保存为 Markdown 文件。
文件名格式：YYYY-MM-DD_themes_<研究主题关键词>.md
默认保存路径：~/Documents/research-memos/themes/
文件内容包含：研究问题、主题结构表、各主题含义说明、边界模糊编码处理记录。
与其他 skill 的关系
| Skill | 定位 | 何时使用 |
|---|
thematic-analysis | 初始编码 + 主题识别与结构化 | 从原始访谈文本到候选主题的完整 TA 流程 |
grounded-coding | 开放编码与类属建构（GT专用） | 需要程序化扎根理论的系统编码与持续比较 |
negative-case-finder | 反例与边界条件识别 | 主题确定后，挑战主题的普遍性 |
analytic-memo | 分析备忘录（AI代写） | 主题审查中产生分析直觉，需要快速记录 |
推荐流程：
thematic-analysis（逐份初始编码 → 汇总编码池 → 候选主题）
↓
negative-case-finder（挑战主题的边界）
↓
analytic-memo（深化核心主题的理论思考）
参考文献
- 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.
说明：
- 2006年论文是主题分析最核心的方法论来源
- 2019年论文是 Braun & Clarke 对"反思性主题分析"的重要修订，明确反对机械化六步执行
- 本 skill 的设计以反思性取向为指导，强调研究者主导判断，避免把主题分析变成流程执行
语言
- 默认中文
- 若用户用英文输入，输出用英文，frontmatter 字段名保持英文
