first commit

software-development/systematic-debugging/references/jinja2-template-inheritance.md

@@ -0,0 +1,39 @@
+# Jinja2 Template Inheritance Debugging
+
+## Silent Block Omission
+
+**Symptom**: Child template's `{% block X %}` content is completely absent from rendered page. No error, no warning.
+
+**Root cause**: Parent template (base.html) does NOT define `{% block X %}{% endblock %}`. Jinja2 silently ignores child blocks that don't have a corresponding parent block definition.
+
+**Detection**:
+```bash
+# Check if parent template defines the block
+grep -n "block_name" templates/base.html
+
+# Check rendered output for the expected content
+curl -s https://site/page | grep -o "expected_js_variable"
+```
+
+**Example from ephron.ren**:
+- `blog/templates/admin/collection_edit.html` defined `{% block extra_scripts %}` with critical JavaScript
+- `blog/templates/base.html` had `{% block extra_styles %}` and `{% block content %}` but NO `{% block extra_scripts %}`
+- Result: All JavaScript for article selection was silently omitted from the page
+- Other services (prompt, auth, canvas, home) all had `extra_scripts` defined in their base templates
+
+**Fix**: Add the missing block definition to the parent template:
+```html
+<!-- Before </body> -->
+{% block extra_scripts %}{% endblock %}
+```
+
+**Prevention**: When creating child templates, verify the parent template defines all blocks you intend to override. Use `grep` to check.
+
+**Cross-service consistency check**: When debugging template issues in multi-service sites, compare the base templates across all services to find missing block definitions:
+```bash
+for svc in blog auth canvas prompt home; do
+  echo "=== $svc ==="
+  grep -n "block.*endblock\|{% block" $svc/templates/base.html 2>/dev/null || \
+  grep -n "block.*endblock\|{% block" $svc/templates/_design_system/page_shell.html 2>/dev/null
+done
+```