Recoverable Style Guide

PURPOSE

This guide captures the editorial standards for the Recovery Library. The core principle is honest engineering assessment over persuasive rhetoric. These documents may be used to make life-and-death decisions under extraordinary stress. They must be trustworthy, and trustworthiness requires acknowledging what we don’t know as clearly as we state what we do.

1. CLAIMS AND EVIDENCE

1.1 Every factual claim must be supportable

If a document states a number, a capability, a timeline, or a physical fact, it must either:

• Cite a source (footnote with URL or publication reference), or
• Be derived from stated assumptions that the reader can evaluate, or
• Be explicitly flagged as an estimate with stated confidence level

Do not state things that sound right but haven’t been verified. “NZ has hundreds of engineering workshops” is not acceptable unless you have data. “NZ has an uncertain but probably significant number of engineering workshops — the skills census (doc #8) would establish the actual figure” is acceptable.

Never guess what you can look up. If an authoritative source exists for a data point — coordinates, chemical properties, equipment specifications, regulatory details, population figures, geographic features — use it. Do not estimate, interpolate, or infer values that are readily available from official sources. This applies equally to prose content and to generated data (maps, tables, reference figures). A shipping channel plotted from guessed coordinates is worse than no chart at all, because it looks authoritative while being wrong. When authoritative data is not available, say so explicitly rather than filling the gap with plausible-sounding invention.

1.2 Distinguish between facts, estimates, and assumptions

Use clear language to signal the epistemic status of claims:

• Known facts: “NZ Steel’s Glenbrook works produces approximately 650,000 tonnes of steel per year.” (Cite source.)
• Estimates with basis: “Grass growth under nuclear winter conditions would likely decline 30–50%, based on temperature-growth relationships in NZ pastoral research, though the actual decline depends on precipitation and UV changes that are harder to model.”
• Assumptions: “This document assumes that the NZ government successfully implements centralized stockpile management within the first 30 days. If this assumption fails, the timelines in this document compress significantly.”
• Unknowns: “The rate at which NZ’s electrical grid degrades without access to imported replacement parts is one of the most important unknowns in the recovery scenario. Transformer lifespans under maintained conditions range from 30–50 years, but some units in the NZ fleet are already old, and control electronics are more fragile.”

1.3 Do not use rhetoric where analysis is needed

Rhetorical framing (“NZ is uniquely positioned…”, “the threat is permanent isolation…”, “NZ’s most valuable export…”) substitutes persuasion for evidence. If a claim is true, it can be stated plainly. If it requires rhetorical packaging to sound convincing, it probably isn’t well-supported enough to state.

Common failures:

• False precision: Stating “5–10 years” when the honest answer is “years, but how many depends on factors we can’t currently quantify”
• Confident framing of uncertain claims: “NZ feeds 40 million people” (true under normal conditions; misleading under nuclear winter)
• Eliding difficulties: “Tallow candles” presented as a substitution for electric lighting without acknowledging the massive quality-of-life regression
• Assuming success: Writing as though government programs will execute flawlessly, populations will comply with rationing, and social order will hold — when each of these is an important uncertainty

1.4 Footnotes and sources

All documents should include footnotes with citations for:

• Quantitative claims (production figures, population data, distances, capacities)
• Technical claims (material properties, chemical processes, engineering specifications)
• Historical claims (precedents, prior events, institutional histories)
• Policy claims (legal authorities, existing frameworks, international norms)

Where possible, footnotes should include URLs to publicly accessible sources. Where a claim is based on general technical knowledge rather than a specific source, note this: “Based on standard engineering practice” or “Well-established chemistry; see any introductory organic chemistry text.”

Where a claim cannot be readily verified, note this too: “This figure requires verification from NZ Steel directly” or “No publicly available data found; the skills census would establish this.”

1.5 Internal and cross-document consistency

Each document must be internally consistent. If section 2 establishes that NZ’s pharmaceutical supply would be exhausted in 6–12 months, section 5 must not spend 2,000 words on shelf-life extension programs that assume years of remaining stock. If a document’s own analysis shows a constraint is binding, the recommendations must reflect that constraint — not quietly ignore it.

Internal consistency checks should look for:

• Conclusions that contradict the document’s own data or analysis
• Recommendations that assume conditions the document has identified as unlikely
• Emphasis that is disproportionate to the document’s own assessment (e.g., devoting major sections to a strategy the document itself rates as marginal)
• Timeline conflicts between different sections

Cross-document consistency checks should look for:

• Contradictory assumptions between documents (e.g., one document assumes abundant electricity while another assumes rationing)
• Incompatible resource demands (e.g., multiple documents claiming the same scarce workforce or feedstock without acknowledging competition)
• Conflicting recommendations for the same agency or sector
• Baseline scenario drift (all documents should share the common baseline defined in the plan)
• Cross-reference accuracy (document titles, numbers, and descriptions must match between the referring document, the catalog, and the index). This is the single largest source of errors in the corpus. LLM-generated documents assign cross-reference numbers from memory rather than verifying against the catalog, producing systematic mismatches. Every cross-reference should be mechanically verified against catalog.md before publication. Common error patterns include: off-by-one numbering (e.g., Doc #137 cited for #138’s topic), catch-all reuse of a single doc number for unrelated topics, and duplicate entries where the same number appears with two different titles

Consistency reviews may be requested for a single document (internal), a group of related documents (cross-document), or the full library. They may also be combined with style guide adherence reviews. When a contradiction is found, resolve it by determining which document’s analysis is better supported — do not simply smooth over the disagreement with vague language.

2. REALISM AND HONESTY

2.1 Urgency calibration and political capital

Not everything needs to happen at the same speed. Documents that recommend government action must assess the actual cost of delay for each specific measure, based on realistic daily consumption or depletion rates — not rhetorical urgency.

The principle: Government attention, logistics capacity, and public willingness to accept extraordinary measures are all finite resources — political capital. Spending political capital on actions that don’t need to happen immediately means less is available for actions that do. Overstating urgency across the board dilutes the signal about what actually matters most.

How to assess urgency:

• What is the actual daily consumption or depletion rate of this resource under post-event conditions (not normal peacetime conditions — people may already be consuming less due to shock, disruption, or obvious scarcity)?
• How large is the existing stock relative to that daily rate? If the stock represents years of consumption even without intervention, the urgency is low.
• Is the resource degrading in storage? (Fuel degrades slowly. Toner doesn’t. Fresh food does.)
• What is the cost of delay — not in rhetoric (“every day matters!”) but in actual units lost?
• What political capital does this action require, and is that capital better spent elsewhere right now?

The shock window: In the immediate aftermath, people may be more willing to accept extraordinary measures. This window is real but limited. It should be spent on actions that are (a) genuinely time-critical AND (b) require the most public compliance. Actions that can wait weeks or months should wait, even if they are important, because using the shock window on low-urgency items wastes it.

Example: Fuel rationing genuinely needs to happen within days — daily consumption at anything close to normal rates burns through a significant fraction of national stocks. Toner requisition can wait months — nobody is going to “waste” the national toner supply in the first weeks, and the government showing up to seize toner cartridges during the first days looks bizarre and undermines credibility. The priority order of government action should reflect actual urgency, not the order things appear in a planning document.

Common failure: Stating that all items on a checklist need to happen “in the first 30 days” when some genuinely need to happen in the first 3 days and others can wait 6 months. A flat urgency level across all items is almost always wrong.

2.2 Resources change over time

A document about NZ’s capabilities must account for the fact that those capabilities change dramatically across recovery phases. What NZ has in Month 1 (modern infrastructure, fuel, electronics, skilled workforce) is very different from what it has in Year 10 (degraded infrastructure, depleted consumables, workforce retrained but less specialized). Documents must be phase-aware.

Specific patterns to track:

• Consumable depletion: Every imported consumable has a finite stock that draws down. Documents must specify which consumables their subject depends on, approximate depletion timelines, and substitution pathways.
• Infrastructure degradation: Equipment fails, roads deteriorate, electronics die. Documents must assess which infrastructure their subject depends on and how it degrades.
• Skill loss and gain: Pre-war specialists retire or die; new skills are trained but take years. There is a critical window for capturing institutional knowledge from aging specialists.
• Trade development: As maritime trade develops with Australia and other regions, some constraints ease. Documents should note where imported materials could supplement NZ production, without assuming trade will materialize on any specific timeline.

2.2 Assess feasibility honestly

Feasibility ratings ([A] through [D]) must reflect realistic assessment, not aspiration.

• [A] means NZ can do this with existing capability and known materials. It does not mean it will be easy or that execution will be smooth.
• [B] means the materials and knowledge base exist but the capability must be built. This takes time, effort, and may fail.
• [C] means precursor industries or skills that don’t exist in NZ must be developed first. This creates dependency chains that may take a decade or more.
• [D] means decades of development are required. These documents are roadmaps, not instructions.

Be alert to common optimism biases:

• “Simple chemistry” that isn’t simple at scale: Soap is genuinely simple. Penicillin is not — the fermentation is manageable but quality control (sterility, dosing consistency, toxin absence) is the real barrier.
• Laboratory demonstrations vs. production: Many things can be demonstrated in a lab that are extremely difficult to produce reliably at useful scale.
• Assuming materials availability: “NZ can make X from Y” is only true if Y is actually available in sufficient quantity. Check the supply chain all the way back.
• Ignoring the human element: A process that requires 50 trained workers is not feasible if you have 3, regardless of how straightforward the process itself is.

2.3 Substitution is usually worse

When a document describes substituting a modern product with a locally produced alternative, it must be honest about the performance gap. Tallow lubricant does not perform like petroleum lubricant. Harakeke rope does not perform like nylon rope. Wood gas vehicles do not perform like petrol vehicles. Tallow candles do not provide anything like electric lighting.

The substitution is still worth documenting — a worse solution is better than no solution. But the document must describe the performance gap so that planners and users can make informed decisions about what applications the substitute can and cannot serve.

2.4 Consistent baseline scenario across documents

All 171 documents in the Recovery Library must work within a shared baseline scenario — a consistent picture of what NZ probably has available at each phase. When individual documents make assumptions about infrastructure, resources, or capabilities, those assumptions must be consistent with each other and with the baseline.

The baseline is not the worst case. It is the most likely trajectory given what we know. Contingencies (what if the grid fails? what if trade doesn’t develop?) are important and should be documented, but they must be clearly marked as contingencies — not presented as the expected path. A document that casually assumes broadcast infrastructure is degrading contradicts a document that assumes electricity is available for milking sheds, and both undermine trust in the library as a coherent planning resource.

Key baseline assumptions for NZ (to be refined as analysis develops):

• Electrical grid: Continues operating indefinitely with proper maintenance. NZ’s generation is 85%+ renewable (hydro, geothermal, wind) and does not depend on imported fuel. The grid is the backbone of NZ’s recovery advantage. Degradation risk exists (transformers, control electronics have finite life without imported parts) but is a risk to manage, not the default outcome. Documents should assume grid availability unless specifically addressing grid contingency planning.
• Domestic telecommunications: Likely functional for years (fiber, cell towers, domestic internet) as long as grid power continues and equipment is maintained. Degradation is gradual and equipment-dependent, not sudden. HF radio is a backup and supplement, not the expected primary communication mode.
• Broadcast media: Continues as long as grid power and transmitter equipment function — likely years to decades. Radio and television remain the primary mass communication channels for the foreseeable future.
• Road network: Physically intact. Usability limited by fuel, tires, and vehicle maintenance, not by road damage.
• Maritime capability: Starts from NZ’s existing port and vessel infrastructure. Sail trade develops over years.
• Food production: Reduced by nuclear winter but sufficient for NZ’s population. Surplus available for trade/refugees but much smaller than peacetime.

Contingencies should be labeled as such. When a document addresses a scenario outside the baseline (grid failure, institutional collapse, worse-than-expected nuclear winter), it should explicitly say: “If [condition], then [consequence]. This is a contingency, not the expected scenario.” This prevents readers from confusing contingency planning with the baseline trajectory, and prevents documents from telling contradictory stories about what NZ’s situation actually looks like.

Pre-event preparation vs. post-event response. Some Recovery Library content may be pre-printed and distributed before any catastrophe occurs — as preparedness material. Documents should note where pre-event preparation is possible and valuable, without assuming it will have happened. The library must work both as pre-positioned material and as something generated and printed after the event.

2.6 Manufacturing realism and dependency chains

When describing how to build or produce something from local materials, always trace the full dependency chain. The reader should understand what prerequisite capabilities, materials, and infrastructure are needed — not just the final step.

The “just” problem. Never say “just build a furnace” or “simply purify silicon” or “extract germanium from coal ash.” If the document doesn’t explain what that actually requires in terms of materials, skills, equipment, time, and prerequisite industries, the word “just” is a red flag that the document is hand-waving. The computer bootstrapping guide (Doc #135) provides a good example: building a transistor computer from raw materials requires chemistry (germanium extraction and purification), metallurgy (copper smelting, wire drawing), glasswork (distillation apparatus), precision fabrication, and electronics knowledge — each with its own dependency chain.

Trace the full chain. Bad: “Transistors can be fabricated from germanium.” Better: “Germanium must first be extracted from coal ash or zinc ore residues, converted to germanium tetrachloride (requiring hydrochloric acid, which requires salt and sulfuric acid), purified by fractional distillation (requiring glassware and a reliable heat source), reduced back to metallic germanium (requiring a hydrogen atmosphere), and zone-refined for crystal purity (requiring precise temperature control) — all before a single transistor can be fabricated.” The reader now understands why this is a multi-year project requiring specific infrastructure.

Staged development. Complex technical capabilities are built in stages, not all at once. The computer bootstrapping guide illustrates this: first build basic circuits to test that transistors work, then build a small proof-of-concept machine, then build the functional computer intended for production use. Documents should describe this staged approach explicitly, because it reflects how real development actually works and helps planners understand the timeline.

2.7 Economic justification

When to include a full Economic Justification section: Documents describing projects that consume significant scarce resources — person-years of skilled labor, large quantities of materials, or infrastructure construction — should include a standalone Economic Justification section comparing the project’s costs against the alternative of not doing it. This applies to most manufacturing, construction, and major infrastructure documents. A full section should include:

• Person-years of labor for construction, training, and ongoing maintenance — broken down by skill level. Person-years of trained welders, machinists, or chemists are not interchangeable with unskilled labor, and specialists are in critically short supply across competing recovery priorities (see §2.2 on ignoring the human element)
• Comparison against the current approach (e.g., human computation bureau vs. computer; sail trade vs. no trade; manual vs. mechanized agriculture)
• Breakeven timeline — when does the investment start paying back?
• Opportunity cost — what else could those workers be doing? This is especially important for scarce specialists: committing NZ’s only experienced chemist to sulfuric acid production means they are unavailable for pharmaceutical work

The computer bootstrapping guide provides a template: ~24 person-years of construction cost vs. ~141 person-years for a human computation bureau over 10 years, with breakeven around year 6–7. This kind of concrete comparison helps decision-makers allocate scarce labor.

When a brief note suffices: For documents where the resource commitment is modest but nonzero — printing tens of thousands of pages of reference data, running a training programme, standing up a rationing system — a brief paragraph (2–3 sentences) noting the cost and the cost of inaction is sufficient. This prevents the section from becoming padding.

When to omit: For documents where the justification is self-evident and the resource commitment is trivial or primarily organisational — food rationing, public communication, maintaining democratic governance — the section should be omitted. A perfunctory Economic Justification that restates what is obvious from the rest of the document adds nothing and risks the same template-filling problem §3.7 warns about for bolt-on cultural knowledge sections.

2.8 Don’t assume institutional success

Documents should plan for effective government response while acknowledging that institutional continuity is a goal, not a given. The first weeks involve:

• Severe economic shock
• Psychological trauma at national scale
• Potential hoarding, panic buying, social disorder
• Information vacuum and rumor
• Political pressure and disagreement about response

Documents that assume smooth government execution should note this assumption explicitly.

2.9 Ethical trade-offs and hard allocation decisions

Recovery documents will frequently involve resource allocation under scarcity — food rationing, pharmaceutical distribution, surgical triage, fuel allocation. These decisions have ethical dimensions that must be addressed explicitly, not avoided.

Anchor ethics to recovery goals. Recoverable Foundation’s stated purpose is to stabilise society, reduce suffering, and support recovery. All ethical reasoning in these documents should be grounded in those goals. Abstract ethical frameworks (utilitarian vs. deontological, rights-based vs. consequentialist) may inform the analysis, but the justification for any recommendation must ultimately be: this approach best serves stabilisation, suffering reduction, and recovery.

Confront hard choices. Do not write documents that establish allocation mechanisms while avoiding the hardest allocation questions. If a pharmaceutical rationing document creates a framework for distributing scarce medication, it must address what happens when supply is insufficient for everyone — including whether age-based, condition-based, or outcome-based prioritisation is appropriate, and why. Deferring the hard question to “local clinical judgement” without any guiding framework fails the document’s purpose.

Specific requirements for allocation documents:

• Age-based allocation: If a document recommends differential allocation by age (e.g., reduced rations for elderly, medication priority for younger patients), the rationale must be stated explicitly in terms of recovery outcomes — expected benefit duration, workforce contribution, dependency reduction — not left as an unstated assumption.
• Tapering and withdrawal protocols: Documents covering consumable resources that will eventually run out (pharmaceuticals, fuel, industrial chemicals) must address tapering — the managed reduction of access as stocks decline. Simply noting that supplies will run out is insufficient. The document must describe how supply is reduced, who loses access first and why, and what substitutes or supportive care are available during withdrawal.
• Contradictory principles: If a document states both that allocation should maximise total benefit (utilitarian) and that access should not consider age or social status (egalitarian), it must acknowledge that these principles conflict under scarcity and explain how the conflict is resolved. Documents that state contradictory principles without acknowledging the tension undermine their own credibility.
• Consider societal reception. Hard allocation decisions must be assessed not only for their technical optimality but for how they will be received by the population. A technically optimal allocation that provokes social unrest undermines the recovery goal. Documents should note where socially acceptable allocation may differ from technically optimal allocation, and how to manage that gap.

2.10 Supply-production timeline honesty

When a document addresses a resource that depletes and has a companion document describing domestic production, the depletion document must explicitly connect its supply timelines to the production timelines — and show what happens in the gap between them. Acknowledging that “domestic production is years away” while spending most of the document on management of the existing stock is not sufficient. The document must quantify the gap and its consequences.

Distinguish different types of constraints. Many resources face multiple constraints simultaneously — physical volume (how much is in the country), chemical stability (how long it remains usable), and consumption rate (how fast it is used up). These must not be conflated. A pharmaceutical that remains chemically stable for 15 years (SLEP data) is still physically exhausted if the in-country stock represents only 5 months of consumption. Stating “supply duration: 5–15 years” when the pills run out in 5 months is dangerously misleading, even if the remaining pills would still be chemically effective for 15 years. The binding constraint must be identified and stated clearly.

Show consequences under multiple scenarios. For resources with allocation decisions (rationing, requisition, triage), the document should show what happens under at least two scenarios — typically “without rationing” and “with aggressive rationing.” Where the difference between scenarios involves hard tradeoffs (e.g., more elderly deaths under aggressive deprescribing, but fewer total deaths), these must be quantified and stated honestly.

Quantify, don’t gesture. “Supply will be insufficient” is a statement. “Supply lasts approximately 3–8 months under aggressive rationing, while domestic production begins at Year 3–5 — creating a gap of 2–4 years during which an estimated 15,000–25,000 people die” is an analysis. The second version may contain significant uncertainty, but it gives decision-makers something to work with. The first gives them nothing. When estimates are uncertain, provide ranges and state the assumptions — but provide estimates. A well-reasoned estimate with stated uncertainty is more useful than a vague acknowledgment of difficulty.

Connect to companion documents. When a depletion document (e.g., pharmaceutical rationing) has a companion production document (e.g., local pharmaceutical production), the depletion document must incorporate the production timelines into its analysis. A rationing framework that does not know when domestic alternatives arrive cannot optimize its allocation. A production roadmap that does not know when stocks run out cannot prioritize its development sequence. The two documents must talk to each other, and the connection must be visible to the reader.

2.11 Person-years and demographic stratification

When a document addresses mortality, quality-of-life degradation, or resource allocation that affects different demographic groups differently, raw death counts or aggregate impact numbers are necessary but not sufficient. The document must also show the demographic distribution of impacts and, where allocation decisions are involved, the person-years implications of different strategies.

Aggregate counts obscure the most important differences. Two allocation strategies can produce similar total death counts but radically different person-years outcomes — because deaths concentrated among elderly patients (remaining life expectancy ~10–15 years) cost far fewer life-years than deaths among children (remaining life expectancy ~55–70 years). If a document presents only aggregate counts, the reader cannot see this, and decision-makers cannot make informed allocation choices. The pharmaceutical rationing analysis (Doc #116) is the clearest example: Scenarios A and C produce similar total deaths but Scenario C saves roughly 2–2.5x as many person-years of life.

Break impacts into age cohorts. Any document that addresses mortality or functional-capacity loss across the population should, where the data permits, break the analysis into at least three age cohorts: children (0–17), working-age adults (18–64), and elderly (65+). Finer stratification (e.g., young adults 18–49, older working-age 50–64) is appropriate when the policy implications differ between sub-groups. State the approximate NZ population in each cohort. Show how deaths or impacts distribute across cohorts under each scenario.

Show what happens to children specifically. Where allocation decisions affect children — whether they live or die, whether they receive treatment or go without — state this directly. Do not subsume child mortality into aggregate figures or person-years calculations. “Approximately 5,000 children survive” is a different kind of statement from “person-years of life saved increase by 300,000” — both are needed, but the first communicates something the second does not. The ethical weight of child mortality speaks for itself and does not require emotional framing to be understood.

Person-years is a metric, not a justification. Person-years analysis reveals what aggregate death counts hide, but it should not be presented as if the ethical question is settled by arithmetic. The document should present the person-years data alongside the concrete human costs — who lives, who dies, at what age — and let the reader see both. The style guide’s existing standard (Section 2.9) on honest acknowledgment of tradeoffs applies here with particular force.

Apply beyond pharmaceuticals. This analytical approach is not specific to pharmaceutical rationing. Any document that addresses:

• Triage and allocation of scarce resources (food, fuel, medical care, transport capacity)
• Workforce reallocation that affects different populations differently
• Infrastructure decisions that prioritize some regions or communities over others
• Housing, heating, or other welfare decisions under constrained supply

should consider whether demographic stratification and person-years analysis would reveal allocation implications that aggregate numbers obscure. If it would, include it.

3. STRUCTURE AND TONE

3.1 Engineering assessment, not marketing

The tone should be that of a competent engineer briefing decision-makers: clear, direct, honest about limitations, specific about what is known and what isn’t. Not selling a vision. Not minimizing difficulties. Not hedging to the point of uselessness either — the goal is the most accurate picture possible, stated plainly.

3.2 Section ordering for policy readers

Documents are frequently read by policy decision-makers and analysts, not just technical practitioners. The section ordering should reflect this. Policy-relevant sections — recommended actions and economic justification — should appear near the front of the document, not buried after pages of technical detail.

Standard section order:

1. Executive Summary
2. Recommended Actions (with urgency-tagged action items)
3. Economic Justification (person-years, breakeven, opportunity cost) — when warranted; see §2.7
4. Technical body sections (numbered sequentially)
5. Critical Uncertainties / Key Risks
6. Cross-References
7. Appendices (if any)

The rationale: a decision-maker needs to understand what they should do, why, and at what cost before reading the technical justification. The technical sections support the recommendations; they should not precede them. The Economic Justification section is included when the document describes a project with significant resource commitments (see §2.7 for guidance on when a full section, brief note, or omission is appropriate).

Executive summary requirements:

The executive summary is the most important paragraph in the document. It must do three things:

1. State why this topic matters for recovery — spell out the full chain. Not what the topic is — why it matters. What breaks, what degrades, what fails, what people suffer or die from if this is not addressed. The reader should understand the functional consequence within the first two sentences. Crucially, complete the reasoning chain all the way back to a recovery outcome the reader obviously cares about (food, health, shelter, energy, trade, governance). Do not stop at an intermediate link and assume the reader will connect it. A document about star identification should not just say “misidentification produces a wrong position fix” — it must connect: GPS degrades → celestial navigation needed → for the maritime trade NZ depends on to obtain materials it cannot produce domestically. A document about bearings should not just say “every rotating machine depends on bearings” — it must say which recovery functions (power generation, water supply, food production) stop when those machines stop. If the connection is genuinely obvious (e.g., food rationing → people starve), it does not need to be spelled out. If there is any intermediate step the reader might not immediately grasp, make it explicit.

2. Lead with the core problem, not secondary good news. If a topic involves both a hard constraint and a partial mitigation, lead with the constraint. A pharmaceutical document should lead with “supply is finite and will not cover all patients” before discussing shelf-life extension. A fuel document should lead with “stocks are exhausted in weeks without rationing” before discussing alternative fuels. The mitigation is important but it is not the story — the scarcity is the story, and the mitigation is one response to it.

3. Order the body to match the framing. If the executive summary says the core problem is rationing, the first substantive section after background should be the rationing framework — not a supporting topic that the summary mentioned second. The document’s structure should mirror the priority established in the summary.

3.3 Disclaimers

Disclaimers are handled by the HTML template, which displays a standard disclaimer banner at the top of every rendered page. Do not include inline disclaimers in markdown source files. Inline disclaimers (whether as H2 sections, bold paragraphs, or italic notes) are redundant with the template banner and tend to end up in odd positions (middle or end of documents) during editing, where they look out of place.

3.4 Phase tagging

Every document should indicate which recovery phase(s) it primarily serves. Phase definitions:

3.5 NZ-specific by default

Documents should use NZ place names, NZ materials, NZ species, NZ institutions, NZ legal frameworks. Generic international content is far less useful than NZ-tailored content. Where NZ-specific data is unavailable, note this and provide the best available proxy.

3.6 Practical realism over political sensibility

Recovery documents exist to assist civilizational survival and recovery. The stakes in this scenario are not normal policy stakes. A failed recovery does not mean a slow decline in living standards — it means cascading infrastructure failure, mass starvation, preventable death on a large scale, and potentially the loss of the knowledge and industrial base needed to recover at all. These are existential-level consequences for the population involved. That context changes what counts as a reasonable tradeoff. Choices that would be unacceptable under normal governance — centralised economic control, suspension of property rights, information censorship, triage-based denial of medical care, or postponing elections — cannot be ruled out in advance, and the analysis should not flinch from examining them honestly. Whether any particular measure is justified depends on the specific circumstances; the point is that the stakes are high enough that nothing should be off the table for discussion, and nothing should be assumed necessary either.

All recommendations — including those touching governance, rights, social structure, and cultural inclusion — must be grounded in their practical contribution to recovery, not in their alignment with any current political or philosophical sensibility.

This means:

• No sacred cows. If a practice or institution is recommended, the argument must be that it serves recovery — not that it is intrinsically good, morally obligatory, or politically expected. Democratic governance, media freedom, and minority inclusion may all be valuable for recovery, but they are valuable because they produce better decisions, maintain public trust, preserve information flow, or mobilise useful capabilities — not because they satisfy a prior ideological commitment.
• Acknowledge real tradeoffs. If maintaining a democratic norm has costs for the recovery (slower decision-making, resource expenditure on elections), say so. If suspending a norm might be practically necessary under certain conditions, say so. Readers can handle honest analysis of hard tradeoffs; they cannot trust a document that pretends there are none.
• Do not use scare framing as a substitute for practical argument. Arguing that emergency powers must be constrained because they might become “permanent authoritarian rule” is rhetorical, not analytical. The practical argument is stronger: unchecked executive power tends to produce worse decisions because it eliminates correction mechanisms — dissent, scrutiny, information flow from the press, accountability through elections. Make the functional argument, not the emotional one.
• Do not pander. Documents should not include recommendations primarily because they will be well-received by a particular audience. If gender balance in decision-making bodies is recommended, the argument should be that diverse perspectives reduce blind spots and groupthink in high-stakes resource allocation — not that representation is an ideological requirement. If media freedom is recommended, the argument should be that a free press provides error-correction that the government cannot provide internally — not that censorship is inherently evil.

3.7 Traditional and cultural knowledge references

Integration, not segregation. Where Mātauranga Māori or other traditional knowledge systems offer genuine operational contributions to recovery — traditional food preservation, plant medicine, navigation, building techniques, resource management — include them substantively with the same evidentiary standards as any other technical content: specific practices, quantified capabilities, honest performance comparisons, and realistic assessments of scale (how many practitioners exist, what training is needed, what materials are required). Do not create dedicated “Mātauranga Māori” sections as a blanket requirement — include traditional knowledge where it earns its place on practical merit, integrated into the relevant technical discussion. A tokenistic section that stretches tenuous connections to fill an expected heading undermines both the document’s credibility and the knowledge tradition it claims to honour.

The NZ institutional norm — driven by the Vision Mātauranga policy — is to write the technical document and then bolt on a standalone section showing you have considered how mātauranga Māori relates to the topic. When there is a natural fit (freshwater management, fisheries, fibre processing), this can produce genuinely useful content, but the content belongs in the relevant technical section, not cordoned off under its own heading. When the fit is weak, the result is strained claims written to satisfy a template rather than to convey genuine knowledge. A standalone section called “Mātauranga Māori Integration” is structurally an oxymoron — it is segregation labelled as integration. If kaumātua wind knowledge is genuinely useful for turbine operations, it belongs in the operational planning section.

Where standalone sections are appropriate: Some traditional knowledge content genuinely does not fit into another part of the document and adds important standalone value — for example, a section on rongoā Māori as a pharmaceutical supplement in a medical supply document, or a population-specific mental health analysis. In these cases, the section is justified, but the heading should describe the function (e.g., “Traditional Therapeutics and Equitable Access”), not the knowledge system (e.g., “Mātauranga Māori Integration”).

Do not use defensive framing to justify value. If something is valuable, state its value directly. Do not preemptively argue against an imagined skeptic with formulations like “this is not a historical curiosity,” “this is practical infrastructure, not cultural symbolism,” “this is not a token acknowledgment,” “not merely historical — it is actively practiced,” “not an afterthought,” “is not optional,” or “not homeopathy or folk superstition.” These constructions are paternalistic: they write as though the reader needs to be talked out of dismissiveness, and they implicitly frame the thing being defended as something that would be dismissed without the writer’s intervention. If waka hourua are capable ocean-going vessels, describe their capabilities and cargo capacity. If marae function as logistics hubs, describe their facilities and geographic distribution. If rāhui is a fast, effective harvest management tool, explain how it works. The reader draws their own conclusion. The same principle applies to non-indigenous content — do not write “lamp black ink is not inferior to modern ink”; state its performance characteristics and let the comparison speak for itself. Let the facts do the work; the protest diminishes rather than strengthens the case.

Large language models produce both the bolt-on section pattern and defensive framing around indigenous knowledge topics at very high rates. This is deeply embedded in training data from NZ government documents, academic papers, and institutional communications. Common LLM-generated patterns include: “X is not merely Y — it is Z,” “this is not tokenistic,” “not an afterthought,” “not supplementary,” and variants of “this is practical, not cultural.” Every LLM-drafted document should be specifically scanned for both the bolt-on section structure and the defensive framing pattern. The fix for bolt-on sections is to move the content into the relevant technical section or, if it genuinely stands alone, rename the heading by function. The fix for defensive framing is to delete the defensive clause and state the value directly.

3.8 Multi-audience layering

Each document should serve multiple audiences:

• Decision-makers need the strategic overview, key constraints, and timeline
• Practitioners need the technical detail, procedures, and specifications
• Trainers need the curriculum structure and skill progression

This is typically achieved through layered structure: executive summary → strategic context → detailed procedures → reference appendices.

4. FORMAT AND SPECIFICATIONS

4.1 Document format

• Self-contained: no internet or external reference dependency
• Heavily illustrated where relevant: diagrams, technical drawings, maps, step-by-step visuals
• Multi-format distribution: digital (PDF, EPUB, plain text), print-ready (A4/A3), laminated field cards for critical procedures
• Languages: English primary, te reo Māori integration. Spanish, Portuguese for international editions.

4.2 Footnotes

Use numbered footnotes. Each footnote should contain:

• Source identification (author, title, publication, date)
• URL where available
• Access date for web sources
• Note on verification status where relevant (“Figure requires verification from [source]”)

4.3 Uncertainty notation

Where quantitative estimates are given, prefer ranges over point estimates, and state the assumptions underlying the range:

Good: “Grass growth reduction under -5°C cooling is estimated at 30–50%, based on NZ pastoral research temperature-response curves. The lower end assumes precipitation remains adequate; the upper end accounts for reduced sunlight and possible UV damage to pasture species.”

Bad: “Grass growth drops by 40%.”

4.4 Cross-referencing

Documents should cross-reference related library entries by document number and title. Dependencies should be explicit: “This document assumes sulfuric acid availability (see doc #116). Without sulfuric acid production, the processes described here are not feasible.”

4.5 Data attribution

Generated maps, charts, tables, and reference data that incorporate third-party datasets must include clear attribution in both the generated image (as a footer or caption) and the accompanying script documentation page. This is both a legal requirement (many datasets are licensed under terms that require attribution) and an editorial standard — readers should know where the data comes from so they can assess its reliability and seek updates.

Required attribution by data source:

Where to place attribution:

• In generated images (PNG/SVG): Include a text footer at the bottom of the image listing all data sources. Use small italic text (5–7 pt) so it doesn’t dominate the visual but remains legible when printed.
• In script documentation pages (script-*.md): Include a “Data Sources and Attribution” section listing each dataset, its URL, license, and the required attribution text.
• In the parent document: When a COMPUTED DATA section references generated tables or images, the data sources are documented in the script page; no need to repeat full attribution in the parent doc.

Recommended legend conventions: Where datasets provide recommended legend symbology or classification schemes (e.g., LCDB land cover classes, NZSC soil orders), prefer using the official legend categories and color schemes. This aids consistency with other publications and makes the data more recognizable to domain specialists. Deviations from recommended legends should be noted and justified.

5. REVIEW AND VERSIONING

5.1 Pre-catastrophe review

All documents should be reviewed by NZ domain specialists before final publication. AI-generated content, no matter how carefully produced, will contain errors of fact, emphasis, and judgment that domain experts will catch.

5.2 Version control

Documents are versioned and dated. Each version should note what changed and why. The catalog itself is versioned separately from individual documents.

5.3 Living documents

The Recovery Library is not a static publication. During the AI facility’s operational life, documents should be updated as conditions change, new information becomes available, and field experience reveals errors or gaps. The printing schedule should account for revised editions of high-priority documents.

6. COMMON ERRORS TO AVOID

A checklist for document authors and reviewers:

• Have I stated any numbers without a source or stated basis?
• Have I described a substitution without acknowledging the performance gap?
• Have I assumed institutional success without noting the assumption?
• Have I used rhetoric (“uniquely positioned”, “most valuable”, “critical”) where plain statement would serve?
• Have I presented peacetime capabilities as though they apply under crisis conditions?
• Have I accounted for consumable depletion in the processes I describe?
• Have I checked whether the materials I specify are actually available in NZ?
• Have I distinguished between what NZ can do now and what requires years of development?
• Have I considered what happens if trade with Australia or other regions does or doesn’t materialize?
• Have I noted the phase(s) this document serves?
• Have I been honest about what I don’t know?
• Have I assessed the actual urgency of recommended actions based on real depletion rates, not rhetoric?
• Am I recommending spending political capital proportionate to the actual cost of delay?
• Have I distinguished between actions that genuinely need days vs. weeks vs. months?
• Are my arguments for governance, rights, and social inclusion grounded in practical recovery value — not political or philosophical fashion?
• Have I avoided scare framing, emotional appeals, or pandering to current political sensibilities?
• If I reference traditional or cultural knowledge systems, is the content grounded in specific, actionable recovery contributions — not included as a compliance checkbox?
• Have I avoided defensive framing (“this is not a historical curiosity,” “not cultural symbolism,” “not merely historical,” “not an afterthought,” “is not optional,” “not tokenistic”)? If something is valuable, have I stated its value directly and let the facts speak? This pattern is particularly prevalent around indigenous knowledge topics — LLMs produce it at very high rates due to training data from NZ institutional documents that use the Vision Mātauranga “bolt-on” template.
• If I recommend maintaining a norm (democracy, media freedom, minority inclusion), is the argument functional and practical?
• If this document involves resource allocation under scarcity, have I confronted the hardest allocation questions explicitly — not deferred them to “local judgement”?
• If differential allocation by age, condition, or social role is recommended, is the rationale stated in terms of recovery outcomes?
• For consumable resources that will run out, have I described tapering protocols — who loses access, in what order, and what supportive care is available during withdrawal?
• If I state multiple allocation principles, do they contradict each other under scarcity? If so, have I explained how the conflict is resolved?
• Have I considered how allocation decisions will be received by the population, and noted where social acceptability diverges from technical optimality?
• Are policy-relevant sections (Recommended Actions, Economic Justification where warranted) placed right after the Executive Summary, not buried at the end?
• Have I avoided including inline disclaimers in the markdown source? (The HTML template handles disclaimers.)
• Are my assumptions about infrastructure (grid, telecom, roads) consistent with the shared baseline scenario?
• Have I clearly labeled contingencies as contingencies, not as the expected trajectory?
• Have I traced the full dependency chain for any manufacturing or production process described?
• Have I avoided the “just” problem — are there any steps described as simple that actually require significant infrastructure?
• For staged technical development, have I described the stages explicitly?
• For major projects, have I included an economic justification with person-years and breakeven? (See §2.7 for when a full section, brief note, or omission is appropriate.)
• Have I mechanically verified every cross-reference (Doc #NNN) against the catalog? LLMs assign these from memory and get them wrong at very high rates — this is the single most common error in the corpus.

7. GENERATED REFERENCE DATA AND GRAPHICS

This section covers the technical conventions for the generated reference data (tables, maps, charts) that accompany many Category 2 reference documents and some navigation documents. These are implementation details for contributors working on the data pipeline — not editorial standards for document authors.

7.1 The three-file pattern

Generated reference data follows a three-file pattern:

1. scripts/generate_[name].py — Python script that fetches/computes data and produces output. Runs from the project’s venv (scripts/.venv/). Must be deterministic: same input data produces same output.
2. tables-[name].md — Generated markdown containing tables and/or image references. Built by the script, rendered to HTML by build.sh. This is what the reader sees.
3. script-[name].md — Documentation page containing the full script source code, data source URLs, attribution, and methodology notes. This lets a technically skilled reader reproduce or update the data.

Documents link to their generated data via a COMPUTED DATA section placed immediately after the document header and before the Executive Summary:

## COMPUTED DATA: [TOPIC NAME]

**[View the [Data Type] →](../tables-[name].html)** — Brief description of the data.

**[View the generation script →](../script-[name].html)** — Python source code and data sources.

Generated data serves as a proof of concept — it demonstrates the data pipeline, shows what production-ready reference pages would look like, and provides immediately useful sample data. It is not exhaustive. Script documentation pages should note the gap between the sample and what a production run would produce.

7.2 Data caching and fetching

Raw data fetched from external APIs should be cached locally in scripts/data/ as GeoJSON or JSON files. Scripts should load cached data rather than hitting APIs on every run. The fetch step (downloading raw data) should be separate from the generation step (processing data into output) where practical, so that generation can be re-run without network access.

Key data sources and access patterns:

ArcGIS API quirks: Some NZ government ArcGIS proxies (notably MPI) block f=geojson responses — use f=json (Esri JSON) and convert client-side. Esri JSON polylines use features[].geometry.paths arrays; convert to GeoJSON MultiLineString format.

7.3 Map specifications

Image format and resolution: - PNG at 200 DPI minimum (sufficient for A4 laser printing) - Figure size: approximately 10 × 12 inches for full-country maps - White background, clean styling

NZ country maps: - GADM v4.1 Level 1 boundaries for coastline and regional shading - Equirectangular projection with latitude-corrected aspect ratio (cos(lat)) - Legend positioned to avoid obscuring populated regions (upper left or lower left preferred)

Harbor approach charts: - Use OpenStreetMap coastline (via Overpass API) for harbor-scale detail — GADM boundaries are too coarse - Bathymetry contours from MPI service; note 10m contour intervals (coarser than official charts) - Navigation features, approach channels, geographic labels, compass rose, scale bar in nautical miles - Always include “PROTOTYPE — NOT FOR NAVIGATION” caution and official LINZ chart reference

Data overlay maps (flora, fauna, soil, geology, infrastructure): - Neutral land base layer first, then data overlays with moderate alpha (0.4–0.6) - When fetching polygon data from ArcGIS FeatureServers, fetch raw geometry and simplify client-side using Douglas-Peucker (epsilon ~0.003° ≈ 300m at NZ latitudes). Server-side simplification via maxAllowableOffset produces angular, blocky results. - For large datasets, filter by area threshold before rendering (>10 km² for common types, >1 km² for less common, >50,000 m² for rare/important types)

Star charts: - Circular polar projection centered on the South Celestial Pole - Stars plotted as circles scaled by magnitude - Constellation lines for key navigational asterisms; horizon circle for observation latitude

This guide is itself a living document and should be updated as editorial standards evolve through the process of writing and reviewing library entries.