# Word-for-Word Resident Reading Audit

## Overall finding

The v0.3.9 report contains strong analysis, careful source boundaries, and many excellent plain-language passages. Its principal weakness is not a lack of information. It is that the resident is asked to absorb too many measures, time periods, technical qualifications, and raw evidence tables before a stable mental model has been built.

The v0.5.0 package therefore does not discard the technical work. It changes the reading contract:

1. Begin with seven questions a resident already has.
2. Show the FY2021–FY2025 Town budget and levy changes, the shorter household example, and the FY2024–FY2026 HWRSD member amount without claiming that one caused another.
3. Set out a controlled path and explain how confidence labels work.
4. Define seven essential terms before the first financial walk-down.
5. Teach Town budget, HWRSD, revenue, Proposition 2½, household impact, Town and District debt, reserves, and affordability in that order.
6. Preserve database columns, hashes, controls, long evidence tables, and source lineage in a linked technical appendix and a complete evidence map, after the resident has learned how the numbers connect.
7. Provide a complete financial-term glossary and real Wilbraham example for every financial concept intentionally used in the resident guide.
8. Use stacked bars to show the starting budget, net increase, and relative scale of the major positive movements while separately reconciling declines and presentation offsets.
9. End with a civic-orientation close: what residents can change or influence, what they cannot control directly, where attention matters most, and what future modules will explain.
10. Keep every HWRSD denominator visible: combined member share, capital allocation, Town-budget composition, levy scale comparison, and household bill are never treated as interchangeable.

## What the resident encountered, in the original displayed order

| Original section | What a non-financial resident is likely thinking | Word-level or sequencing problem | v0.5.0 treatment |
|---:|---|---|---|
| Opening QA banner | “Am I reading a correction notice or the actual report?” | The first visible message discusses token alignment and QA rather than the Town questions. There is no welcoming title immediately before it. | The primary file opens with a resident title, purpose, and clear path. Correction history remains in package documentation. |
| Metric-card wall | “Which of these 13 numbers matters first? Why do the years differ?” | Budget growth, levy growth, a private-property assessment, base tax, revenue, exclusions, debt, and open follow-ups appear before their relationships are taught. | Four relatable changes appear first. Each states its exact period, entity, denominator, and evidence type. Debt and follow-up counts wait until their teaching sections. |
| 1. Start here: definitions | “Why am I studying vocabulary before I know the questions?” | Several good definitions appear, but they precede the reader's motivation and omit many later terms. | Seven big questions come first. Seven essential definitions then establish the minimum path. Every later financial term links to the full glossary. |
| 2. Short version | “Is 20% the budget, the levy, or my bill?” | Five different conclusions are compressed together. “Serviceable” is used without a definition and may sound like an affordability endorsement. | Each major conclusion is assigned to its own question. The affordability language is narrowed: repayability evidence exists, but affordability is not yet determined. |
| 3. Why did the budget rise? | “Why are FY2021–FY2025 and FY2022–FY2026 both being used?” | The report presents a 17.1% window and then explains a 20.3% window. A provenance note interrupts the resident story. | The resident walk-down leads with the requested FY2021–FY2025 result: $48,322,189 to $56,595,042, an $8,272,853 or 17.1% increase. The 20.3% window is preserved inside a clearly labeled separate comparison. |
| 3. Driver table | “Do these percentages add to 100%? Is ‘general government’ Town Hall?” | The narrative correctly warns that the categories do not form a clean bridge, but the reader first has to understand why the movements exceed the net increase. | The Town guide retains every published FY2021–FY2025 movement and reconciles the offsets. The completed HWRSD walk-down then separately shows the seven District source categories and preserves their $1 source-total difference. |
| 4. $10,005,151 bridge | “This seems like the answer—why did I first read a different bridge?” | This is a precise normalized database bridge, but it answers a forward-shifted FY2022–FY2026 question. | It remains complete inside the separate-window disclosure, including category detail and source-total reconciliation. It does not displace the requested FY2021–FY2025 headline. |
| 5. Proposition 2½ concept | “I understand the words, but where are Wilbraham's numbers?” | The five-step table is conceptual. The actual FY2025 calculation appears six sections later. | The current FY2026 unused levy capacity of $1,322,755 appears first; a clearly labeled prior-year FY2025 calculation then walks from $44.893 million through $986,000 of unused levy capacity. |
| 5. Working formula | “Why doesn't the formula add up exactly when I use the displayed numbers?” | Source values are rounded to thousands, but the rounding consequence is not adjacent to the formula. | A rounding note immediately follows the calculation and explains possible $1,000 differences. |
| 5. Limit terminology | “Is the levy ceiling the same as the levy limit?” | The report later distinguishes them, but the similar labels are easy to merge mentally. | The $66.187 million statutory ceiling and $48.323 million operative limit are displayed side by side and explicitly defined as different measures. |
| 6. Five-year story | “Haven't I already read these changes twice?” | The section repeats budget and levy changes after the earlier budget and Proposition 2½ sections. | The material is absorbed into the opening change cards and the relevant walk-downs. No separate repeat section is needed. |
| 7. 481 Main Street | “Is this supposed to be a typical home? Why is a private address in the public story?” | The source boundary is careful, but the named address can distract from the lesson and invite an assumption of typicality. | The resident guide uses “Susan's example home,” prominently says it is one real example rather than a median, and keeps the source account in technical evidence. |
| 7. Household calculation | “What exactly is excluded from the estimated bill?” | The exclusions are in a long boundary paragraph after the main result. | The assessment × rate ÷ 1,000 formula is shown first. CPA, exemptions, abatements, betterments, timing, and the missing FY2026 rate are placed in an adjacent warning. |
| 8. Operating resources | “Do I need to read 90 rows to understand the budget?” | The first very large technical table arrives before the debt story. | The resident guide shows the broad movements first. The complete 90-row table remains linked in the appendix and in the detailed evidence map. |
| 9. Budget reconciliation | “Does a difference mean the Town's books are wrong?” | “Source-printed total difference” is a control concept that needs a plain example. | The guide explains the exact FY2026 $273 difference and says no balancing department was invented. |
| 10. General Fund revenue | “Is revenue the same as the levy? Can I subtract this from the budget?” | General Fund, audited revenue, property-tax revenue, levy, fund scope, and accounting basis arrive together. | The guide defines revenue and General Fund, shows $52.059 million total and $45.321 million property-tax revenue, then explicitly says why budget minus levy is not a guaranteed reconciliation. |
| 11. Proposition 2½ schedule | “Why is the numerical schedule separated from the formula?” | This section contains the real numbers needed earlier. | It is merged into the main Proposition 2½ teaching section. The complete five-year table is available under an optional disclosure control. |
| 12. Reserves | “Can all of these balances be added and spent?” | The report correctly says no, but free cash, unassigned fund balance, stabilization, and legal availability require definitions. | A short supporting-context section defines reserve, free cash, stabilization, and one-time resource, with three FY2024 examples and a prominent non-addition warning. |
| 13. Enterprise services | “Does a positive result mean the service made a profit?” | “Net operating result,” “enterprise,” “coverage,” and debt service require translation. | The guide defines enterprise fund, user charge, net operating result, and says the $809,432 of debt service is already in expenditures and cannot be subtracted again. |
| 14. Development evidence | “How did we move from my taxes to building permits?” | The section is useful context but interrupts the core budget-to-tax-to-debt learning path. | It remains in the technical appendix until commercial/residential attribution can support a direct resident question. |
| 15. Geographic comparison | “Which comparison changes the budget or debt conclusion?” | Twenty-three measures appear without a single decision question controlling the section. | Preserved in the technical appendix as contextual evidence. |
| 16. Employment and services | “Am I now reading a community profile?” | The human context is valuable but further postpones the debt explanation. | Preserved in the appendix. A later resident edition can use selected service outcomes only when tied to spending questions. |
| 17. FY2027 CSKE classifications | “Are these official Town categories? Why do some fields say unassessed?” | The section introduces internal analytical labels and current-year accounting classifications before debt. | The resident budget section uses only broad published categories. Internal classifications remain in the appendix with the CSKE-origin boundary. |
| 18. Embedded audit | “Why would an audit be counted twice?” | This is a provenance-control question rather than a resident's main financial question. | Preserved in the appendix and source-control documentation. |
| 19. Audited instruments | “What are original amount, outstanding, rate, scope, and maturity?” | The five instruments are important, but the required definitions are not adjacent. | The debt walk-down defines debt, principal, interest, debt service, original principal, outstanding debt, bond anticipation note, general obligation bond, refinancing, and maturity using the actual five instruments. |
| 20. Remaining debt service | “Are five-year bands annual payments?” | The original note warns they are not, but the table still requires a technical reading. | The resident guide gives the controlled totals: $12.746 million principal, $2.897 million future interest, and $15.642 million total. Period bands remain technical evidence. |
| 21. Proposition 2½ debt treatment | “Why are database IDs, JSON, and hashes in a resident report?” | Raw source-native columns overwhelm the legal distinction being taught. | The guide states the known aggregate exclusion, explains the missing project allocation, and moves raw tax-treatment records to the appendix. |
| 22. Audit-to-disclosure bridge | “Did debt rise from $12.7 million to $14.4 million? Should I add the Senior Center amounts?” | Different dates and scopes create a high double-count risk. | The guide labels the totals as two dated observations, explains the Senior Center note-to-bond refinancing, and explicitly prohibits addition. |
| 23. Debt purposes | “Why are original financings not current debt?” | Original principal, outstanding principal, BAN renewal, purpose allocation, and status codes appear together. | Definitions and the 2017 real example are placed in the debt lesson; full purpose rows remain in the appendix. |
| 24. Town and HWRSD snapshots | “Do I add 336 rows? Does all school debt belong to Wilbraham?” | Multiple dates, issuers, and scopes can be silently overcounted by a lay reader. | The guide shows Town and District debt separately, calculates only the supported FY2026 Wilbraham share, prohibits adding 100% of District debt, and warns against adding debt service again when it is already inside the member amount. |
| 25. Long-term obligations | “Can I add pension, OPEB, bonds, and every sensitivity amount?” | The original correctly says rows are not additive, but presents 35 rows with different accounting and actuarial meanings. | The guide defines pension and OPEB liabilities, provides actual examples, and says they matter without being casually added to bond debt service. |
| 26. Definitive affordability | “At last—what evidence would answer the main question?” | This decision-oriented section comes after the bulk technical data. | It becomes the resident conclusion: evidence supporting confidence, evidence still missing, and the precise non-definitive conclusion. |
| 27. Open controls | “Do I need to manage a 38-row internal worklist?” | Valuable project management evidence is presented as public narrative. | Retained in the appendix; the resident guide distills the six missing evidence groups. |
| 28. Audit controls | “Why am I reading 248 equations?” | These prove quality but are not part of resident learning. | Retained intact in the appendix and checksums. |
| 29. Debt controls | “What do IDs, raw JSON, hashes, and treatments mean?” | Internal control structure is exposed directly. | Retained intact in the appendix. |
| 30. Migrations | “What is a database migration, and why does it matter to my tax question?” | Technical lineage is useful for operators but not for the primary audience. | Retained in the appendix/source package. The resident guide states only the evidence-through date. |
| 31. Data roadmap | “This is useful, but why did it come after the database tables?” | This is one of the most decision-oriented sections, but it is last and Town-audience language does not fully match a resident guide. | Its main questions become the final “sensible questions to ask next” table, with known evidence and the exact missing dataset side by side. |

## Word-for-word audit of the v0.5.0 visual, HWRSD, and closing sections

| New element | What a resident may think or misunderstand | Control in v0.5.0 |
|---|---|---|
| Overall budget stacked bars | “If the orange part is 14.6%, why does the report say the budget rose 17.1%?” | The chart states both denominators: the $8,272,853 segment is 14.6% of the $56,595,042 ending total and 17.1% of the $48,322,189 starting budget. |
| Major-increase stacked bar | “Do these colored pieces add to the $8,272,853 net increase?” | The chart labels $10,520,297 of positive movements as its 100% denominator, then visibly reconciles the $326,140 debt-service decrease and $1,921,304 balancing residual to the $8,272,853 net increase. The residual is explicitly not called a department. |
| Three closing resident questions | “Is this another technical appendix?” | Each card begins with a familiar purpose—understand voting, strengthen non-residential revenue, or protect service value—and points to later detail rather than presenting an unfinished conclusion as complete. |
| “Home rule” sentence | “Does home rule mean voters can veto every expenditure?” | Home rule is defined as municipal authority within legal limits, not as a separate type of spending vote. Town Meeting, election ballot questions, early public participation, and citizen-petition warrant articles are named separately. |
| Resident-choice chart | “If I vote no on an exclusion, is the whole project automatically canceled?” | Borrowing authorization and debt-exclusion financing are shown as separate decisions. The chart and adjacent warning say the exact article, question, funding, law, and contingency wording control. |
| Routine departmental spending row | “Can residents vote on every invoice?” | The row explains that residents influence routine spending through budget approval, public review, performance oversight, and later budget cycles rather than day-to-day administration. |
| Revenue row | “Is every new fee, grant, or free-cash use a property-tax saving?” | The row separates reliable recurring support from one-time or limited-purpose resources and notes that a fee shifts who pays rather than automatically creating a saving. |
| Cumulative-spending standard | “How do I see the effect of many small approvals?” | The planned disclosure set puts the annual change, five-year cumulative cost, funding source, household effect, staffing or contract consequences, service result, alternatives, and yes/no consequences together. |
| HWRSD growth bar | “Is the $7.0 million increase Wilbraham's bill?” | The chart labels the amount as the District-wide budget change and separately introduces Wilbraham's member amount. |
| HWRSD driver bar | “Do the positive colored pieces equal the net increase?” | The bar states its positive-movement denominator, subtracts the capital decline, and preserves the remaining $1 source difference. |
| Enrollment comparison | “Does this prove spending was wasteful?” | The guide concludes only that enrollment growth does not explain the increase; it does not infer staffing efficiency, program value, or marginal student cost. |
| 77.42% member split | “Is 77.42% of my bill schools?” | The same sentence and graphic state that the denominator is the combined two-town operating-and-capital amount—not a household bill. |
| 79.9% capital allocation | “Can I use this for every future year?” | The factor is labeled FY2026 only; later use would be illustrative and not official. |
| HWRSD debt schedule | “Should I add District debt to the member assessment?” | The portfolio rule requires a non-duplication bridge and prohibits automatically adding District debt service on top of the combined member amount. |
| Future-module list | “Are those analyses already finished?” | The closing section says the broad budget and debt findings are complete while contract, staffing, placement, transportation, facility, service, future-allocation, and household drill-downs remain future work. |

## Financial language that required explicit definitions

The original opening defined six concepts well, but later narrative used many additional terms without a real-number definition at first use. The v0.5.0 term control includes, among others:

- fiscal year, budget, appropriation, expenditure, revenue, General Fund, and property-tax revenue;
- tax levy, prior-year levy limit, ordinary 2.5% increment, new growth, operating override, growth levy limit, debt exclusion, capital-expenditure exclusion, levy limit including exclusions, actual levy, unused levy capacity, and levy ceiling;
- assessment, residential tax rate, calculated base property tax, property-tax exemption, abatement, betterment, and Community Preservation Act surcharge;
- enterprise fund, user charge, and net operating result;
- reserve, fund balance, unassigned fund balance, free cash, stabilization fund, recurring, and one-time resource;
- debt, debt instrument, MWPAT loan, general obligation bond, bond anticipation note, principal, interest, debt service, outstanding debt, original principal, maturity, refinancing, direct debt observation, and statutory debt limit;
- pension liability, OPEB liability, actuarial estimate, HWRSD, member-town operating-and-capital amount, member-town share, operating assessment, budget per reported enrolled student, net state aid, state-aid coverage, burden-shift indicator, capital-cost allocation, authorized-but-unissued debt, estimate, projection, audit, official disclosure, calculated result, and reconciliation.
- Town Meeting, warrant article, ballot question, home rule, operating budget, borrowing authorization, and life-cycle cost.

Each appears in `TERM-AND-NUMBER-CONTROL.csv` with a plain definition, a Wilbraham real-number example, and its first teaching section.

## Editorial rules applied to the resident guide

1. A number never appears without its measure, period, and scope nearby.
2. Different periods are not placed side by side without an explicit warning.
3. A calculated result shows its inputs and formula.
4. “Budget,” “revenue,” “levy,” “assessment,” “rate,” and “bill” are never treated as synonyms.
5. “Levy ceiling,” “growth levy limit,” and “limit including exclusions” remain distinct.
6. Original principal is never described as current outstanding debt.
7. A temporary note and its permanent refinancing are never added as separate current obligations.
8. HWRSD schedules are not assigned wholly to Wilbraham; 77.42%, 79.9%, 53.38%, and 63.82% retain their distinct denominators.
9. One household is never called typical without a Town-wide comparison.
10. “Repayable under the presented schedule” is not converted into “affordable,” “reasonable,” or “comfortable.”
11. Large source and control tables remain complete, counted, indexed, and linked, but they do not interrupt the learning path.
12. Missing evidence is named precisely rather than hidden behind a general disclaimer.
13. A stacked-bar denominator is stated; positive movements are not presented as though they equal the smaller net increase after offsets.
14. Town Meeting approval, borrowing authorization, and a Proposition 2½ ballot question are never treated as one interchangeable vote.
15. Resident influence is explained without promising an unlimited veto over legal obligations, routine administration, or powers assigned by state law.
16. The final section previews the next teaching modules without representing those future drill-downs as completed evidence.
17. District debt service is not added on top of the combined member amount without a source bridge proving non-duplication.
18. An empty HWRSD receiving table is reported as missing evidence, never as a zero-valued fact.