---
epic: 5
story: 5.5
title: "Subtotals & Grand Total"
status: draft
---

## Epic 5 — Variables, Line References & Aggregators
**Goal:** Transform the notepad into a lightweight computational document.

### Story 5.5: Subtotals & Grand Total

As a **CalcPad user**,
I want subtotal lines scoped to their respective sections and a grand total that sums all subtotals,
So that I can build structured documents like budgets with section summaries and an overall total.

**Acceptance Criteria:**

**Given** a sheet with two sections, each ending with a `subtotal` line
**When** the engine evaluates the sheet
**Then** each `subtotal` computes the sum of numeric lines in its own section only (not lines from other sections)

**Given** Section A has values `100`, `200` (subtotal = `300`) and Section B has values `50`, `75` (subtotal = `125`)
**When** the user writes `grand total` after both sections
**Then** the result is `425` (the sum of all subtotal lines: `300 + 125`)

**Given** a sheet with three sections, each with a `subtotal`
**When** the user adds a fourth section with its own `subtotal`
**Then** `grand total` at the bottom automatically includes the new subtotal in its sum

**Given** a subtotal line exists but its section has no numeric lines
**When** the engine evaluates
**Then** the subtotal is `0`
**And** the grand total still includes this `0` subtotal without error

**Given** a section uses `total` instead of `subtotal`
**When** a `grand total` line appears later
**Then** `grand total` sums all `subtotal` lines specifically (it does not include `total` lines unless they are explicitly subtotal-scoped; the distinction should be clearly documented)

**Given** a user writes multiple `subtotal` lines within the same section
**When** the engine evaluates
**Then** each `subtotal` line sums the lines above it within its section scope, and `grand total` sums all subtotal lines in the document