Chapter Authoring Guide

This guide is the operational checklist for anyone drafting or revising a chapter of The Transformed Security Architect, whether a human contributor or an AI-assisted writer. Read BOOK_BLUEPRINT.md for the chapter brief, SERIES_FOUNDATIONS.md for the conclusions of Books 1–5 it builds on, AUTHOR_PERSONA.md for voice, and STYLE_GUIDE.md for language rules before writing.

File layout

  • Chapter file: docs/NN_short_name.md, where NN is the two-digit chapter number from book_index.json.
  • Diagram source: docs/images/diagram_NN_topic.mmd. The rendered docs/images/diagram_NN_topic.png is produced by python3 scripts/check_mermaid_diagrams.py --write-missing and committed alongside the source.
  • No YAML front matter. The first content line is the H1 title with a Pandoc anchor: # Title {#anchor}.

Required structure

# Chapter Title {#chapter-anchor}

Opening paragraph that states what the chapter covers, why it matters to the reader and which of the four shifts it concerns.

![Alt text describing the diagram](images/diagram_NN_topic.png)

*Figure NN.1: One-sentence caption.*

## First major section

Prose. Use ### subsections where they improve clarity.

## Further sections ...

### Across the usage modes

### Nordvik Region and Hansa Mutual

## Summary

Three to five paragraphs that recap the chapter, name the shifts it concerns and point to the next chapter.

## Sources

1. **Author, A. (Year).** *Title.* Publisher. ([N, Author, Year](30_references.md#source-N))

Rules

  1. Language. Oxford-standard British English. Headings in sentence case except for proper nouns the terms AI Architecture and Architecture as Code, and the names of the four shifts. Every heading starts with a capital letter.
  2. Length and weighting. Measured as prose (excluding code blocks and tables): numbered narrative chapters 3,600 to 5,500 words, companion chapters 3,500 to 6,500 words, unless the brief says otherwise. A chapter far below the range should be expanded with substance, not padding. A chapter that grows beyond about 6,500 words, or a single section beyond about 2,500 words that treats a distinct subject, should be split into a companion chapter of its own. The brief records each such weighting decision.
  3. Diagrams. At least one Mermaid diagram per chapter. Use graph, flowchart, sequenceDiagram, quadrantChart, mindmap, or classDiagram. Apply Kvadrat classes (:::kv-primary, :::kv-accent, :::kv-highlight, :::kv-muted, :::kv-pattern) to key nodes. No emojis. Labels in British English. Keep node text short so that diagrams render at 1400 by 900 pixels. Do not use quotation marks inside node labels unless necessary, and avoid parentheses in labels (use square-bracket node syntax with plain text).
  4. Code. At least one fenced code block with a language identifier (yaml, json, python, bash, rego, hcl, sql). YAML and JSON must parse. Keep examples under 60 lines; longer versions belong in Appendix A.
  5. Citations. Cite only sources that exist in 30_references.md, in the form ([N, Author, Year](30_references.md#source-N)), which renders as (N, Author, Year). Run python3 scripts/format_citations.py --fix to derive the author label and year from the bibliography; see STYLE_GUIDE.md for the label rules. Do not invent sources. Do not add entries to 30_references.md from a chapter branch; propose additions to the editorial team instead.
  6. Sources section. The final section is ## Sources, a numbered list, one entry per cited source, in the format shown above, with the source link at the end of each entry.
  7. Europe first. Include at least one concrete European or public-sector consideration. Attribute legal statements to the instrument and article. Frame them as architectural implications, not legal advice.
  8. Codify it. Show at least one artefact that belongs in version control.
  9. Practical guides. Where a chapter prescribes protective or operational measures, include at least one practical guide the reader can follow: a ### Practical guide: <task> subsection with the purpose, the roles involved, numbered steps, a codified artefact where it helps, and a short definition of done. Prefer concrete defaults (time limits, thresholds, configuration settings) over general advice, and say when a default must be adapted to the organisation's risk appetite.
  10. Worked examples in the chapter. Show, do not only tell. Where a chapter recommends an artefact (a prompt, an agent skill, an agent or connector configuration, a policy, an AI Decision Record, a forum's terms of reference, a checklist), include at least one complete, realistic example in that chapter, at the point where the concept is explained, as a ### Worked example: <artefact> subsection marked as illustrative. Examples live in the chapter they illustrate, as in Architecture as Code; Appendix A holds only fuller versions of artefacts that a chapter introduces. Use the shared fictional organisations Nordvik Region (a regional public authority in a Nordic EU member state) and Hansa Mutual (a multinational mutual insurance group headquartered in Germany, operating inside and outside the EU) for continuity, keeping every fact consistent with their canonical profiles in docs/EXAMPLE_ORGANISATIONS.md, and make sure every YAML and JSON block parses. Every narrative chapter also ends, before its Summary, with a short ### Nordvik Region and Hansa Mutual subsection that states how the chapter's subject plays out for each organisation and where they differ; Chapter 25 follows both through a year in the role and Chapter 26 draws these together into a conclusion for each organisation.
  11. Four shifts as red threads. Chapter 3 defines the four shifts, and every chapter uses them by these exact names: Shift 1, from documents to code; Shift 2, from gatekeeper to boundary designer; Shift 3, from periodic to continuous, at machine speed; Shift 4, from sole author to conductor of an AI team. Every chapter in Parts II to V names, in its opening and its Summary, which of the four shifts it concerns, by the exact names; Part I frames the shifts and Part VI concludes them. Every narrative chapter has an ### Across the usage modes or ### Across the autonomy levels subsection where the subject differs by mode or level, normally a compact table. Use the usage modes by their exact names (Mode 0 Ambient AI, Mode 1 Conversational assistants, Mode 2 Embedded workplace assistants, Mode 3 Agentic work tools, Mode 4 Built AI applications, Mode 5 Autonomous production agents; AI Governance and AI Platform and Security, Chapter 2) and the autonomy levels by theirs (Level 0 Advisory, Level 1 Assisted, Level 2 Supervised, Level 3 Bounded, Level 4 Autonomous; AI Red Team, Chapter 6). The mode describes how the AI is deployed and whose identity it uses; the level describes who decides each action. Level 4 is never used for irreversible actions.
  12. Observable, expected, speculation. Every statement about the future of the role or the technology carries one of the three labels of AI Governance, Chapter 22: observable (happening now and documented), expected (supported by a stated trend or a decided instrument), or speculation (plausible but unsupported by present evidence). The author's own projections are confined to Chapters 23 and 27 and labelled as such; elsewhere, attribute forecasts to the source that makes them and label them.
  13. Cross-references. Refer to other chapters of this book as "Chapter N". Refer to the earlier volumes in plain text, without a link, as "Architecture as Code (Chapter N)", "AI Governance, Chapter N", "AI Platform and Security, Chapter N", "AI Red Team, Chapter N" and "AI Threat, Chapter N", using the tables of contents in SERIES_FOUNDATIONS.md, and cite them as (Nordqvist, 2025) or (Nordqvist, 2026). Summarise just enough of an earlier volume's content that the reader is not left with a gap, and state explicitly when a chapter builds on a conclusion recorded in SERIES_FOUNDATIONS.md. The series builds strictly in publication order, so that there is no circular reasoning between the books: Architecture as Code (Book 1) refers to no other volume, AI Governance (Book 2) only to Book 1, AI Platform and Security (Book 3) only to Books 1–2, AI Red Team (Book 4) only to Books 1–3, AI Threat (Book 5) only to Books 1–4, and The Transformed Security Architect (Book 6) only to Books 1–5. Never refer to a later volume. Every new claim either cites an external source or is the book's own conclusion, drawn in a conclusions section or summary; a reference to an earlier volume builds on that volume's conclusions and never stands in for an external source for a factual claim. tests/test_series_references.py enforces the order.
  14. Defensive security only. This is a book about the people who design defences, and the rule is strict. Describe adversary behaviour by technique (MITRE ATT&CK, MITRE ATLAS, OWASP) at the level needed to design boundaries, controls, detections, tests and exercises. Never include exploit code, malware, payloads, prompt-injection or jailbreak strings, phishing templates, evasion techniques or step-by-step intrusion instructions, even as illustrations. Every offensive activity the book describes, such as a red-team exercise or a security chaos experiment, is authorised in writing, scoped, run against the organisation's own or contracted systems, logged, and closed with a defensive improvement. Code examples are role charters, control catalogue entries, policy-as-code rules, containment profiles, permission and mandate manifests, competence records, decision records and evidence manifests.
  15. Voice. No marketing language, no hype, no anthropomorphism, no rhetorical questions as transitions, no filler openers. Active voice, imperative mood for instructions.

Before you submit

python3 -m pytest tests/test_completeness.py tests/test_consistency.py tests/test_reference_consistency.py -q
python3 scripts/check_mermaid_diagrams.py --write-missing
python3 scripts/audit_references.py