qualitative-research-pro 1.0.0

package/hooks/dist/transcript-parser.mjs

@@ -0,0 +1,214 @@
+// src/transcript-parser.ts
+import * as fs from "fs";
+function parseTranscript(transcriptPath) {
+  const summary = {
+    lastTodos: [],
+    recentToolCalls: [],
+    lastAssistantMessage: "",
+    filesModified: [],
+    errorsEncountered: []
+  };
+  if (!fs.existsSync(transcriptPath)) {
+    return summary;
+  }
+  const content = fs.readFileSync(transcriptPath, "utf-8");
+  const lines = content.split("\n").filter((line) => line.trim());
+  const allToolCalls = [];
+  const modifiedFiles = /* @__PURE__ */ new Set();
+  const errors = [];
+  let lastTodoState = [];
+  let lastAssistant = "";
+  for (const line of lines) {
+    try {
+      const entry = JSON.parse(line);
+      if (entry.role === "assistant" && typeof entry.content === "string") {
+        lastAssistant = entry.content;
+      } else if (entry.type === "assistant" && typeof entry.content === "string") {
+        lastAssistant = entry.content;
+      }
+      if (entry.tool_name || entry.type === "tool_use") {
+        const toolName = entry.tool_name || entry.name;
+        if (toolName) {
+          const toolCall = {
+            name: toolName,
+            timestamp: entry.timestamp,
+            input: entry.tool_input,
+            success: true
+            // Will be updated by result
+          };
+          if (toolName === "TodoWrite" || toolName.toLowerCase().includes("todowrite")) {
+            const input = entry.tool_input;
+            if (input?.todos) {
+              lastTodoState = input.todos.map((t, idx) => ({
+                id: t.id || `todo-${idx}`,
+                content: t.content || "",
+                status: t.status || "pending"
+              }));
+            }
+          }
+          if (toolName === "Edit" || toolName === "Write" || toolName.toLowerCase().includes("edit") || toolName.toLowerCase().includes("write")) {
+            const input = entry.tool_input;
+            const filePath = input?.file_path || input?.path;
+            if (filePath && typeof filePath === "string") {
+              modifiedFiles.add(filePath);
+            }
+          }
+          if (toolName === "Bash" || toolName.toLowerCase().includes("bash")) {
+            const input = entry.tool_input;
+            if (input?.command) {
+              toolCall.input = { command: input.command };
+            }
+          }
+          allToolCalls.push(toolCall);
+        }
+      }
+      if (entry.type === "tool_result" || entry.tool_result !== void 0) {
+        const result = entry.tool_result;
+        if (result) {
+          const exitCode = result.exit_code ?? result.exitCode;
+          if (exitCode !== void 0 && exitCode !== 0) {
+            if (allToolCalls.length > 0) {
+              allToolCalls[allToolCalls.length - 1].success = false;
+            }
+            const errorMsg = result.stderr || result.error || "Command failed";
+            const lastTool = allToolCalls[allToolCalls.length - 1];
+            const command = lastTool?.input?.command || "unknown command";
+            errors.push(`${command}: ${errorMsg.substring(0, 200)}`);
+          }
+        }
+        if (entry.error) {
+          errors.push(entry.error.substring(0, 200));
+          if (allToolCalls.length > 0) {
+            allToolCalls[allToolCalls.length - 1].success = false;
+          }
+        }
+      }
+    } catch {
+      continue;
+    }
+  }
+  summary.lastTodos = lastTodoState;
+  summary.recentToolCalls = allToolCalls.slice(-5);
+  summary.lastAssistantMessage = lastAssistant.substring(0, 500);
+  summary.filesModified = Array.from(modifiedFiles);
+  summary.errorsEncountered = errors.slice(-5);
+  return summary;
+}
+function generateAutoHandoff(summary, sessionName) {
+  const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+  const dateOnly = timestamp.split("T")[0];
+  const lines = [];
+  const inProgress = summary.lastTodos.filter((t) => t.status === "in_progress");
+  const pending = summary.lastTodos.filter((t) => t.status === "pending");
+  const completed = summary.lastTodos.filter((t) => t.status === "completed");
+  const currentTask = inProgress[0]?.content || pending[0]?.content || "Continue from auto-compact";
+  const goalSummary = completed.length > 0 ? `Completed ${completed.length} task(s) before auto-compact` : "Session auto-compacted";
+  lines.push("---");
+  lines.push(`session: ${sessionName}`);
+  lines.push(`date: ${dateOnly}`);
+  lines.push("status: partial");
+  lines.push("outcome: PARTIAL_PLUS");
+  lines.push("---");
+  lines.push("");
+  lines.push(`goal: ${goalSummary}`);
+  lines.push(`now: ${currentTask}`);
+  lines.push("test: # No test command captured");
+  lines.push("");
+  lines.push("done_this_session:");
+  if (completed.length > 0) {
+    completed.forEach((t) => {
+      lines.push(`  - task: "${t.content.replace(/"/g, '\\"')}"`);
+      lines.push("    files: []");
+    });
+  } else {
+    lines.push('  - task: "Session started"');
+    lines.push("    files: []");
+  }
+  lines.push("");
+  lines.push("blockers:");
+  if (summary.errorsEncountered.length > 0) {
+    summary.errorsEncountered.slice(0, 3).forEach((e) => {
+      const safeError = e.replace(/"/g, '\\"').substring(0, 100);
+      lines.push(`  - "${safeError}"`);
+    });
+  } else {
+    lines.push("  []");
+  }
+  lines.push("");
+  lines.push("questions:");
+  if (pending.length > 0) {
+    pending.slice(0, 3).forEach((t) => {
+      lines.push(`  - "Resume: ${t.content.replace(/"/g, '\\"')}"`);
+    });
+  } else {
+    lines.push("  []");
+  }
+  lines.push("");
+  lines.push("decisions:");
+  lines.push('  - auto_compact: "Context limit reached, auto-compacted"');
+  lines.push("");
+  lines.push("findings:");
+  lines.push(`  - tool_calls: "${summary.recentToolCalls.length} recent tool calls"`);
+  lines.push(`  - files_modified: "${summary.filesModified.length} files changed"`);
+  lines.push("");
+  lines.push("worked:");
+  const successfulTools = summary.recentToolCalls.filter((t) => t.success);
+  if (successfulTools.length > 0) {
+    lines.push(`  - "${successfulTools.map((t) => t.name).join(", ")} completed successfully"`);
+  } else {
+    lines.push("  []");
+  }
+  lines.push("");
+  lines.push("failed:");
+  const failedTools = summary.recentToolCalls.filter((t) => !t.success);
+  if (failedTools.length > 0) {
+    lines.push(`  - "${failedTools.map((t) => t.name).join(", ")} encountered errors"`);
+  } else {
+    lines.push("  []");
+  }
+  lines.push("");
+  lines.push("next:");
+  if (inProgress.length > 0) {
+    lines.push(`  - "Continue: ${inProgress[0].content.replace(/"/g, '\\"')}"`);
+  }
+  if (pending.length > 0) {
+    pending.slice(0, 2).forEach((t) => {
+      lines.push(`  - "${t.content.replace(/"/g, '\\"')}"`);
+    });
+  }
+  if (inProgress.length === 0 && pending.length === 0) {
+    lines.push('  - "Review session state and continue"');
+  }
+  lines.push("");
+  lines.push("files:");
+  lines.push("  created: []");
+  lines.push("  modified:");
+  if (summary.filesModified.length > 0) {
+    summary.filesModified.slice(0, 10).forEach((f) => {
+      lines.push(`    - "${f}"`);
+    });
+  } else {
+    lines.push("    []");
+  }
+  return lines.join("\n");
+}
+var isMainModule = import.meta.url === `file://${process.argv[1]}`;
+if (isMainModule) {
+  const args = process.argv.slice(2);
+  if (args.length === 0) {
+    console.log("Usage: npx tsx transcript-parser.ts <transcript-path> [session-name]");
+    process.exit(1);
+  }
+  const transcriptPath = args[0];
+  const sessionName = args[1] || "test-session";
+  console.log(`Parsing transcript: ${transcriptPath}`);
+  const summary = parseTranscript(transcriptPath);
+  console.log("\n--- Summary ---");
+  console.log(JSON.stringify(summary, null, 2));
+  console.log("\n--- Auto-Handoff ---");
+  console.log(generateAutoHandoff(summary, sessionName));
+}
+export {
+  generateAutoHandoff,
+  parseTranscript
+};

package/install.sh

@@ -0,0 +1,194 @@
+#!/bin/bash
+# Qualitative Research Pro installer
+# Academic qualitative research squad for Claude Code / Codex CLI
+# Merges ecosystem files without overwriting your existing setup
+
+set -e
+
+REPO_DIR="$(cd "$(dirname "$0")" && pwd)"
+CLAUDE_DIR="$HOME/.claude"
+FORCE=false
+ADDED=0
+SKIPPED=0
+
+for arg in "$@"; do
+  case $arg in
+    --force) FORCE=true ;;
+    --non-interactive) NON_INTERACTIVE=true ;;
+    --help|-h)
+      echo "Usage: ./install.sh [--force] [--non-interactive]"
+      echo ""
+      echo "  --force            Overwrite existing files (default: skip existing)"
+      echo "  --non-interactive  Skip confirmation prompt"
+      echo ""
+      echo "Without --force, only NEW files are added. Your existing agents,"
+      echo "skills, hooks, and rules are preserved."
+      exit 0
+      ;;
+  esac
+done
+
+echo "Qualitative Research Pro installer"
+echo "========================"
+echo ""
+echo "Academic qualitative research squad for Claude Code"
+echo ""
+AGENT_COUNT=$(find "$REPO_DIR/agents" -name "*.md" 2>/dev/null | wc -l | tr -d ' ')
+SKILL_COUNT=$(find "$REPO_DIR/skills" -mindepth 1 -maxdepth 1 -type d 2>/dev/null | wc -l | tr -d ' ')
+HOOK_COUNT=$(find "$REPO_DIR/hooks/src" -maxdepth 1 -name "*.ts" 2>/dev/null | wc -l | tr -d ' ')
+RULE_COUNT=$(find "$REPO_DIR/rules" -name "*.md" 2>/dev/null | wc -l | tr -d ' ')
+
+echo "This will install into ~/.claude/:"
+echo "  - $AGENT_COUNT agents  -> ~/.claude/agents/"
+echo "  - $SKILL_COUNT skills  -> ~/.claude/skills/"
+echo "  - $HOOK_COUNT hooks   -> ~/.claude/hooks/"
+echo "  - $RULE_COUNT rules   -> ~/.claude/rules/"
+echo ""
+if [ "$FORCE" = true ]; then
+  echo "Mode: OVERWRITE (--force) — existing files will be replaced"
+else
+  echo "Mode: MERGE (default) — existing files will be preserved"
+fi
+echo ""
+
+# Check for Python
+if command -v python3 &>/dev/null; then
+  PY_VERSION=$(python3 --version 2>/dev/null | head -1)
+  echo "Python detected: $PY_VERSION"
+else
+  echo "WARNING: Python 3 not found. Install it for data processing utilities."
+fi
+
+# Check for pandoc
+if command -v pandoc &>/dev/null; then
+  echo "pandoc detected"
+else
+  echo "NOTE: pandoc not found. Install it: brew install pandoc"
+fi
+echo ""
+
+if [ "$NON_INTERACTIVE" != true ]; then
+  read -p "Continue? (y/N) " -n 1 -r
+  echo
+  [[ $REPLY =~ ^[Yy]$ ]] || exit 0
+fi
+
+if [ "$FORCE" = true ]; then
+  if [ -d "$CLAUDE_DIR/agents" ] || [ -d "$CLAUDE_DIR/skills" ]; then
+    BACKUP="$CLAUDE_DIR/backup-$(date +%Y%m%d-%H%M%S)"
+    echo "Backing up existing files to: $BACKUP"
+    mkdir -p "$BACKUP"
+    [ -d "$CLAUDE_DIR/agents" ] && cp -r "$CLAUDE_DIR/agents" "$BACKUP/"
+    [ -d "$CLAUDE_DIR/skills" ] && cp -r "$CLAUDE_DIR/skills" "$BACKUP/"
+    [ -d "$CLAUDE_DIR/hooks" ] && cp -r "$CLAUDE_DIR/hooks" "$BACKUP/"
+    [ -d "$CLAUDE_DIR/rules" ] && cp -r "$CLAUDE_DIR/rules" "$BACKUP/"
+    echo ""
+  fi
+fi
+
+smart_copy_file() {
+  local src="$1"
+  local dest="$2"
+  if [ "$FORCE" = true ] || [ ! -e "$dest" ]; then
+    cp "$src" "$dest"
+    ADDED=$((ADDED + 1))
+  else
+    SKIPPED=$((SKIPPED + 1))
+  fi
+}
+
+smart_copy_dir() {
+  local src="$1"
+  local dest="$2"
+  if [ "$FORCE" = true ] || [ ! -e "$dest" ]; then
+    cp -r "$src" "$dest"
+    ADDED=$((ADDED + 1))
+  else
+    SKIPPED=$((SKIPPED + 1))
+  fi
+}
+
+echo "Installing agents..."
+mkdir -p "$CLAUDE_DIR/agents"
+for f in "$REPO_DIR/agents/"*.md; do
+  [ -f "$f" ] || continue
+  name=$(basename "$f")
+  smart_copy_file "$f" "$CLAUDE_DIR/agents/$name"
+done
+
+echo "Installing skills..."
+mkdir -p "$CLAUDE_DIR/skills"
+for d in "$REPO_DIR/skills/"*/; do
+  name=$(basename "$d")
+  [ "$name" = "*" ] && continue
+  smart_copy_dir "$d" "$CLAUDE_DIR/skills/$name"
+done
+
+echo "Installing hooks..."
+mkdir -p "$CLAUDE_DIR/hooks/dist"
+mkdir -p "$CLAUDE_DIR/hooks/src/shared"
+for f in "$REPO_DIR/hooks/dist/"*.mjs; do
+  [ -f "$f" ] || continue
+  name=$(basename "$f")
+  smart_copy_file "$f" "$CLAUDE_DIR/hooks/dist/$name"
+done
+for f in "$REPO_DIR/hooks/src/"*.ts; do
+  [ -f "$f" ] || continue
+  name=$(basename "$f")
+  smart_copy_file "$f" "$CLAUDE_DIR/hooks/src/$name"
+done
+for f in "$REPO_DIR/hooks/src/shared/"*.ts; do
+  [ -f "$f" ] || continue
+  name=$(basename "$f")
+  smart_copy_file "$f" "$CLAUDE_DIR/hooks/src/shared/$name"
+done
+[ -f "$REPO_DIR/hooks/package.json" ] && cp "$REPO_DIR/hooks/package.json" "$CLAUDE_DIR/hooks/package.json"
+[ -f "$REPO_DIR/hooks/tsconfig.json" ] && cp "$REPO_DIR/hooks/tsconfig.json" "$CLAUDE_DIR/hooks/tsconfig.json"
+HOOK_COUNT=$(ls "$CLAUDE_DIR/hooks/dist/"*.mjs 2>/dev/null | wc -l | tr -d ' ')
+
+echo "Installing rules..."
+mkdir -p "$CLAUDE_DIR/rules"
+for f in "$REPO_DIR/rules/"*.md; do
+  [ -f "$f" ] || continue
+  name=$(basename "$f")
+  smart_copy_file "$f" "$CLAUDE_DIR/rules/$name"
+done
+
+echo "Installing scripts..."
+if [ -d "$REPO_DIR/scripts" ]; then
+  mkdir -p "$CLAUDE_DIR/scripts"
+  for f in "$REPO_DIR/scripts/"*; do
+    [ -f "$f" ] || continue
+    name=$(basename "$f")
+    smart_copy_file "$f" "$CLAUDE_DIR/scripts/$name"
+  done
+fi
+
+if [ -d "$REPO_DIR/.github/workflows" ]; then
+  echo "Installing GitHub workflow templates..."
+  mkdir -p "$CLAUDE_DIR/.github/workflows"
+  for f in "$REPO_DIR/.github/workflows/"claude-*.yml; do
+    [ -f "$f" ] || continue
+    name=$(basename "$f")
+    smart_copy_file "$f" "$CLAUDE_DIR/.github/workflows/$name"
+  done
+fi
+
+echo ""
+echo "Installation complete!"
+echo "  Added:   $ADDED files"
+echo "  Skipped: $SKIPPED files (already existed)"
+echo ""
+echo "  Agents: $(ls "$CLAUDE_DIR/agents/"*.md 2>/dev/null | wc -l | tr -d ' ')"
+echo "  Skills: $(find "$CLAUDE_DIR/skills/" -mindepth 1 -maxdepth 1 -type d 2>/dev/null | wc -l | tr -d ' ')"
+echo "  Hooks:  ${HOOK_COUNT:-$(ls "$CLAUDE_DIR/hooks/dist/"*.mjs 2>/dev/null | wc -l | tr -d ' ')}"
+echo "  Rules:  $(ls "$CLAUDE_DIR/rules/"*.md 2>/dev/null | wc -l | tr -d ' ')"
+echo ""
+if [ $SKIPPED -gt 0 ]; then
+  echo "Tip: Use ./install.sh --force to overwrite existing files."
+fi
+echo ""
+echo "Recommended tools for Qualitative Research Pro:"
+echo "  - Zotero: https://www.zotero.org/"
+echo "  - pandoc: brew install pandoc"
+echo "  - Python 3.10+: for data processing utilities"

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "qualitative-research-pro",
+  "version": "1.0.0",
+  "description": "Academic qualitative research squad for grounded theory, qualitative analysis, academic writing, and research methodology",
+  "type": "module",
+  "bin": {
+    "qualitative-research-pro": "./bin/cli.mjs"
+  },
+  "files": [
+    "agents/",
+    "skills/",
+    "hooks/dist/",
+    "hooks/hooks.json",
+    "rules/",
+    "plugin.json",
+    "bin/",
+    "install.sh",
+    "CLAUDE.md",
+    "AGENTS.md"
+  ],
+  "keywords": [
+    "grounded-theory",
+    "qualitative-research",
+    "academic-research",
+    "glaser",
+    "coding",
+    "memoing",
+    "methodology",
+    "claude-code",
+    "ai-agents",
+    "research-methods"
+  ],
+  "author": "ccashwell (https://github.com/ccashwell)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ccashwell/qualitative-research-pro.git"
+  },
+  "homepage": "https://github.com/ccashwell/qualitative-research-pro#readme",
+  "bugs": {
+    "url": "https://github.com/ccashwell/qualitative-research-pro/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/plugin.json

@@ -0,0 +1,19 @@
+{
+  "name": "qualitative-research-pro",
+  "description": "Academic qualitative research squad for grounded theory analysis, qualitative methodology, academic writing, and research ethics with Claude Code",
+  "version": "1.0.0",
+  "author": {
+    "name": "ccashwell",
+    "url": "https://github.com/ccashwell"
+  },
+  "repository": "https://github.com/ccashwell/qualitative-research-pro",
+  "license": "MIT",
+  "keywords": [
+    "grounded-theory",
+    "qualitative-research",
+    "academic-research",
+    "glaser",
+    "methodology",
+    "claude-code"
+  ]
+}

package/rules/academic-writing-style.md

@@ -0,0 +1,42 @@
+# Academic Writing Style (Qualitative Research)
+
+Use this rule when drafting manuscripts, dissertations, memos-for-publication, or research communications.
+
+## Voice and Hedging
+
+- Prefer **active voice** for clarity (“We analyzed…” / “The analysis shows…”). Use passive sparingly for standard methods or when the actor is irrelevant.
+- Hedge interpretive claims appropriately: “suggests,” “indicates,” “may,” “appears to,” paired with evidence.
+- Avoid overstated universals (“always,” “proves”) unless design supports them.
+
+## APA 7th Edition Defaults
+
+- Default to **APA 7th** unless a journal or program specifies otherwise.
+- Use author–date in-text citations and a corresponding reference list.
+- Follow APA heading levels, seriation, and bias-free language guidance.
+
+## Paragraph Structure and Flow
+
+- One main idea per paragraph; opening sentence states the claim or move.
+- Support with evidence or logical development; close with a transition or implication.
+- Use **transition words** purposefully (however, therefore, moreover, in contrast, consequently) to signal relationships.
+
+## First Person in Qualitative Work
+
+- First person is acceptable for researcher actions, positionality, and method narration when consistent with venue norms.
+- Maintain analytic focus: the researcher’s voice frames; participants’ voices illustrate.
+
+## Participant Voice and Analysis
+
+- Present verbatim or lightly edited excerpts in block quotes with clear attribution (pseudonym, role if relevant).
+- Follow each excerpt with **analytical commentary** that interprets significance; avoid “data dumps.”
+- Balance empathy with analytic distance; name categories and relationships explicitly.
+
+## Jargon and Accessibility
+
+- Define specialized terms on first use; prefer precise ordinary language when it serves readers.
+- Reserve theory-laden labels for concepts earned through analysis, not imported labels without justification.
+
+## Logical Flow
+
+- Move from concrete evidence to abstract claims; signpost structure in introductions and discussions.
+- Align discussion claims with findings sections; flag limitations without undermining transparent interpretation.

package/rules/citation-standards.md

@@ -0,0 +1,47 @@
+# Citation Standards (APA 7 & Chicago)
+
+Use this rule for in-text citations, reference lists, and methodology-heavy qualitative manuscripts.
+
+## APA 7th Edition (Default)
+
+### In-Text Citations
+
+- **Narrative**: Glaser (1978) argued that…
+- **Parenthetical**: (Glaser, 1978, p. 45) for direct quotes with page numbers when available.
+- For **paraphrases**, include page numbers when quoting closely or when pagination aids verification.
+- **Et al.**: For works with three or more authors, use first author + “et al.” in every citation (APA 7).
+
+### Reference List
+
+- Alphabetize; hanging indent; include DOI or URL when available, formatted per APA.
+- **DOIs**: Prefer `https://doi.org/10.xxxx/xxxxx` in stable form.
+- Match every in-text citation to a reference entry; verify years and editions.
+
+## Chicago (Notes-Bibliography or Author-Date)
+
+- Use when discipline or venue requires (e.g., some humanities fields).
+- **Notes**: Full note first occurrence; shortened notes thereafter; bibliography with full details.
+- **Author-date**: Parallel to APA in spirit but follow Chicago spacing and punctuation rules.
+
+## Canonical Grounded Theory Sources (Examples for Reference Lists)
+
+- Glaser, B. G. (1978). *Theoretical sensitivity*. Sociology Press.
+- Glaser, B. G. (1992). *Basics of grounded theory analysis*. Sociology Press.
+- Glaser, B. G. (1998). *Doing grounded theory: Issues and discussions*. Sociology Press.
+- Glaser, B. G., & Strauss, A. L. (1967). *The discovery of grounded theory*. Aldine.
+
+Always verify pagination, city, and publisher requirements of your style manual and publisher.
+
+## Unpublished Data and Field Materials
+
+- Cite participant data **only** as allowed by consent and IRB; typically avoid identifiable archives in references.
+- Use generic descriptors in methods (“interview data, 2024–2026”) unless a registered repository is approved.
+
+## Secondary Sources
+
+- Prefer **primary** sources; when citing a source quoted in another work, credit both per APA secondary source rules.
+- In qualitative writing, trace original methodological claims to original texts when possible.
+
+## Quality Checks
+
+- [ ] DOIs/URLs resolve; [ ] edition/year correct for seminal texts; [ ] direct quotes have locations; [ ] unpublished items handled per ethics approval.

package/rules/current-methodological-state.md

@@ -0,0 +1,40 @@
+# Current Methodological State (2026)
+
+Use this rule for tool selection, AI-assisted workflows, and situating grounded theory within contemporary qualitative debates.
+
+## CAQDAS Landscape (Circa 2026)
+
+Major platforms continue to evolve on collaboration, cloud deployment, and mixed-methods integration:
+
+- **NVivo 15** — Widely used in applied and team projects; strong query and coding tools; verify institutional license and data residency.
+- **ATLAS.ti 24** — Visual/network-friendly; check export options for long-term archival needs.
+- **MAXQDA 2024** — Mixed-methods and survey linkage features; confirm encryption and team workflows.
+- **Dedoose** — Browser-based collaboration; suitable for distributed teams; validate security posture for sensitive data.
+
+Choose based on **IRB constraints**, **encryption**, **audit logs**, **vendor lock-in**, and **training** available to the team.
+
+## AI-Assisted Qualitative Analysis
+
+- **Ethical considerations**: consent for machine processing, data processing agreements, re-identification risk in cloud APIs, and institutional AI policies.
+- **Appropriate uses**: administrative tasks (formatting timestamps), **hypothesis generation** to be verified against data, exploratory summaries under researcher supervision.
+- **Limitations**: synthetic “themes” without traceability, hallucinated citations, flattening of context, and weak accountability for marginalized voices.
+- Always retain **human-led** coding, memoing, and audit trails; treat AI output as **provisional**.
+
+## Debates in Grounded Theory and Qualitative Inquiry
+
+- **Methodological evolution**: classic, evolved, and constructivist GT lineages; clarity about lineage reduces talking-past-one-another in review.
+- **Digital ethnography**: platform norms, trace data ethics, and rapid context change challenge static field boundaries.
+- **Visual GT**: images and multimodal data as empirical materials; require explicit semiotic and ethical handling.
+
+## Key Recent Publications (Illustrative Directions)
+
+- Follow current issues of *Qualitative Inquiry*, *Qualitative Research*, *Forum: Qualitative Social Research*, and flagship handbooks in your discipline for **up-to-date** exemplars and controversies—verify citations at write time.
+
+## APA and Open Science
+
+- **APA 7th** remains the default in much social and behavioral science; confirm journal supplements for qualitative reporting (e.g., exemplar tables, positionality).
+- **Open science in qualitative work**: preregistration where feasible, registered reports in some venues, **de-identified** data and excerpt sharing when ethical; opaque sharing when not.
+
+## Practical Takeaway
+
+Pair tool choices and AI use with **ethics approval**, **documentation**, and **transparent** statements of analytic lineage—software and models change; accountable process endures.

package/rules/data-handling.md

@@ -0,0 +1,44 @@
+# Qualitative Data Handling
+
+Use this rule for organizing, securing, anonymizing, and retaining qualitative materials across the research lifecycle.
+
+## File Naming Conventions
+
+- Use consistent, machine-safe names: `YYYY-MM-DD_pseudonym_session01_transcript-v2.docx` (adjust to IRB constraints).
+- Avoid real names, initials tied to identity, or geotags in filenames and metadata.
+- Version transcripts and coded exports with `_v#` or semantic versioning notes in a change log.
+
+## Directory Structure (Example)
+
+- `01_admin/` — IRB, consent templates (encrypted), recruitment logs (de-identified).
+- `02_raw/` — audio/video (encrypted); restricted access.
+- `03_processed/` — transcripts, anonymized field notes, cleaned documents.
+- `04_analysis/` — exports from CAQDAS, codebooks, memo banks.
+- `05_outputs/` — figures, models, publication-ready excerpts (reviewed for disclosure risk).
+
+## Anonymization Procedures
+
+- Replace direct identifiers; generalize places and dates when they enable re-identification.
+- Review quotations for **jigsaw risk** (combinations of details that identify individuals or sites).
+- Maintain a separate, secured **re-identification key** if required for follow-up; never merge key with shared analytic files.
+
+## Secure Storage
+
+- Institutional secure drives or approved encrypted containers; full-disk encryption on field devices.
+- Separate accounts for shared projects; log access where policy requires.
+- Delete local copies of restricted files from personal devices after secure upload.
+
+## Backup Strategy
+
+- Follow 3-2-1 principles where permitted: three copies, two media types, one off-site **approved** backup.
+- Test restores periodically; document backup locations and responsible parties.
+
+## CAQDAS Tool Recommendations
+
+- **NVivo**, **ATLAS.ti**, **MAXQDA**, **Dedoose** — choose based on collaboration needs, mixed methods, cloud policy, and institutional licenses.
+- Export codebooks and project logs regularly in vendor-neutral formats when available.
+
+## Retention and Destruction
+
+- Align with IRB, funder, and legal holds; document destruction dates and methods (secure erase, shredding).
+- Clarify whether participants consented to archiving or future reuse; honor opt-outs.