@mseep/open-computer-use 1.0.0

package/skills/examples/product-marketing-context/SKILL.md

@@ -0,0 +1,241 @@
+---
+name: product-marketing-context
+description: "When the user wants to create or update their product marketing context document. Also use when the user mentions 'product context,' 'marketing context,' 'set up context,' 'positioning,' 'who is my target audience,' 'describe my product,' 'ICP,' 'ideal customer profile,' or wants to avoid repeating foundational information across marketing tasks. Use this at the start of any new project before using other marketing skills — it creates `.agents/product-marketing-context.md` that all other skills reference for product, audience, and positioning context."
+metadata:
+  version: 1.1.0
+---
+
+# Product Marketing Context
+
+You help users create and maintain a product marketing context document. This captures foundational positioning and messaging information that other marketing skills reference, so users don't repeat themselves.
+
+The document is stored at `.agents/product-marketing-context.md`.
+
+## Workflow
+
+### Step 1: Check for Existing Context
+
+First, check if `.agents/product-marketing-context.md` already exists. Also check `.claude/product-marketing-context.md` for older setups — if found there but not in `.agents/`, offer to move it.
+
+**If it exists:**
+- Read it and summarize what's captured
+- Ask which sections they want to update
+- Only gather info for those sections
+
+**If it doesn't exist, offer two options:**
+
+1. **Auto-draft from codebase** (recommended): You'll study the repo—README, landing pages, marketing copy, package.json, etc.—and draft a V1 of the context document. The user then reviews, corrects, and fills gaps. This is faster than starting from scratch.
+
+2. **Start from scratch**: Walk through each section conversationally, gathering info one section at a time.
+
+Most users prefer option 1. After presenting the draft, ask: "What needs correcting? What's missing?"
+
+### Step 2: Gather Information
+
+**If auto-drafting:**
+1. Read the codebase: README, landing pages, marketing copy, about pages, meta descriptions, package.json, any existing docs
+2. Draft all sections based on what you find
+3. Present the draft and ask what needs correcting or is missing
+4. Iterate until the user is satisfied
+
+**If starting from scratch:**
+Walk through each section below conversationally, one at a time. Don't dump all questions at once.
+
+For each section:
+1. Briefly explain what you're capturing
+2. Ask relevant questions
+3. Confirm accuracy
+4. Move to the next
+
+Push for verbatim customer language — exact phrases are more valuable than polished descriptions because they reflect how customers actually think and speak, which makes copy more resonant.
+
+---
+
+## Sections to Capture
+
+### 1. Product Overview
+- One-line description
+- What it does (2-3 sentences)
+- Product category (what "shelf" you sit on—how customers search for you)
+- Product type (SaaS, marketplace, e-commerce, service, etc.)
+- Business model and pricing
+
+### 2. Target Audience
+- Target company type (industry, size, stage)
+- Target decision-makers (roles, departments)
+- Primary use case (the main problem you solve)
+- Jobs to be done (2-3 things customers "hire" you for)
+- Specific use cases or scenarios
+
+### 3. Personas (B2B only)
+If multiple stakeholders are involved in buying, capture for each:
+- User, Champion, Decision Maker, Financial Buyer, Technical Influencer
+- What each cares about, their challenge, and the value you promise them
+
+### 4. Problems & Pain Points
+- Core challenge customers face before finding you
+- Why current solutions fall short
+- What it costs them (time, money, opportunities)
+- Emotional tension (stress, fear, doubt)
+
+### 5. Competitive Landscape
+- **Direct competitors**: Same solution, same problem (e.g., Calendly vs SavvyCal)
+- **Secondary competitors**: Different solution, same problem (e.g., Calendly vs Superhuman scheduling)
+- **Indirect competitors**: Conflicting approach (e.g., Calendly vs personal assistant)
+- How each falls short for customers
+
+### 6. Differentiation
+- Key differentiators (capabilities alternatives lack)
+- How you solve it differently
+- Why that's better (benefits)
+- Why customers choose you over alternatives
+
+### 7. Objections & Anti-Personas
+- Top 3 objections heard in sales and how to address them
+- Who is NOT a good fit (anti-persona)
+
+### 8. Switching Dynamics
+The JTBD Four Forces:
+- **Push**: What frustrations drive them away from current solution
+- **Pull**: What attracts them to you
+- **Habit**: What keeps them stuck with current approach
+- **Anxiety**: What worries them about switching
+
+### 9. Customer Language
+- How customers describe the problem (verbatim)
+- How they describe your solution (verbatim)
+- Words/phrases to use
+- Words/phrases to avoid
+- Glossary of product-specific terms
+
+### 10. Brand Voice
+- Tone (professional, casual, playful, etc.)
+- Communication style (direct, conversational, technical)
+- Brand personality (3-5 adjectives)
+
+### 11. Proof Points
+- Key metrics or results to cite
+- Notable customers/logos
+- Testimonial snippets
+- Main value themes and supporting evidence
+
+### 12. Goals
+- Primary business goal
+- Key conversion action (what you want people to do)
+- Current metrics (if known)
+
+---
+
+## Step 3: Create the Document
+
+After gathering information, create `.agents/product-marketing-context.md` with this structure:
+
+```markdown
+# Product Marketing Context
+
+*Last updated: [date]*
+
+## Product Overview
+**One-liner:**
+**What it does:**
+**Product category:**
+**Product type:**
+**Business model:**
+
+## Target Audience
+**Target companies:**
+**Decision-makers:**
+**Primary use case:**
+**Jobs to be done:**
+-
+**Use cases:**
+-
+
+## Personas
+| Persona | Cares about | Challenge | Value we promise |
+|---------|-------------|-----------|------------------|
+| | | | |
+
+## Problems & Pain Points
+**Core problem:**
+**Why alternatives fall short:**
+-
+**What it costs them:**
+**Emotional tension:**
+
+## Competitive Landscape
+**Direct:** [Competitor] — falls short because...
+**Secondary:** [Approach] — falls short because...
+**Indirect:** [Alternative] — falls short because...
+
+## Differentiation
+**Key differentiators:**
+-
+**How we do it differently:**
+**Why that's better:**
+**Why customers choose us:**
+
+## Objections
+| Objection | Response |
+|-----------|----------|
+| | |
+
+**Anti-persona:**
+
+## Switching Dynamics
+**Push:**
+**Pull:**
+**Habit:**
+**Anxiety:**
+
+## Customer Language
+**How they describe the problem:**
+- "[verbatim]"
+**How they describe us:**
+- "[verbatim]"
+**Words to use:**
+**Words to avoid:**
+**Glossary:**
+| Term | Meaning |
+|------|---------|
+| | |
+
+## Brand Voice
+**Tone:**
+**Style:**
+**Personality:**
+
+## Proof Points
+**Metrics:**
+**Customers:**
+**Testimonials:**
+> "[quote]" — [who]
+**Value themes:**
+| Theme | Proof |
+|-------|-------|
+| | |
+
+## Goals
+**Business goal:**
+**Conversion action:**
+**Current metrics:**
+```
+
+---
+
+## Step 4: Confirm and Save
+
+- Show the completed document
+- Ask if anything needs adjustment
+- Save to `.agents/product-marketing-context.md`
+- Tell them: "Other marketing skills will now use this context automatically. Run `/product-marketing-context` anytime to update it."
+
+---
+
+## Tips
+
+- **Be specific**: Ask "What's the #1 frustration that brings them to you?" not "What problem do they solve?"
+- **Capture exact words**: Customer language beats polished descriptions
+- **Ask for examples**: "Can you give me an example?" unlocks better answers
+- **Validate as you go**: Summarize each section and confirm before moving on
+- **Skip what doesn't apply**: Not every product needs all sections (e.g., Personas for B2C)

package/skills/examples/product-marketing-context/evals/evals.json

@@ -0,0 +1,85 @@
+{
+  "skill_name": "product-marketing-context",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I want to set up my product marketing context. We're a B2B SaaS company that sells a customer feedback platform to product teams.",
+      "expected_output": "Should check if .agents/product-marketing-context.md already exists. If not, should offer two options: (1) Auto-draft from codebase (recommended) or (2) Start from scratch. If user chooses start from scratch, should walk through sections conversationally one at a time. Should cover all applicable sections: Product Overview, Target Audience, Personas, Problems You Solve, Competitive Landscape, Differentiation, Objections, Switching Dynamics, Customer Language, Brand Voice, Proof Points, and Goals. Should create the file at .agents/product-marketing-context.md when complete.",
+      "assertions": [
+        "Checks for existing product-marketing-context.md",
+        "Offers two options: auto-draft or start from scratch",
+        "Covers applicable sections",
+        "Walks through sections conversationally one at a time",
+        "Creates file at .agents/product-marketing-context.md"
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "Update our product marketing context. We just added a new enterprise tier and our target audience has expanded to include VP of Engineering, not just Product Managers.",
+      "expected_output": "Should check for existing .agents/product-marketing-context.md and read it. Should identify which sections need updating based on the changes: Target Audience (add VP of Engineering), Personas (add new persona), Product Overview (new enterprise tier, including pricing updates within that section), Objections (enterprise-specific), and Competitive Landscape (enterprise competitors). Should update only the relevant sections, preserving existing content that hasn't changed.",
+      "assertions": [
+        "Reads existing product-marketing-context.md",
+        "Identifies sections that need updating",
+        "Updates Target Audience with VP of Engineering",
+        "Adds new persona for the expanded audience",
+        "Updates Product Overview for enterprise tier",
+        "Preserves unchanged sections"
+      ],
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "create a product context doc for my app. it's a mobile app that helps people find hiking trails. we're just getting started.",
+      "expected_output": "Should trigger on casual phrasing. Should check for existing context doc. Should offer auto-draft or start-from-scratch options. Should adapt questions for an early-stage B2C mobile app (outdoor/fitness niche). Should note that some sections may be sparse for an early-stage product and that's okay — they can be filled in as the business matures. Should skip non-applicable sections (e.g., Personas section is B2B-focused) rather than forcing all 12. Should accept lighter answers for sections like Proof Points or Competitive Landscape if the company is new.",
+      "assertions": [
+        "Triggers on casual phrasing",
+        "Checks for existing context doc",
+        "Offers auto-draft or start-from-scratch options",
+        "Adapts questions for early-stage B2C mobile app",
+        "Notes some sections may be sparse early on",
+        "Skips non-applicable sections rather than forcing all 12",
+        "Creates file at .agents/product-marketing-context.md"
+      ],
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "Can you auto-draft our product marketing context from our existing codebase and marketing materials?",
+      "expected_output": "Should activate the auto-draft workflow mode. Should scan the codebase for existing marketing context: README, landing page copy, pricing page, about page, meta descriptions, any existing documentation. Should draft the product-marketing-context.md from what it finds, filling in sections where information is available and flagging sections that need manual input. Should present the draft for review before saving.",
+      "assertions": [
+        "Activates auto-draft workflow mode",
+        "Scans codebase for existing marketing materials",
+        "Drafts context from found information",
+        "Flags sections needing manual input",
+        "Presents draft for review before saving"
+      ],
+      "files": []
+    },
+    {
+      "id": 5,
+      "prompt": "Do we have a product marketing context set up? I want to make sure the other marketing skills have context about our product.",
+      "expected_output": "Should check for .agents/product-marketing-context.md (and the older .claude/product-marketing-context.md location). Should report whether it exists and summarize its contents if found. If it doesn't exist, should offer to create one and explain why it's valuable (other skills like copywriting, page-cro, seo-audit check for it first). Should explain how other skills use this context document.",
+      "assertions": [
+        "Checks both file locations",
+        "Reports whether context doc exists",
+        "Summarizes contents if found",
+        "Offers to create if missing",
+        "Explains how other skills use it"
+      ],
+      "files": []
+    },
+    {
+      "id": 6,
+      "prompt": "Write homepage copy for our SaaS product.",
+      "expected_output": "Should recognize this is a copywriting task, not a product marketing context task. Should check for product-marketing-context.md (as other skills do), and if it doesn't exist, may suggest creating one first. But should defer to the copywriting skill for actually writing the homepage copy.",
+      "assertions": [
+        "Recognizes this as a copywriting task",
+        "May check for or suggest creating product-marketing-context.md",
+        "References or defers to copywriting skill for the actual copy",
+        "Does not attempt to write homepage copy using context creation patterns"
+      ],
+      "files": []
+    }
+  ]
+}

package/skills/examples/single-cell-rna-qc/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: single-cell-rna-qc
+description: Performs quality control on single-cell RNA-seq data (.h5ad or .h5 files) using scverse best practices with MAD-based filtering and comprehensive visualizations. Use when users request QC analysis, filtering low-quality cells, assessing data quality, or following scverse/scanpy best practices for single-cell analysis.
+---
+
+# Single-Cell RNA-seq Quality Control
+
+Automated QC workflow for single-cell RNA-seq data following scverse best practices.
+
+## When to Use This Skill
+
+Use when users:
+- Request quality control or QC on single-cell RNA-seq data
+- Want to filter low-quality cells or assess data quality
+- Need QC visualizations or metrics
+- Ask to follow scverse/scanpy best practices
+- Request MAD-based filtering or outlier detection
+
+**Supported input formats:**
+- `.h5ad` files (AnnData format from scanpy/Python workflows)
+- `.h5` files (10X Genomics Cell Ranger output)
+
+**Default recommendation**: Use Approach 1 (complete pipeline) unless the user has specific custom requirements or explicitly requests non-standard filtering logic.
+
+## Approach 1: Complete QC Pipeline (Recommended for Standard Workflows)
+
+For standard QC following scverse best practices, use the convenience script `scripts/qc_analysis.py`:
+
+```bash
+python3 scripts/qc_analysis.py input.h5ad
+# or for 10X Genomics .h5 files:
+python3 scripts/qc_analysis.py raw_feature_bc_matrix.h5
+```
+
+The script automatically detects the file format and loads it appropriately.
+
+**When to use this approach:**
+- Standard QC workflow with adjustable thresholds (all cells filtered the same way)
+- Batch processing multiple datasets
+- Quick exploratory analysis
+- User wants the "just works" solution
+
+**Requirements:** anndata, scanpy, scipy, matplotlib, seaborn, numpy
+
+**Parameters:**
+
+Customize filtering thresholds and gene patterns using command-line parameters:
+- `--output-dir` - Output directory
+- `--mad-counts`, `--mad-genes`, `--mad-mt` - MAD thresholds for counts/genes/MT%
+- `--mt-threshold` - Hard mitochondrial % cutoff
+- `--min-cells` - Gene filtering threshold
+- `--mt-pattern`, `--ribo-pattern`, `--hb-pattern` - Gene name patterns for different species
+
+Use `--help` to see current default values.
+
+**Outputs:**
+
+All files are saved to `<input_basename>_qc_results/` directory by default (or to the directory specified by `--output-dir`):
+- `qc_metrics_before_filtering.png` - Pre-filtering visualizations
+- `qc_filtering_thresholds.png` - MAD-based threshold overlays
+- `qc_metrics_after_filtering.png` - Post-filtering quality metrics
+- `<input_basename>_filtered.h5ad` - Clean, filtered dataset ready for downstream analysis
+- `<input_basename>_with_qc.h5ad` - Original data with QC annotations preserved
+
+If copying outputs to `/mnt/user-data/outputs/` for user access, copy individual files (not the entire directory) so users can preview them directly as Assistant.ai artifacts.
+
+### Workflow Steps
+
+The script performs the following steps:
+
+1. **Calculate QC metrics** - Count depth, gene detection, mitochondrial/ribosomal/hemoglobin content
+2. **Apply MAD-based filtering** - Permissive outlier detection using MAD thresholds for counts/genes/MT%
+3. **Filter genes** - Remove genes detected in few cells
+4. **Generate visualizations** - Comprehensive before/after plots with threshold overlays
+
+## Approach 2: Modular Building Blocks (For Custom Workflows)
+
+For custom analysis workflows or non-standard requirements, use the modular utility functions from `scripts/qc_core.py` and `scripts/qc_plotting.py`:
+
+```python
+# Run from scripts/ directory, or add scripts/ to sys.path if needed
+import anndata as ad
+from qc_core import calculate_qc_metrics, detect_outliers_mad, filter_cells
+from qc_plotting import plot_qc_distributions  # Only if visualization needed
+
+adata = ad.read_h5ad('input.h5ad')
+calculate_qc_metrics(adata, inplace=True)
+# ... custom analysis logic here
+```
+
+**When to use this approach:**
+- Different workflow needed (skip steps, change order, apply different thresholds to subsets)
+- Conditional logic (e.g., filter neurons differently than other cells)
+- Partial execution (only metrics/visualization, no filtering)
+- Integration with other analysis steps in a larger pipeline
+- Custom filtering criteria beyond what command-line params support
+
+**Available utility functions:**
+
+From `qc_core.py` (core QC operations):
+- `calculate_qc_metrics(adata, mt_pattern, ribo_pattern, hb_pattern, inplace=True)` - Calculate QC metrics and annotate adata
+- `detect_outliers_mad(adata, metric, n_mads, verbose=True)` - MAD-based outlier detection, returns boolean mask
+- `apply_hard_threshold(adata, metric, threshold, operator='>', verbose=True)` - Apply hard cutoffs, returns boolean mask
+- `filter_cells(adata, mask, inplace=False)` - Apply boolean mask to filter cells
+- `filter_genes(adata, min_cells=20, min_counts=None, inplace=True)` - Filter genes by detection
+- `print_qc_summary(adata, label='')` - Print summary statistics
+
+From `qc_plotting.py` (visualization):
+- `plot_qc_distributions(adata, output_path, title)` - Generate comprehensive QC plots
+- `plot_filtering_thresholds(adata, outlier_masks, thresholds, output_path)` - Visualize filtering thresholds
+- `plot_qc_after_filtering(adata, output_path)` - Generate post-filtering plots
+
+**Example custom workflows:**
+
+**Example 1: Only calculate metrics and visualize, don't filter yet**
+```python
+adata = ad.read_h5ad('input.h5ad')
+calculate_qc_metrics(adata, inplace=True)
+plot_qc_distributions(adata, 'qc_before.png', title='Initial QC')
+print_qc_summary(adata, label='Before filtering')
+```
+
+**Example 2: Apply only MT% filtering, keep other metrics permissive**
+```python
+adata = ad.read_h5ad('input.h5ad')
+calculate_qc_metrics(adata, inplace=True)
+
+# Only filter high MT% cells
+high_mt = apply_hard_threshold(adata, 'pct_counts_mt', 10, operator='>')
+adata_filtered = filter_cells(adata, ~high_mt)
+adata_filtered.write('filtered.h5ad')
+```
+
+**Example 3: Different thresholds for different subsets**
+```python
+adata = ad.read_h5ad('input.h5ad')
+calculate_qc_metrics(adata, inplace=True)
+
+# Apply type-specific QC (assumes cell_type metadata exists)
+neurons = adata.obs['cell_type'] == 'neuron'
+other_cells = ~neurons
+
+# Neurons tolerate higher MT%, other cells use stricter threshold
+neuron_qc = apply_hard_threshold(adata[neurons], 'pct_counts_mt', 15, operator='>')
+other_qc = apply_hard_threshold(adata[other_cells], 'pct_counts_mt', 8, operator='>')
+```
+
+## Best Practices
+
+1. **Be permissive with filtering** - Default thresholds intentionally retain most cells to avoid losing rare populations
+2. **Inspect visualizations** - Always review before/after plots to ensure filtering makes biological sense
+3. **Consider dataset-specific factors** - Some tissues naturally have higher mitochondrial content (e.g., neurons, cardiomyocytes)
+4. **Check gene annotations** - Mitochondrial gene prefixes vary by species (mt- for mouse, MT- for human)
+5. **Iterate if needed** - QC parameters may need adjustment based on the specific experiment or tissue type
+
+## Reference Materials
+
+For detailed QC methodology, parameter rationale, and troubleshooting guidance, see `references/scverse_qc_guidelines.md`. This reference provides:
+- Detailed explanations of each QC metric and why it matters
+- Rationale for MAD-based thresholds and why they're better than fixed cutoffs
+- Guidelines for interpreting QC visualizations (histograms, violin plots, scatter plots)
+- Species-specific considerations for gene annotations
+- When and how to adjust filtering parameters
+- Advanced QC considerations (ambient RNA correction, doublet detection)
+
+Load this reference when users need deeper understanding of the methodology or when troubleshooting QC issues.
+
+## Next Steps After QC
+
+Typical downstream analysis steps:
+- Ambient RNA correction (SoupX, CellBender)
+- Doublet detection (scDblFinder)
+- Normalization (log-normalize, scran)
+- Feature selection and dimensionality reduction
+- Clustering and cell type annotation

package/skills/examples/single-cell-rna-qc/references/scverse_qc_guidelines.md

@@ -0,0 +1,186 @@
+# scverse Quality Control Guidelines
+
+This document provides detailed information about quality control best practices for single-cell RNA-seq data, following the scverse ecosystem recommendations.
+
+## Quality Control Metrics
+
+### Count Depth (Total Counts)
+- **What it measures**: Total number of UMI/reads per cell
+- **Why it matters**: Low count cells may be empty droplets, debris, or poorly captured cells
+- **Typical range**: 500-50,000 counts per cell (varies by protocol)
+- **Red flags**: Bimodal distributions may indicate mixing of high and low-quality cells
+
+### Gene Detection (Genes per Cell)
+- **What it measures**: Number of genes with at least 1 count
+- **Why it matters**: Strongly correlates with count depth; low values indicate poor capture
+- **Typical range**: 200-5,000 genes per cell
+- **Red flags**: Very low values (<200) suggest technical failures
+
+### Mitochondrial Content
+- **What it measures**: Percentage of counts from mitochondrial genes
+- **Why it matters**: High MT% indicates cell stress, apoptosis, or lysed cells
+- **Typical range**: <5% for most tissues, up to 10-15% for metabolically active cells
+- **Species-specific patterns**:
+  - Mouse: Genes start with 'mt-' (e.g., mt-Nd1, mt-Co1)
+  - Human: Genes start with 'MT-' (e.g., MT-ND1, MT-CO1)
+- **Context matters**: Some cell types (cardiomyocytes, neurons) naturally have higher MT content
+
+### Ribosomal Content
+- **What it measures**: Percentage of counts from ribosomal protein genes
+- **Why it matters**: Can indicate cell state or contamination
+- **Patterns**: Genes start with 'Rpl'/'RPL' (large subunit) or 'Rps'/'RPS' (small subunit)
+- **Note**: High ribosomal content isn't always bad - metabolically active cells have more ribosomes
+
+### Hemoglobin Content
+- **What it measures**: Percentage of counts from hemoglobin genes
+- **Why it matters**: Indicates blood contamination in non-blood tissues
+- **Patterns**: Genes matching '^Hb[^(p)]' or '^HB[^(P)]' (excludes Hbp1/HBP1)
+- **When to use**: Particularly important for tissue samples (brain, liver, etc.)
+
+## MAD-Based Filtering Rationale
+
+### Why MAD Instead of Fixed Thresholds?
+
+Fixed thresholds (e.g., "remove cells with <500 genes") fail because:
+- Different protocols yield different ranges
+- Different tissues have different characteristics
+- Different species have different gene counts
+- Fixed thresholds are arbitrary and not data-driven
+
+MAD (Median Absolute Deviation) is robust to outliers and adapts to your dataset:
+```
+MAD = median(|X - median(X)|)
+Outlier bounds = median ± n_MADs × MAD
+```
+
+### Recommended MAD Thresholds
+
+Following scverse best practices (deliberately permissive):
+
+**5 MADs for count depth (log-transformed)**
+- Very permissive to retain rare cell populations
+- Catches extreme outliers (empty droplets, debris)
+- Log transformation handles the typical right-skewed distribution
+
+**5 MADs for gene counts (log-transformed)**
+- Parallels count depth filtering
+- Most informative when combined with count filtering
+- Log transformation normalizes the distribution
+
+**3 MADs for mitochondrial percentage**
+- More stringent because high MT% strongly indicates dying cells
+- Uses raw percentages (not log-transformed)
+- Combined with hard threshold for extra stringency
+
+**Hard threshold: 8% mitochondrial content**
+- Additional filter beyond MAD-based detection
+- Conservative cutoff that works across most tissues
+- Adjust higher (10-15%) for metabolically active cell types
+
+### Why Be Permissive?
+
+The default thresholds intentionally err on the side of keeping cells because:
+1. **Rare populations**: Stringent filtering may remove rare but viable cell types
+2. **Biological variation**: Some healthy cells naturally have extreme values
+3. **Reversibility**: Easier to filter more later than to recover lost cells
+4. **Downstream robustness**: Modern normalization methods handle moderate quality variation
+
+## Interpreting QC Visualizations
+
+### Histograms
+- **Bimodal distributions**: May indicate mixing of cell types or quality issues
+- **Long tails**: Common for count depth; MAD filtering handles this
+- **Sharp cutoffs**: May indicate prior filtering or technical artifacts
+
+### Violin Plots
+- Shows distribution shape and density
+- Median (line) and mean (diamond) should be similar for symmetric distributions
+- Wide distributions suggest high heterogeneity
+
+### Scatter Plots
+
+**Counts vs Genes (colored by MT%)**
+- Should show strong positive correlation (R² > 0.8 typical)
+- Points deviating from trend may be outliers
+- High MT% cells often cluster at low counts/genes
+
+**Counts vs MT%**
+- Negative correlation expected (dying cells have fewer counts)
+- Vertical stratification may indicate batch effects
+- Cells with high counts + high MT% are suspicious
+
+**Genes vs MT%**
+- Similar to counts vs MT%, but often weaker correlation
+- Useful for identifying cells with gene detection issues
+
+## Gene Filtering
+
+After filtering cells, remove genes detected in fewer than 20 cells:
+- **Why 20?**: Balances noise reduction with information retention
+- **Benefits**: Reduces dataset size, speeds up computation, removes noisy genes
+- **Trade-offs**: May lose very rare markers; adjust to 10 if studying rare populations
+
+## Species-Specific Considerations
+
+### Mouse (Mus musculus)
+- Mitochondrial genes: mt-* (lowercase)
+- Ribosomal genes: Rpl*, Rps* (capitalized first letter)
+- Hemoglobin genes: Hb* (but not Hbp1)
+
+### Human (Homo sapiens)
+- Mitochondrial genes: MT-* (uppercase)
+- Ribosomal genes: RPL*, RPS* (all uppercase)
+- Hemoglobin genes: HB* (but not HBP1)
+
+### Other Species
+Adjust gene name patterns in the script to match your organism's gene nomenclature. Consult Ensembl or your reference annotation for correct prefixes.
+
+## When to Adjust Parameters
+
+Consider adjusting filtering thresholds when:
+
+**More stringent (lower MADs)**
+- High ambient RNA contamination suspected
+- Many low-quality cells observed in visualizations
+- Downstream analysis shows quality-driven clustering
+
+**More permissive (higher MADs)**
+- Studying rare cell populations
+- Dataset has high technical quality
+- Cell types naturally have extreme values (e.g., neurons with high MT%)
+
+**Tissue-specific adjustments**
+- Brain/neurons: May need higher MT% threshold (10-15%)
+- Blood: Can be more stringent with MT% (5-8%)
+- Tumor samples: Often need more permissive thresholds due to biological variation
+
+## Advanced QC Considerations
+
+### Not Included in This Workflow
+
+**Ambient RNA correction**
+- Tool: SoupX, CellBender, DecontX
+- When: High background RNA in droplet-based data
+- Effect: Removes contamination from lysed cells
+
+**Doublet detection**
+- Tool: scDblFinder, scrublet, DoubletFinder
+- When: Always recommended for droplet-based data
+- Effect: Identifies and removes multiplets (2+ cells in one droplet)
+
+**Cell cycle scoring**
+- Tool: scanpy's score_genes_cell_cycle
+- When: Cell cycle effects confound biological signal
+- Effect: Allows regressing out or accounting for cell cycle phase
+
+**Batch correction**
+- Tool: Harmony, scVI, ComBat
+- When: Integrating data from multiple batches/experiments
+- Effect: Removes technical batch effects while preserving biology
+
+## References
+
+- scverse Best Practices: https://www.sc-best-practices.org/preprocessing_visualization/quality_control.html
+- Luecken & Theis (2019): Current best practices in single-cell RNA-seq analysis
+- Osorio & Cai (2021): Systematic determination of the mitochondrial proportion in human and mouse genomes
+- Germain et al. (2020): Doublet identification in single-cell sequencing data using scDblFinder