Analytics Project README Template

# [Project name]

[One sentence: the decision this project supports and the result it produces.]

## Business question

- **Decision owner:** [Who uses this work?]
- **Question:** [What decision or recurring workflow does this analysis support?]
- **Output grain:** [What does one row in the final output represent?]
- **Reporting period:** [Coverage dates and timezone]

## Executive summary

[Write 3–5 sentences. State the checked result, the most important limitation, and the recommended next action. Do not describe a synthetic pattern as a real business benchmark.]

## Data

| Source | Grain | Coverage | Important limitations |
|---|---|---|---|
| [source.table] | [one row per…] | [date range] | [missing history, synthetic data, sampling, etc.] |

### Relationships

[Add a small lineage or relationship diagram. Label one-to-many relationships and the key used on each side.]

## Metric definitions

### [Metric name]

- **Business meaning:** [Plain-language definition]
- **Population:** [Included entities/events]
- **Formula:** [Numerator / denominator or aggregation]
- **Date rule:** [Which timestamp assigns the reporting period?]
- **Exclusions:** [Statuses, test records, cancellations, etc.]
- **Units:** [USD, customers, percentage points, days, etc.]

## Model and approach

1. **Staging:** [Renames, types, source cleanup]
2. **Intermediate:** [Reusable joins or event logic]
3. **Facts and dimensions:** [Declared grain and keys]
4. **Serving output:** [Final mart, report, notebook, or dashboard]

### Defended decision

[Explain one trade-off. What alternatives did you consider, what evidence changed the decision, and what consequence remains?]

## Validation

- [ ] Final key is unique at the declared grain.
- [ ] Required keys and fields are not null.
- [ ] Relationships have no unexpected orphan records.
- [ ] Important totals reconcile to a simpler source query.
- [ ] Row counts were checked before and after one-to-many joins.
- [ ] A small example was calculated independently.
- [ ] Ties, zero-activity entities, late records, and cancellations were reviewed where relevant.

## Result

[Show the smallest useful table or chart. Include units, filters, coverage dates, and the dataset/model version.]

## Limitations

- [What can this result not establish?]
- [Which source limitation could change the interpretation?]
- [What additional evidence would you request?]

## Repository map

```text
.
├── README.md
├── models/          # or sql/
├── analyses/        # checks and one-off validation
├── tests/
├── docs/
└── outputs/         # reproducible tables/charts, not private raw data
```

## Reproduce the work

### Requirements

- [Tool and tested version]
- [Required packages]
- [Safe sample data or documented source access]

### Run

```bash
[exact setup command]
[exact build/test command]
[exact output command]
```

## Changes and ownership

- **Owner:** [Name or team]
- **Last checked:** [YYYY-MM-DD]
- **Version:** [dataset/model/release version]
- **Change process:** [How definitions and breaking changes are reviewed]