Skip to content

DAAF-Contribution-Community/daaf / .claude/skills/data-scientist

data-scientist

Verified

Data science methodology and method-selection routing for quantitative research. Covers EDA, data validation, descriptive analysis, causal inference (IV, DiD, RD, synthetic control), clustering/PCA/UMAP, supervised ML, geospatial analysis, network analysis, and visualization design. Contains the canonical method-to-library routing tree, routed by execution language — Python: statsmodels (OLS/GLM/time series), pyfixest (FE/IV/DiD), linearmodels (RE/GMM/SUR), svy (complex surveys), scikit-learn (clustering/prediction ML), geopandas (spatial), igraph (network analysis); R: r-stats (OLS/GLM/time series), fixest (FE/IV/DiD), plm (panel RE/between, dynamic GMM), survey-r (complex surveys), tidymodels (ML), sf-terra (spatial), igraph-r (network analysis). Load the routed tool-specific skill before giving tool-specific advice or writing code — library skills encode environment constraints and curated caveats absent from general knowledge.

references/code-documentation.md

View on GitHub
# Code Documentation

Writing thorough comments and documentation for data science code.

## Contents

- [Comment Philosophy](#comment-philosophy)
- [What to Document](#what-to-document)
- [Docstring Patterns](#docstring-patterns)
- [Marimo Cell Documentation](#marimo-cell-documentation)
- [Test Documentation](#test-documentation)
- [Documentation Examples](#documentation-examples)

## Comment Philosophy

### The Core Principle

**Code tells you HOW. Comments tell you WHY, WHAT FOR, and WHAT'S ASSUMED.**

In research workflows, the standard is the **Inline Audit Trail (IAT)** -- see `agent_reference/INLINE_AUDIT_TRAIL.md` for the full specification.

Good comments explain:
- Why this approach was chosen over alternatives
- Why specific values or thresholds were selected
- Why edge cases are handled a particular way
- What business logic or domain knowledge informed the decision

Bad comments explain:
- What the code literally does (the code already shows this)
- Obvious operations (`# increment i by 1`)

### When to Be Verbose

**For research scripts (Stages 5-8): Be verbose ALWAYS.** The IAT standard applies to all research code. Every transformation, filter, join, and aggregation needs INTENT, REASONING, and ASSUMES comments.

Be MORE verbose when:
- Business logic is encoded
- Domain knowledge is required to understand
- Non-obvious decisions were made
- Assumptions are being made about the data
- Edge cases require special handling
- The operation is complex or multi-step
- Future maintainers need context

Be LESS verbose when (non-research code only):
- Code is self-explanatory
- Using well-known library patterns
- Operations are trivial

### Data Science Specific Guidance

Data science code should be MORE documented than typical code because:
- Analytical decisions have significant downstream impact
- Assumptions need to be explicit for reproducibility
- Domain expertise may be needed to understand choices
- Data quality issues need to be documented
- Statistical methodology should be explained

## What to Document

### For Every Code Block

1. **INTENT**: What are you trying to accomplish?
2. **REASONING**: Why this method vs. alternatives?
3. **ASSUMES**: What must be true for this to work?
4. **EXPECTED RESULT**: What should the output look like?

### For Data Operations

**Python:**
```python
# ================================================================
# INTENT: Filter to customers with valid purchase history
# 
# REASONING: Require at least one purchase in the last 365 days.
# We chose 365 days (vs. 90 or 180) because seasonal customers
# (e.g., holiday-only shoppers) are still valuable for this analysis.
#
# ASSUMES:
# - 'last_purchase_date' is populated for all customers with purchases
# - Customers with NULL last_purchase_date have never purchased
#
# EXPECTED: ~60% of customers retained (based on historical pattern)
# ================================================================
active_customers = customers.filter(
    pl.col("last_purchase_date") >= cutoff_date
)

# Verify expectation
retention_rate = len(active_customers) / len(customers) * 100
print(f"Retained {retention_rate:.1f}% of customers")
# If this is far from 60%, investigate before proceeding
```

**R:**
```r
# ================================================================
# INTENT: Filter to customers with valid purchase history
# 
# REASONING: Require at least one purchase in the last 365 days.
# We chose 365 days (vs. 90 or 180) because seasonal customers
# (e.g., holiday-only shoppers) are still valuable for this analysis.
#
# ASSUMES:
# - 'last_purchase_date' is populated for all customers with purchases
# - Customers with NA last_purchase_date have never purchased
#
# EXPECTED: ~60% of customers retained (based on historical pattern)
# ================================================================
active_customers <- customers |>
  filter(last_purchase_date >= cutoff_date)

# Verify expectation
retention_rate <- nrow(active_customers) / nrow(customers) * 100
cat(sprintf("Retained %.1f%% of customers\n", retention_rate))
# If this is far from 60%, investigate before proceeding
```

### For Statistical Operations

**Python:**
```python
# ================================================================
# INTENT: Handle outliers in transaction amounts
#
# REASONING: Winsorization at 1st and 99th percentiles
#
# WHY WINSORIZE vs. REMOVE:
# - Removing outliers loses data and may bias toward "normal" transactions
# - Winsorizing preserves row count while reducing outlier influence
# - 1st/99th percentiles chosen to affect only extreme values (~2% of data)
#
# WHY NOT LOG TRANSFORM:
# - Need to preserve original scale for business interpretation
# - Log transform would complicate downstream aggregations
#
# ASSUMES: Outliers are measurement/entry errors, not real events
# (Verified: extreme values correspond to known data quality issues)
# ================================================================
p01 = df["amount"].quantile(0.01)
p99 = df["amount"].quantile(0.99)

df = df.with_columns(
    pl.col("amount").clip(p01, p99).alias("amount_winsorized")
)
```

**R:**
```r
# ================================================================
# INTENT: Handle outliers in transaction amounts
#
# REASONING: Winsorization at 1st and 99th percentiles
#
# WHY WINSORIZE vs. REMOVE:
# - Removing outliers loses data and may bias toward "normal" transactions
# - Winsorizing preserves row count while reducing outlier influence
# - 1st/99th percentiles chosen to affect only extreme values (~2% of data)
#
# WHY NOT LOG TRANSFORM:
# - Need to preserve original scale for business interpretation
# - Log transform would complicate downstream aggregations
#
# ASSUMES: Outliers are measurement/entry errors, not real events
# (Verified: extreme values correspond to known data quality issues)
# ================================================================
p01 <- quantile(df$amount, 0.01, na.rm = TRUE)
p99 <- quantile(df$amount, 0.99, na.rm = TRUE)

df <- df |>
  mutate(amount_winsorized = pmin(pmax(amount, p01), p99))
```

### For Joins and Merges

**Python:**
```python
# ================================================================
# INTENT: Enrich orders with customer demographic data
#
# REASONING: Left join (not inner) on customer_id
# - Keep all orders even if customer demographics missing
# - Missing demographics will be analyzed separately
#
# ASSUMES:
# - customer_id is unique in the customers table (verified; the join is many:1, many orders per customer)
# - Some orders may have customer_id not in customers table (new customers)
#
# EXPECTED RESULT:
# - Same row count as orders (left join preserves all left rows)
# - Additional columns from customers added
# - Some NULL values in customer columns where no match
# ================================================================
enriched_orders = orders.join(
    customers.select(["customer_id", "age_group", "region", "tenure_months"]),
    on="customer_id",
    how="left"
)

# Verify: row count unchanged
assert len(enriched_orders) == len(orders), "Unexpected row count change after join"

# Document match rate
match_rate = enriched_orders["age_group"].drop_nulls().len() / len(enriched_orders) * 100
print(f"Customer match rate: {match_rate:.1f}%")
```

**R:**
```r
# ================================================================
# INTENT: Enrich orders with customer demographic data
#
# REASONING: Left join (not inner) on customer_id
# - Keep all orders even if customer demographics missing
# - Missing demographics will be analyzed separately
#
# ASSUMES:
# - customer_id is unique in the customers table (verified; the join is many:1, many orders per customer)
# - Some orders may have customer_id not in customers table (new customers)
#
# EXPECTED RESULT:
# - Same row count as orders (left join preserves all left rows)
# - Additional columns from customers added
# - Some NA values in customer columns where no match
# ================================================================
enriched_orders <- orders |>
  left_join(
    customers |> select(customer_id, age_group, region, tenure_months),
    by = "customer_id"
  )

# Verify: row count unchanged
stopifnot("Unexpected row count change after join" = nrow(enriched_orders) == nrow(orders))

# Document match rate
match_rate <- sum(!is.na(enriched_orders$age_group)) / nrow(enriched_orders) * 100
cat(sprintf("Customer match rate: %.1f%%\n", match_rate))
```

## Docstring Patterns

> **Note for research scripts:** Formal docstrings are valuable for reusable utility functions
> (e.g., `fetch_all_pages`, `apply_coded_values`). For one-and-done script code, inline comments
> explaining the "why" are sufficient -- you do not need full NumPy-style docstrings on every block.

### Function Docstrings (for reusable utilities)

**Python:**
```python
def calculate_customer_lifetime_value(
    transactions: pl.DataFrame,
    customer_id_col: str = "customer_id",
    amount_col: str = "amount",
    date_col: str = "transaction_date",
) -> pl.DataFrame:
    """
    Calculate customer lifetime value (CLV) using historical transaction data.
    
    Uses a simple historical CLV model: total past spend per customer.
    For predictive CLV, consider BG/NBD or Pareto/NBD models.
    
    Parameters
    ----------
    transactions : pl.DataFrame
        Transaction-level data with customer ID, amount, and date.
    customer_id_col : str
        Name of customer identifier column.
    amount_col : str
        Name of transaction amount column (should be in consistent currency).
    date_col : str
        Name of transaction date column.
    
    Returns
    -------
    pl.DataFrame
        Customer-level DataFrame with columns:
        - customer_id: Customer identifier
        - total_spend: Sum of all transaction amounts
        - transaction_count: Number of transactions
        - first_purchase: Date of first transaction
        - last_purchase: Date of most recent transaction
        - tenure_days: Days between first and last purchase
    
    Assumptions
    -----------
    - Transactions are deduplicated (no duplicate transaction records)
    - Amounts are in consistent currency (no currency conversion needed)
    - Negative amounts represent refunds/returns
    
    Example
    -------
    >>> clv = calculate_customer_lifetime_value(transactions)
    >>> print(clv.head())
    """
```

**R (roxygen2-style documentation for reusable functions):**
```r
#' Calculate customer lifetime value (CLV) using historical transaction data.
#'
#' Uses a simple historical CLV model: total past spend per customer.
#' For predictive CLV, consider BG/NBD or Pareto/NBD models.
#'
#' @param transactions Data frame with transaction-level data.
#' @param customer_id_col Name of customer identifier column.
#' @param amount_col Name of transaction amount column (consistent currency).
#' @param date_col Name of transaction date column.
#' @return Data frame with columns: customer_id, total_spend,
#'   transaction_count, first_purchase, last_purchase, tenure_days.
#' @details
#' Assumptions:
#' - Transactions are deduplicated (no duplicate transaction records)
#' - Amounts are in consistent currency (no currency conversion needed)
#' - Negative amounts represent refunds/returns
#' @examples
#' clv <- calculate_customer_lifetime_value(transactions)
#' head(clv)

# Note: In DAAF research scripts, prefer inline sequential code over
# function definitions. Roxygen2 documentation is shown here as
# reference for the rare cases where reusable functions are needed.
```

### Data Validation (Inline Approach)

For research scripts, validate data inline rather than building validator classes:

**Python:**
```python
# Validate directly where you use the data
assert df["id"].null_count() == 0, "IDs must not be null"
assert df.select("id", "year").n_unique() == len(df), "id+year must be unique"
# State FIPS: 1-56 skips 3, 7, 14, 43, 52 (Census state list); add 60, 66, 69, 72, 74, 78 if territories belong
valid_states = set(range(1, 57)) - {3, 7, 14, 43, 52}  # 50 states + DC
invalid = set(df["fips"].unique().to_list()) - valid_states
assert not invalid, f"Invalid FIPS codes: {invalid}"
```

**R:**
```r
# Validate directly where you use the data
stopifnot("IDs must not be null" = !any(is.na(df$id)))
stopifnot("id+year must be unique" = nrow(distinct(df, id, year)) == nrow(df))
# State FIPS: 1-56 skips 3, 7, 14, 43, 52 (Census state list); add 60, 66, 69, 72, 74, 78 if territories belong
valid_states <- setdiff(1:56, c(3, 7, 14, 43, 52))  # 50 states + DC
invalid <- setdiff(unique(df$fips), valid_states)
stopifnot("Invalid FIPS codes found" = length(invalid) == 0)
```

## Marimo Cell Documentation

The patterns in this section are for **standalone marimo apps** (an exploratory or diagnostic app built on request), not Stage 9 notebooks. A Stage 9 notebook computes nothing: it archives the executed Stage 5-8 scripts with their execution logs and may add only a bounded preview of an existing Parquet file or an already-created figure (`marimo` skill § Stage 9 Notebook Assembly and § ABSOLUTE PROHIBITIONS for Stage 9; assembled by the `notebook-assembler` agent). In a standalone app too, prefer showing results an executed script already saved over computing new ones in a cell, so the numbers keep their audit trail.

### Cell Organization Pattern

Standalone-app example: Cell 4 computes inside the notebook, which a Stage 9 notebook never does.

```python
# Cell 1: Setup (minimal documentation needed)
import marimo as mo
import polars as pl

# Cell 2: Data Loading (document source)
# ================================================================
# DATA SOURCE: Customer transactions from DW export
# EXPORTED: 2024-01-15
# COVERAGE: All transactions from 2023-01-01 to 2023-12-31
# KNOWN ISSUES: December data may be incomplete (export ran early)
# ================================================================
transactions = pl.read_parquet("transactions_2023.parquet")

# Cell 3: Markdown explanation before analysis
mo.md("""
## Data Quality Assessment

Before analyzing customer behavior, we need to assess the quality of our 
transaction data. Key questions:

1. **Completeness**: Are there missing values in critical fields?
2. **Validity**: Are transaction amounts and dates reasonable?
3. **Consistency**: Do customer IDs match across systems?

The following cells examine each of these dimensions.
""")

# Cell 4: Analysis with inline comments (standalone app only, never Stage 9)
# Check for missing values in critical columns
# Critical = columns that would invalidate the transaction if missing
critical_columns = ["transaction_id", "customer_id", "amount", "transaction_date"]

missing_summary = transactions.select([
    pl.col(col).null_count().alias(f"{col}_missing")
    for col in critical_columns
])

mo.md(f"""
### Missing Values in Critical Fields

{missing_summary}

**Interpretation**: [Add interpretation of what the missing values mean]
""")
```

> **R:** DAAF's Stage 9 notebook format for R is Quarto (.qmd), and a Stage 9 Quarto notebook follows the `quarto` skill's archive rules (§ CRITICAL: Stage 9 is Script COMPILATION, Not Report Authoring, and `references/daaf-notebook.md`), not this section. For a standalone Quarto document outside Stage 9, the same documentation principles apply as for a standalone marimo app: markdown for narrative context, code chunk comments for technical detail.

### When to Use Markdown Cells

Use `mo.md()` cells for:
- Section headers and transitions
- Explaining the analytical approach BEFORE the code
- Summarizing findings AFTER the code
- Documenting decisions and their rationale
- Providing business context

Keep in code comments:
- Technical implementation details
- Line-by-line explanations
- Assumptions specific to that code block

### Reactive Validation Documentation

> Interactive widgets such as `mo.ui.dropdown` belong only in standalone marimo apps, never in Stage 9 notebooks (`marimo` skill § ABSOLUTE PROHIBITIONS for Stage 9).

```python
# Standalone app only, never Stage 9: this cell computes on each selection
# Interactive column selector for exploration
# Purpose: Allow user to quickly inspect any column's distribution
column_selector = mo.ui.dropdown(
    options=df.columns,
    value=df.columns[0],
    label="Select column to inspect"
)

# This cell reacts to column_selector changes
# Automatically updates when user selects different column
mo.md(f"""
### Column: `{column_selector.value}`

- **Type**: {df[column_selector.value].dtype}
- **Null count**: {df[column_selector.value].null_count()}
- **Unique values**: {df[column_selector.value].n_unique()}

**Sample values**: {df[column_selector.value].unique().head(10).to_list()}
""")
```

## Test Documentation

### Validating Transformations

Instead of writing separate test files, validate transformations inline within the script that performs them:

**Python:**
```python
# Before aggregation
pre_total = transactions["amount"].sum()

# Aggregate
customer_summary = (
    transactions
    .group_by("customer_id")
    .agg(pl.col("amount").sum().alias("total_spend"))
)

# Validate immediately
post_total = customer_summary["total_spend"].sum()
print(f"Total spend preserved: {pre_total:,.2f} → {post_total:,.2f}")
# Relative tolerance: float sums differ in the last bits after regrouping
tol = 1e-12 * max(1.0, transactions["amount"].abs().sum())
assert abs(pre_total - post_total) <= tol, "STOP: Total spend changed during aggregation"
```

**R:**
```r
# Before aggregation
pre_total <- sum(transactions$amount, na.rm = TRUE)

# Aggregate
customer_summary <- transactions |>
  group_by(customer_id) |>
  summarise(total_spend = sum(amount, na.rm = TRUE), .groups = "drop")

# Validate immediately
post_total <- sum(customer_summary$total_spend, na.rm = TRUE)
cat(sprintf("Total spend preserved: %s -> %s\n",
            format(pre_total, big.mark = ",", nsmall = 2),
            format(post_total, big.mark = ",", nsmall = 2)))
# Relative tolerance: float sums differ in the last bits after regrouping
tol <- 1e-12 * max(1, sum(abs(transactions$amount), na.rm = TRUE))
stopifnot("STOP: Total spend changed during aggregation" = abs(pre_total - post_total) <= tol)
```

## Documentation Examples

### Good vs. Bad Examples

**Bad: Stating the obvious**

**Python:**
```python
# Loop through customers
for customer in customers.iter_rows(named=True):
    # Get customer id
    customer_id = customer["id"]
    # Filter transactions for this customer
    customer_transactions = transactions.filter(pl.col("customer_id") == customer_id)
```

**R:**
```r
# Loop through customers
for (i in seq_len(nrow(customers))) {
  # Get customer id
  customer_id <- customers$id[i]
  # Filter transactions for this customer
  customer_transactions <- transactions |> filter(customer_id == !!customer_id)
}
```

**Good: Explaining the why**

**Python:**
```python
# Process customers individually rather than in a single groupby because:
# 1. Memory constraints: full aggregation exceeds available RAM
# 2. Partial results: we want to checkpoint progress every 1000 customers
# 3. Custom logic: per-customer CLV model requires sequential processing
for customer in customers.iter_rows(named=True):
    customer_id = customer["id"]
    customer_transactions = transactions.filter(pl.col("customer_id") == customer_id)
```

**R:**
```r
# Process customers individually rather than in a single group_by because:
# 1. Memory constraints: full aggregation exceeds available RAM
# 2. Partial results: we want to checkpoint progress every 1000 customers
# 3. Custom logic: per-customer CLV model requires sequential processing
for (i in seq_len(nrow(customers))) {
  customer_id <- customers$id[i]
  customer_transactions <- transactions |> filter(customer_id == !!customer_id)
}
```

**Bad: No context**

**Python:**
```python
df = df.filter(pl.col("amount") > 0)
```

**R:**
```r
df <- df |> filter(amount > 0)
```

**Good: Business context**

**Python:**
```python
# Remove zero and negative amounts
# - Zero amounts are placeholder records created by legacy system (confirmed with IT)
# - Negative amounts are handled separately in refund analysis
# - This filter removes ~2% of records (validated against expectation)
df = df.filter(pl.col("amount") > 0)
print(f"Removed {original_count - len(df)} non-positive amount records")
```

**R:**
```r
# Remove zero and negative amounts
# - Zero amounts are placeholder records created by legacy system (confirmed with IT)
# - Negative amounts are handled separately in refund analysis
# - This filter removes ~2% of records (validated against expectation)
df <- df |> filter(amount > 0)
cat(sprintf("Removed %d non-positive amount records\n", original_count - nrow(df)))
```

### Full Analysis Block Example

**Python:**
```python
# ============================================================================
# ANALYSIS: Customer Segmentation by Purchase Frequency
# ============================================================================
# 
# INTENT: Segment customers into frequency tiers for targeted marketing
#
# REASONING:
# - Calculate purchase frequency (orders per month) for each customer
# - Segment into quartiles: Low, Medium, High, Very High frequency
# - Quartiles chosen over fixed thresholds because:
#   - Adapts to changes in overall customer behavior
#   - Ensures balanced segment sizes for marketing capacity
#   - Standard approach aligns with previous analyses
#
# ASSUMES:
# - Only counting orders with status='complete' (not cancelled/pending)
# - Using 12-month lookback window to smooth seasonality
# - New customers (<3 months tenure) excluded (not enough history)
#
# EXPECTED OUTPUT:
# - Customer-level DataFrame with frequency tier assignment
# - Approximately 25% of customers in each tier
# ============================================================================

# Calculate monthly order frequency
customer_frequency = (
    orders
    .filter(
        (pl.col("status") == "complete") &  # Only completed orders
        (pl.col("order_date") >= twelve_months_ago)  # 12-month window
    )
    .group_by("customer_id")
    .agg([
        pl.len().alias("order_count"),
        (pl.col("order_date").max() - pl.col("order_date").min()).dt.total_days().alias("active_days")
    ])
    .with_columns(
        # Orders per 30-day month
        (pl.col("order_count") / (pl.col("active_days") / 30)).alias("monthly_frequency")
    )
    .filter(pl.col("active_days") >= 90)  # Minimum 3 months history
)

# Assign quartile-based segments
# Manual quantile cut-points (Series.qcut also exists)
q25 = customer_frequency["monthly_frequency"].quantile(0.25)
q50 = customer_frequency["monthly_frequency"].quantile(0.50)
q75 = customer_frequency["monthly_frequency"].quantile(0.75)

customer_frequency = customer_frequency.with_columns(
    pl.when(pl.col("monthly_frequency") <= q25).then(pl.lit("Low"))
    .when(pl.col("monthly_frequency") <= q50).then(pl.lit("Medium"))
    .when(pl.col("monthly_frequency") <= q75).then(pl.lit("High"))
    .otherwise(pl.lit("Very High"))
    .alias("frequency_tier")
)

# Validate segment distribution
segment_distribution = customer_frequency["frequency_tier"].value_counts()
print("Segment distribution:")
print(segment_distribution)
# Expected: each tier ~25% of customers
```

**R:**
```r
# ============================================================================
# ANALYSIS: Customer Segmentation by Purchase Frequency
# ============================================================================
# 
# INTENT: Segment customers into frequency tiers for targeted marketing
#
# REASONING:
# - Calculate purchase frequency (orders per month) for each customer
# - Segment into quartiles: Low, Medium, High, Very High frequency
# - Quartiles chosen over fixed thresholds because:
#   - Adapts to changes in overall customer behavior
#   - Ensures balanced segment sizes for marketing capacity
#   - Standard approach aligns with previous analyses
#
# ASSUMES:
# - Only counting orders with status='complete' (not cancelled/pending)
# - Using 12-month lookback window to smooth seasonality
# - New customers (<3 months tenure) excluded (not enough history)
#
# EXPECTED OUTPUT:
# - Customer-level data frame with frequency tier assignment
# - Approximately 25% of customers in each tier
# ============================================================================

# Calculate monthly order frequency
customer_frequency <- orders |>
  filter(
    status == "complete",               # Only completed orders
    order_date >= twelve_months_ago      # 12-month window
  ) |>
  group_by(customer_id) |>
  summarise(
    order_count = n(),
    active_days = as.numeric(difftime(max(order_date), min(order_date), units = "days")),
    .groups = "drop"
  ) |>
  mutate(
    # Orders per 30-day month
    monthly_frequency = order_count / (active_days / 30)
  ) |>
  filter(active_days >= 90)  # Minimum 3 months history

# Assign quartile-based segments
q25 <- quantile(customer_frequency$monthly_frequency, 0.25, na.rm = TRUE)
q50 <- quantile(customer_frequency$monthly_frequency, 0.50, na.rm = TRUE)
q75 <- quantile(customer_frequency$monthly_frequency, 0.75, na.rm = TRUE)

customer_frequency <- customer_frequency |>
  mutate(
    frequency_tier = case_when(
      monthly_frequency <= q25 ~ "Low",
      monthly_frequency <= q50 ~ "Medium",
      monthly_frequency <= q75 ~ "High",
      TRUE                     ~ "Very High"
    )
  )

# Validate segment distribution
segment_distribution <- customer_frequency |> count(frequency_tier, sort = TRUE)
cat("Segment distribution:\n")
print(segment_distribution)
# Expected: each tier ~25% of customers
```

---

## IAT Quick Reference

For research workflow scripts, follow the **Inline Audit Trail (IAT)** protocol. The full specification is in `agent_reference/INLINE_AUDIT_TRAIL.md`.

**5 Comment Types:**

| # | Type | Format | Required When |
|---|------|--------|---------------|
| 1 | Section Preamble | Block above `# --- Section ---` | Every section |
| 2 | Intent Comment | `# INTENT: ...` | Every transform, filter, join, agg |
| 3 | Reasoning Comment | `# REASONING: ...` | Non-obvious choices |
| 4 | Assumption Comment | `# ASSUMES: ...` | Data property dependencies |
| 5 | Inline Annotation | End-of-line `# ...` | Complex single operations |
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 321kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 197kUpdated Claude CodeCodexVerifiedInstall