Research Report Style Guide

Purpose

Research reports are deep-dive investigations into specific topics within the knowledge base. They serve two primary functions:

1. Comprehensive analysis of a topic with citations from authoritative sources
2. Input for diagram creation - reports inform the causal models in cause-effect diagrams

Reports are generated with AI assistance (Claude Code) using web research and synthesis of existing content.

Note: The research-reports section has been deprecated. Research content now lives in the relevant knowledge-base sections (risks/, responses/, etc.).

Formatting Guidelines

Use Tables Over Bullet Lists

Bad (low density):

**Factor Name**
- Direction: Increases → topic
- Type: leaf
- Evidence: Some evidence
- Confidence: high

Good (table format):

| Factor | Direction | Type | Evidence | Confidence |
|--------|-----------|------|----------|------------|
| **Factor Name** | ↑ Topic | leaf | Some evidence | High |

Use Callouts/Asides Liberally

Add <Aside> components to highlight key insights, caveats, and implications. Aim for at least 3-4 callouts per report.

<Aside type="tip" title="Why This Matters">
Key insight about safety implications.
</Aside>

<Aside type="caution" title="Limitation">
Important caveat about the data.
</Aside>

<Aside type="note" title="Data Source">
Methodological note about how data was collected.
</Aside>

Escape Dollar Signs

Currency values MUST be escaped to avoid LaTeX rendering:

Also escape in frontmatter description:

description: "H-1B fees increased to \\$100K"

Use Horizontal Rules

Separate major sections with --- for visual clarity.

Report Structure

Every research report should follow this structure:

---
title: "Topic Name: Research Report"
description: "One-sentence summary with specific data (escape \\$ signs)."
topic: "entity-id"           # Links to knowledge-base or transition-model item
createdAt: 2025-01-07        # Date without quotes (YAML date type)
lastUpdated: 2025-01-07      # Date without quotes (YAML date type)
researchDepth: "standard"    # quick | standard | comprehensive
sources: ["web", "codebase"] # What sources were consulted
quality: 3                   # 1-5 quality rating
---

Required Sections

Section Templates

Executive Summary (Table Format)

Use a table, not bullets:

## Executive Summary

| Finding | Key Data | Implication |
|---------|----------|-------------|
| **US dominance** | 57% of top researchers | US remains primary hub |
| **Policy risk** | \$100K H-1B fee | May accelerate brain drain |
| **Key uncertainty** | Immigration policy | Critical inflection point |

Causal Factors (Table Format)

## Causal Factors

### Primary Factors (Strong Influence)

| Factor | Direction | Type | Evidence | Confidence |
|--------|-----------|------|----------|------------|
| **Immigration Policy** | ↑↓ Concentration | leaf | 80% retention depends on visas | High |
| **Research Ecosystem** | ↑ Concentration | cause | 60% of top institutions in US | High |

### Secondary Factors (Medium Influence)

| Factor | Direction | Type | Evidence | Confidence |
|--------|-----------|------|----------|------------|
| **Graduate Programs** | ↑ Concentration | cause | 80% of students stay | Medium |

### Minor Factors (Weak Influence)

| Factor | Direction | Type | Evidence | Confidence |
|--------|-----------|------|----------|------------|
| **Nationalist Sentiment** | ↓ Mobility | leaf | Limited evidence | Low |

Column definitions:

• Factor: Short name (2-5 words)
• Direction: ↑ (increases), ↓ (decreases), ↑↓ (bidirectional), Mixed
• Type: leaf (external), cause (derived), intermediate (direct factor)
• Evidence: Brief summary with source reference
• Confidence: High, Medium, or Low

Open Questions (Table Format)

## Open Questions

<Aside type="note" title="Key Uncertainties">
These questions represent the highest-value areas for follow-up research.
</Aside>

| Question | Why It Matters | Current State |
|----------|----------------|---------------|
| **Will H-1B fees persist?** | \$100K changes economics | May face legal challenge |
| **Is China's surge sustainable?** | 47% share may be temporary | Depends on retention |

Research Methodology

Source Hierarchy

Research Depth Levels

Validation Checklist

Before marking a report complete, verify:

Run validators:

npm run crux -- validate compile
npm run crux -- validate unified --rules=dollar-signs

Quality Criteria

Integration with Diagrams

After a report is complete, the Causal Factors section can be directly converted to a causeEffectGraph:

Workflow:

1. Create report → Research and document findings
2. Extract factors → Format in tables
3. Create diagram → Use cause-effect-diagram skill
4. Link both → Report references diagram

File Location & Naming

Note: The research-reports directory has been removed. Research content should now be integrated into the appropriate knowledge-base sections (risks/, responses/, etc.).

Naming: Use kebab-case matching the topic entity ID:

• ai-talent-concentration.mdx
• algorithmic-progress.mdx
• compute-governance.mdx

Common Mistakes