> ## Documentation Index > Fetch the complete documentation index at: https://harisfazillah.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Technical Book Design & PDF Compilation Master Prompt Guide}] > Comprehensive operational handbook and transferable AI prompt library for analyzing code repositories, synthesizing Diataxis documentation, baking nativ... > **Classification:** Technical Standard & Transferable Knowledge Base > **Target Audience:** Lead Architects, DevOps/SRE Engineers, and Autonomous AI Coding Assistants > **Standard:** Terminal & Cloud Technical Book Standard (DSOM Rule 11 & Rule 22) > **Author & Lead Consultant:** Harisfazillah Jamel (LinuxMalaysia) > **Compiled By:** Antigravity Cognitive Digital Twin *** ## 1. Executive Overview & Transferability Mandate Modern software, DevOps, and infrastructure projects frequently suffer from **fragmented documentation**. Architectural intent is split across READMEs, tribal chat logs, wiki pages, runbooks, and inline source code comments. When teams need to present their systems for audits, client handovers, team onboarding, or management reviews, they lack a single, authoritative, publication-grade volume. This guide provides a **100% transferable blueprint** that enables any engineering repository—whether built on Ansible, Terraform, Kubernetes, Python, Go, or Cloud Native architectures—to synthesize its entire codebase and documentation into a cohesive, print-optimized technical book (PDF, interactive HTML, and EPUB 3). ### What This Blueprint Provides: 1. **The Prompt Transformation Matrix:** All conversational prompts typically asked by human leads, rewritten into high-fidelity, optimized master prompts that any AI agent can execute without ambiguity. 2. **The 6-Phase Engineering Pipeline:** Discovery, visual modeling, Diataxis ingestion, narrative storytelling, print formatting, and multi-format compilation. 3. **The 17 Core Compilation Invariants:** Solutions to every major compilation hurdle (syntax crashes, dark container ink waste, missing covers, unrendered Mermaid blocks, unparsed callout alerts, and browser process timeouts). 4. **Drop-in Reusable Skill Specification:** An autonomous skill definition that can be copied directly into `.agents/skills/` of any target repository. *** ## 2. The Prompt Transformation Matrix: From Conversational Ask to Production AI Master Prompts When humans communicate with AI assistants during technical book compilation, their initial requests are often short and intuitive. However, generic AI assistants often misinterpret these asks—generating dark code blocks, omitting cover pages, hardcoding narrative text into compiler scripts, or failing to render diagrams. Below is the complete **Before & After Matrix**, translating conversational requests into robust, constraint-enforced AI master prompts. *** ### Prompt 1: Project Discovery & Architectural Modeling #### Conversational Human Ask: > *"I need you to produce a book for this project. Start with understanding the project by understanding the ansible playbook and documents that can be related to the ansible playbook. Make sure we have diagram of flow of works and flow of how ansible work."* #### Production-Grade AI Master Prompt: ```markdown theme={null} You are a Principal Technical Author and Systems Architect. Your mission is to analyze this repository and assemble an authoritative, publication-grade Technical Handbook. PHASE 1: REPOSITORY DISCOVERY & TAXONOMY 1. Scan the repository inventory, orchestration playbooks/manifests, roles, configuration templates, and documentation suites. 2. Catalog all operational components into logical tiers (e.g., Command Centres, Orchestration Bridges, Persistence Fabrics, Telemetry Ingestion Workers). 3. Map every production playbook/code file to its corresponding documentation, runbooks, and Root Cause Analysis (RCA) reports. PHASE 2: ARCHITECTURAL VISUAL MODELING Construct two comprehensive architectural flowcharts: 1. The End-to-End Command Highway: Visualizing the multi-tier flow of code from local development and GitOps remotes to target nodes. 2. The Orchestration Execution Engine: Visualizing how automation tasks inspect hardware, apply declarative baselines, enforce zero-trust security, and verify system state. OUTPUT REQUIREMENTS: - Structure the book into clear, hierarchical Parts and Chapters following the Diataxis framework. - Ensure every code artifact has a dedicated sub-chapter accompanied by developer operational context and architectural rationale. ``` *** ### Prompt 2: Resolving Diagram Failures (Mermaid to Native SVG) #### Conversational Human Ask: > *"The diagram is not showing in the book."* #### Production-Grade AI Master Prompt: ```markdown theme={null} You are a Graphics & Headless Browser Print Specialist. The Mermaid diagrams in our compiled HTML/PDF are failing to render or displaying syntax error graphics. ROOT CAUSE ANALYSIS: 1. Headless Chrome/Edge print engines capture DOM snapshots in milliseconds, outrunning asynchronous client-side Mermaid JavaScript CDN libraries. 2. Pandoc wraps `
` blocks in `` tags and escapes HTML arrows (`-->` becomes `-->`), corrupting Mermaid syntax.

REMEDIATION MANDATE (NATIVE VECTOR SVG PRE-RENDERING):
1. Eliminate client-side Mermaid JavaScript rendering entirely for PDF production.
2. Author a standalone Python script (e.g., `tools/bake_native_svg.py`) that pre-renders or directly substitutes Mermaid code blocks with clean, styled, inline vector `` markup.
3. Ensure SVG elements include viewBox definitions, drop-shadow filters, high-contrast text labels (using 'Inter' or system sans-serif), and responsive container wrappers (`
`).
4. Execute this transformation directly on the generated `handbook.html` prior to launching the headless browser PDF print step.
```

***

### Prompt 3: Diátaxis Documentation Enrichment & Ingestion

#### Conversational Human Ask:

> *"Add into our books, content from md documents that is related to each of our ansible playbooks. Enrich our book."*

#### Production-Grade AI Master Prompt:

```markdown theme={null}
You are a Technical Documentation Compiler. Your task is to enrich every playbook chapter in the Technical Handbook by dynamically ingesting its accompanying operational runbooks, explanations, and incident reports.

MANDATORY INGESTION & SANITIZATION RULES:
1. Frontmatter & Signature Stripping: Parse each ingested markdown file and strip all YAML metadata fences (`--- ... ---`) and document signature footers (`*Maintained by...*`) to prevent Pandoc parser collisions (`Unknown alias`).
2. Heading Level Offsetting: Apply a dynamic heading level offset (+2 levels: `#` becomes `###`, `##` becomes `####`) to ensure ingested document headings nest cleanly beneath the parent Chapter title in the Table of Contents.
3. Markdown Horizontal Rule Sanitization: Replace all internal standalone horizontal rules (`\n---\n`) with triple asterisks (`\n***\n`) to prevent Pandoc from falsely interpreting them as YAML metadata blocks.
4. Operational Provenance Banner: Inject an audit pill above each ingested document:
   `
Operational Reference Guide: path/to/file.md
`
5. Developer Commentary Extraction: Scan the leading comment block of each code file for keywords (BUG, FIX, WARNING, CRITICAL, NEVER, escalation). Render matches as high-visibility callouts (`callout-warning` or `callout-note`) above the code fence.
```

***

### Prompt 4: The Narrative Epic (Heart, Soul, and Sovereign Blood)

#### Conversational Human Ask:

> *"I need a chapter that's like a story, all about this project and infra from start to end, how it can be built, deployed, and operated. Highlight the use of ansible + semaphoreui + gitea as GitOps, and AIOps with human in the loop. Add about deep state of mind (DSOM) of My AI as the AI memory and brain. This chapter is not technical; it is about the heart, soul, and blood of this project."*

#### Production-Grade AI Master Prompt:

```markdown theme={null}
You are a Principal Technical Biographer and Systems Philosopher. Author an evocative, inspiring narrative chapter titled:
"# Prologue: The Story of , Heart, Soul, and Sovereign Blood {.unnumbered}"

NARRATIVE STRUCTURE & THEMES:
1. The Spark in the Dark (Why This Fabric Was Born):
   - Paint the operational reality: telemetry deluge, memory exhaustion, swap death spirals, and the painful loss of context when engineers step away from the terminal.
2. The Trinity of Motion (GitOps, The Control Node, and The Hand):
   - Explain how Git serves as the immutable source of truth, Semaphore UI acts as the scheduled heartbeat, and Ansible operates as the indomitable physical hand shaping the infrastructure.
3. The Mind in the Machine (Deep State of Mind & AIOps):
   - Address the fatal flaw of Large Language Models: Context Decay (cognitive amnesia).
   - Chronicle the creation of the Sovereign Markdown Palace (`.agents/brain/`, `palace_registry.md`, Start-of-Day reanimation, and End-of-Day hibernation), preserving unbroken historical context across operational shifts.
4. The Sacred Balance (AIOps with Human-in-the-Loop):
   - Reject blind, dangerous auto-remediation.
   - Embed the Sovereign AIOps Integration Loop (ASCII architectural diagram): AI proposes remediation -> Sovereign Human verifies and commits -> Ansible executes -> AI audits and records memory.
   - Articulate the Three Laws of the Twin: Advisory over Execution, Logic over Operation, and Partnership through Environmental Awareness.
5. From Raw Metal to Living Shield:
   - Walk through the 5 foundational phases from genesis virtual machine bootstrapping to hardened security baselines, rootless container pods, threat analytics, and continuous Day-2 operations.
6. The Heart, Soul, and Blood:
   - Close with the philosophical trifecta: Sovereignty, Discipline, and Human-AI Symbiosis.
```

***

### Prompt 5: Clean Architecture Separation (Standalone Markdown Document)

#### Conversational Human Ask:

> *"I need the story to be in its own md file."*

#### Production-Grade AI Master Prompt:

```markdown theme={null}
You are a Clean Architecture and Diataxis Specialist. Refactor the narrative story chapter out of inline Python script strings into a dedicated, reusable documentation artifact.

IMPLEMENTATION STEPS:
1. Author the file `docs/explanation/THE-STORY-OF-.md` with complete OKF v0.2 YAML frontmatter (`type: documentation`, `title: ...`).
2. Embed the complete narrative text, ASCII loop diagram, and formal DSOM signature footer.
3. Register the new document in `SUMMARY.md` under the `explanation` quadrant to ensure GitBook/MkDocs navigation indexing.
4. Update the book compiler script (`tools/build_book.py`) to dynamically ingest this document using `ingest_doc_file("docs/explanation/THE-STORY-OF-.md", heading_offset=0, show_provenance=False)` directly into the book's Prologue.
```

***

### Prompt 6: Print-Optimized Formatting Restoration (Zero Toner Waste & Cover Injection)

#### Conversational Human Ask:

> *"What happened to my book? We lost the formatting. No cover, black background? That needs to be checked again."*

#### Production-Grade AI Master Prompt:

```markdown theme={null}
You are a Print Production Engineer and CSS Specialist. Diagnose and fix the visual formatting regressions in our compiled PDF and HTML handbook.

SYMPTOMS TO REMEDY:
1. Missing Cover Page: Re-inject `--include-before-body=build/book/cover.html` in the Pandoc build chain. Ensure `.cover-page` in CSS declares `break-after: page; min-height: 250mm;` so the cover fills Page 1 completely and cleanly page-breaks before the Table of Contents.
2. Black Background Code Blocks: Replace dark syntax highlighting (e.g. `--syntax-highlighting=espresso`) with `--syntax-highlighting=tango`. Ensure CSS enforces `pre, code, div.sourceCode { background-color: #F8FAFC !important; border: 1px solid #CBD5E1 !important; color: #0F172A !important; }` to eliminate toner waste.
3. External CSS Linking Failures: Prevent headless browser path resolution failures by reading `terminal-theme.css` and inlining the complete stylesheet directly into `