# Agent guidance: `fundamentals-x` This directory holds **Fundamentals** series posts. **Hugo-wide rules** (front matter baseline, cover images, internal/external linking) are in **`hugo/AGENTS.md`** at the site root—follow those for every post, then apply the series rules below. ## Titles, slugs, and folders - **Title (default for new posts):** Use **`Fundamentals of [Topic]`** (natural Title Case—for example *Fundamentals of Software Automation*, *Fundamentals of CI/CD and Release Engineering*). - **Slug and directory:** Prefer **`fundamentals-of-`** so `slug`, the folder name, and the last segment of `url` stay aligned. - **Legacy exception:** A few posts use the **`fundamental-`** folder/slug pattern with titles like **`Fundamental [Topic]`** (for example *Fundamental Software Concepts*, *Fundamental Algorithmic Patterns*). Do not rename those silently; new work should follow **`fundamentals-of-*`** + **`Fundamentals of …`** unless there is a deliberate reason to align with the legacy pattern. ## Front matter (series-specific) In addition to **`hugo/AGENTS.md`:** - **`categories`:** Lead with **`Fundamentals`**, then one or two topical categories (for example Software Engineering, DevOps) consistent with sibling posts. - **`series: Fundamentals`:** Set for long-form series explainers when it matches neighboring articles (some reference-style pages omit it—follow the closest comparable post). - **`diataxis`:** Set when the post fits the site’s Diataxis labeling (often **`explanation`** for understanding-oriented fundamentals; use **`reference`** or **`how-to`** when the article is catalog- or procedure-shaped). Match comparable posts in this directory. ## Body structure and voice - Prefer a clear **introduction** that states what the article covers and who it is for. - For long explainers, use **Prerequisites & Audience**, **Jump to** (anchor links), and **TL;DR** when similar articles in this folder do. - Include the **Laws, bias, and fallacies** section required for this series (see the dedicated heading below). - Include a **References** section: authoritative external links plus internal cross-links to related fundamentals posts (use the **`ref`** shortcode with the target post’s **slug only**, as in **`hugo/AGENTS.md`**). - Use **Diataxis-style callouts** in prose when the rest of the series does (for example a short “Type: **Explanation** …” line). ## Laws, bias, and fallacies (required) **Always include a dedicated section** (for example `## Laws, bias, and fallacies` or a title that fits the article tone) that ties the topic to how people and organizations actually reason and decide. - **Laws and named principles:** Name a few **relevant** laws, heuristics, or named effects (for example industry adages, “X’s law,” Goodhart-style dynamics, Brooks, Conway, etc.—whatever genuinely fits the subject). For each, give a **one-line gist** and **how it shows up** in this article’s domain (teams, tooling, metrics, process). - **Bias:** Call out **cognitive biases** that commonly distort thinking about this topic (confirmation bias, sunk cost, availability, planning fallacy, automation complacency—only what applies). Explain **what goes wrong** and **what to do instead** in context. - **Fallacies:** Mention **logical or rhetorical fallacies** that often appear in arguments about this topic (false dichotomy, appeal to novelty, moving goalposts—again, only what applies). Tie each to **a concrete scenario** readers might recognize. Keep the section **practical**, not a philosophy catalog: every item should answer “so what for someone working in this space?” Order and depth should match article length—short posts get a tight subset; long explainers can use subheadings or the **`cards`** shortcode if comparisons would otherwise become tables (per **`hugo/AGENTS.md`**). ## Glossary (required) **Always render article glossary terms with the shared shortcode and data file**—do not hand-maintain duplicate glossary blocks in Markdown when the terms exist (or should exist) in the canonical glossary. - **Shortcode:** `hugo/layouts/shortcodes/glossary.html` - **Data:** `hugo/data/a-software-fundamentals-glossary.jsonc` (JSON array of objects: `term`, `definition`, `subject`; optional `source`) Each entry’s `subject` is a slug string (for example `ci-cd-and-release-engineering`, `software-development-operations`, `maintainability`). Pass that exact value as `subject` so only rows for that article’s theme are emitted. - Use `subject="all"` only when you intentionally want **every** glossary entry, grouped by subject (rare for a single article). ### Example for LLMs Replace `YOUR_SUBJECT_SLUG` with the `subject` value from the JSONC entries this article should show (must match character-for-character). ```markdown ## Glossary ``` Concrete example (maintainability terms only): ```markdown ## Glossary ``` If a term readers need is missing or the wrong `subject` is used, **add or adjust entries in** `a-software-fundamentals-glossary.jsonc` **and** choose the `subject` slug that matches this article’s glossary section—do not fork definitions only in the post body.