report-writing

Report Writing

Produce reproducible, stakeholder-ready analysis reports that communicate findings honestly and lead to clear action.

Iron Law: NO CONCLUSIONS WITHOUT SUPPORTING EVIDENCE IN THE REPORT

Checklist

1. Audience check — who will read this? What decisions will they make?
2. Reproducibility header — code version, data snapshot, random seeds
3. Executive summary — answer + confidence + key caveat, in 3 sentences
4. Data section — what data was used, quality notes, limitations
5. Methods section — what was done (enough to reproduce)
6. Results section — findings with uncertainty (CIs, not just point estimates)
7. Limitations section — what this analysis CANNOT tell us
8. Recommendations section — concrete next actions with owners and timelines
9. Appendix — detailed tables, full code reference

Audience Check

Before writing, answer:

• Decision maker: Will read executive summary only? → 3-sentence summary must be self-contained
• Technical peer: Will replicate the analysis? → Methods must include all parameters
• Stakeholder: Needs to act on findings → Recommendations must be concrete and assigned

Adjust depth accordingly. Never write a 20-page report for a decision that can be summarized in 5 bullet points.

Report Template

# [Analysis Title]

**Date:** YYYY-MM-DD
**Analyst:** [name]
**Code version:** [git SHA]
**Data snapshot:** [date/version]
**Random seed:** 42
**Status:** DRAFT / FINAL

---

## Executive Summary

[Answer to the business question in one sentence.]
[Confidence level and key uncertainty in one sentence.]
[Recommended action in one sentence.]

---

## Business Context

[What decision does this analysis support?]
[What was the success criterion?]

---

## Data

| Dataset | Source | Date Range | Rows | Key Limitations |
|---|---|---|---|---|
| [name] | [source] | [range] | [count] | [limitation] |

Known data quality issues:
- [issue]: [impact on conclusions]

---

## Methods

[Describe what was done in enough detail to reproduce. Include:]
- Data preprocessing steps
- Feature engineering decisions
- Model(s) used and why
- Evaluation methodology (CV strategy, test set split date)
- Primary metric and why it was chosen

---

## Results

### Primary Metric
**[Metric Name]: [value] (95% CI: [lower, upper])**

[Is this better than the baseline? By how much? Is the improvement significant?]

### Secondary Metrics
| Metric | Value | Baseline | Improvement |
|---|---|---|---|
| [metric] | [value] | [baseline] | [delta] |

### Key Findings
1. **[Finding]:** [Evidence] — [implication]
2. **[Finding]:** [Evidence] — [implication]
3. **[Finding]:** [Evidence] — [implication]

---

## Limitations

Be explicit about what this analysis CANNOT tell us:

- **[Limitation]:** [Impact] — [What would be needed to address it]

Examples to always check:
- Correlation ≠ causation: if observational data, state it
- Temporal scope: findings may not hold for future time periods
- Population scope: if trained on a subset, may not generalize
- Missing data: imputation assumptions may affect conclusions

---

## Recommendations

| Action | Owner | Timeline | Expected Impact |
|---|---|---|---|
| [concrete action] | [person/team] | [date] | [measurable outcome] |

**Next analysis step:** [what should be done next, by whom]

---

## Appendix

### A. Full Metrics Table
[All computed metrics, not just the highlights]

### B. Confusion Matrix / Residual Plot
[Include actual plots or tables]

### C. Feature Importance
[Top 20 features with SHAP values]

### D. Code Reference
Full code: `[path/to/notebook or script]`