Chapter Authoring Guide

This guide is the operational checklist for anyone drafting or revising a chapter of AI Blue, 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–7 it builds on, EXAMPLE_ORGANISATIONS.md for the blue team profiles of Nordvik Region and Hansa Mutual, 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 five blue team functions it concerns (for example **B2 Detect** and **B3 Investigate**).

![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 ...

## The debate                       (Chapters 7, 21, 23 and 24 only; see rule 16)

### The case for concern

### The case for calm

### Where the positions meet

### What can be done

## Verdict                          (chapters with a debate only)

### Across the usage modes          (or ### Across the degrees of delegation)

### Nordvik Region and Hansa Mutual

## Summary

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

## Sources

1. **Author, A. (Year).** *Title.* Publisher. ([N, Author, Year](31_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 five blue team functions and the autonomy levels. Every heading starts with a capital letter. No em-dashes in prose; use a colon, a comma or a new sentence.
  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). Diagrams show people as roles (analyst, incident commander, SOC lead, works council), never as faces or caricatures.
  4. Code. At least one fenced code block with a language identifier (yaml, json, python, bash, rego, 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 31_references.md, in the form ([N, Author, Year](31_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 31_references.md from a chapter branch; propose additions to the editorial team instead. Verify every article number, recital and judgment against its live text (EUR-Lex for EU law, the official national gazette or court database for national law and case law) before citing it, and list in your report every claim you could not verify.
  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 (for example NIS 2 Articles 20, 21 and 23; DORA Articles 5 and 17 to 19; GDPR Articles 32 to 34; AI Act Articles 14, 26 and 73; Regulation (EU) 2024/2847, Article 14). Frame them as organisational and architectural implications, not legal advice. Where national law differs, say which member state's law the example uses.
  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 (analyst, detection engineer, incident commander, SOC lead, CISO, privacy officer, employee representative), numbered steps, a codified artefact where it helps, and a short definition of done. Prefer concrete defaults (time limits, thresholds, sampling rates, review intervals) over general advice, and say when a default must be adapted to the contract, the works agreement or the organisation's risk appetite.
  10. Worked examples in the chapter. Show, do not only tell. Where a chapter recommends an artefact (a detection record, a case record, a playbook manifest, a hunt record, a post-incident review, a mandate manifest, a delegation profile, a role charter, a policy, an AI Decision Record, a contract annex, 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; 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 and blue team profiles in docs/EXAMPLE_ORGANISATIONS.md; a new fact goes into the profile in the same change. Use the identifier ranges of this book: AIDR-0700 to AIDR-0749 for Nordvik Region and AIDR-0750 to AIDR-0799 for Hansa Mutual, and DET-*, CASE-*, PBK-*, HNT-*, PIR-*, MND-*, DLG-*, ROLE-* and CMP-* for the records. 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 26 follows four people through a year on the blue team (Karin Lund at Nordvik Region; Piotr Nowak, Lena Vogel and Thomas Brandt at Hansa Mutual, as EXAMPLE_ORGANISATIONS.md profiles them), and Chapter 27 draws the chapters together into a conclusion for each organisation.
  11. Five blue team functions as red threads. Chapter 2 defines the five blue team functions, and every chapter uses them by these exact names: B1 Anticipate (threat intelligence, exposure awareness and the hypotheses that direct detection and hunting); B2 Detect (engineering, running and tuning detections); B3 Investigate (triage, scoping, analysis and forensics); B4 Respond (containment, eradication, recovery coordination, communication and reporting); B5 Learn (post-incident review, purple teaming and improvement). Every chapter in Parts II to V names, in its opening and its Summary, which functions it concerns, by the exact names; Part I defines them and Part VI concludes them. Every narrative chapter has an ### Across the usage modes or ### Across the degrees of delegation subsection, 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). The degrees of delegation reuse the autonomy levels of AI Red Team, Chapter 6, by their exact names, applied per function and action class: Level 0 Advisory, Level 1 Assisted, Level 2 Supervised, Level 3 Bounded, Level 4 Autonomous. The mode describes how the AI is deployed and whose identity it uses; the level describes who decides each action. Level 4 Autonomous is never used for an irreversible B4 Respond action, nor for an action that decides about a named person's access to work; Level 3 Bounded is defined by a codified playbook enforced by a policy decision point outside the model, and a stop path outside the system it stops is part of the design.
  12. Observable, expected, speculation. Every statement about the future of the blue team, of threats or of 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 24 and 28 and labelled as the author's judgement; 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", "AI Threat, Chapter N", "The Transformed Security Architect, Chapter N" and "AI Boss, Chapter N", using the tables of contents in SERIES_FOUNDATIONS.md, and cite them as (Nordqvist, 2025) for Architecture as Code or (Nordqvist, 2026) for Books 2–7. 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 (F1–F91). 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, The Transformed Security Architect (Book 6) only to Books 1–5, AI Boss (Book 7) only to Books 1–6, and AI Blue (Book 8) only to Books 1–7. 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 only. This is a book about the team that defends, and it helps organisations to defend well. Describe adversary behaviour by technique (MITRE ATT&CK or ATLAS identifiers) at the level needed to design detections, controls, decisions and tests. Never include working exploit code, malware, payloads, jailbreak or prompt-injection strings, phishing kits, or step-by-step intrusion instructions, even as illustrations or counter-examples. Offensive activity appears only as authorised, scoped exercises that end in a defensive improvement. Never include instructions for covert monitoring of staff or for defeating the rights of employee representatives. Code examples are detections, playbooks, mandates, policies, records and evaluation configurations, not attack tooling.
  15. Voice. No marketing language, no hype, no anthropomorphism, no rhetorical questions as transitions, no filler openers. Active voice, imperative mood for instructions. Describe analysts, managers and representatives with respect: never call anyone lazy, stupid or replaceable, and describe effects on people by what studies measured.
  16. Constructive debate. Chapters 7, 21, 23 and 24 each contain a debate section with four subsections, in this order: ### The case for concern (the strongest version, in the words and with the evidence of those who hold it), ### The case for calm (the strongest sceptical or optimistic version, treated with the same charity), ### Where the positions meet (the facts and measures both sides accept), and ### What can be done (concrete actions for analysts, leads, CISOs, boards and representatives). It is followed by a verdict that labels the outlook observable, expected or speculation and states what people and organisations can influence. State each position at its strongest; never caricature a position or use labels in place of an argument. Separate what a source reports from interpretation: say what was measured, in whom, over what period and with what method before saying what it means. Keep the author's own projections for Chapters 24 and 28, and end every chapter with something the reader can do. Other chapters may stage a shorter debate in the same form where the brief asks for one.
  17. No anthropomorphism, and "decides" only where a decision was delegated. An AI system enriches, correlates, ranks, flags, drafts, recommends or executes a playbook; it does not suspect, understand, judge or decide in the human sense. Write "the triage agent closed the alert under class SC-02" or "the model scored the host 0.93", not "the AI decided the host was clean". Use "decides" for a system only where a decision was formally delegated to it, and then name, in the same passage or the case record, who delegated it, under which delegation profile and at which level.
  18. Sources the book has not yet verified. The seed bibliography is carried over from AI Red Team. Before a chapter cites a source on the operating model, workforce, wellbeing or practice of security operations that is not in 31_references.md, the researcher verifies it (title, author, date, URL or ISBN) and adds it to the bibliography first.

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