CR-2026-04-10: Codex Formatting Refactor

Change Request

Field Value

CR ID

CR-2026-04-10-codex-formatting-refactor

Title

Codex Formatting Refactor — Per-Command Code Blocks, Tables to Code, STD-016 Compliance

Requested By

Evan Rosado

Date Submitted

2026-04-10

Priority

P1 — documentation quality

Category

Documentation Standards

Environment

domus-captures (codex partials + examples)

Context

universal

Status

Planned

Business Justification

Codex entries exist to be copied and used. When commands are buried in a single monolithic code block or hidden in table cells, the reader cannot copy the specific command they need. This violates STD-016 (Codex Entry Format) which requires:

  • One code block per command or logical unit

  • .Title labels on every code block explaining what it does

  • Real output shown where applicable

  • No commands in table cells — tables are for metadata, not executable content

Anti-Patterns Found

Monolithic code blocks

Multiple unrelated commands in one [source,bash] block. The reader must read the entire block, identify the command they need, and manually select just those lines.

Example: PowerShell AD DNS codex — 20+ commands in a single block covering import, query, add, remove, scavenge, and test operations.

Commands in table cells

Executable commands placed in AsciiDoc table cells where they cannot be copied with a click. Tables should describe relationships and metadata — not hold runnable code.

Missing .Title labels

Code blocks without a descriptive .Title — the reader must read the code to understand what it does before deciding if they need it.

Scope

Inventory

Category Files Lines

Codex Partials

494 files

~22,650 lines

Codex Examples

272 files

~69,364 lines

Total

766 files

~92,000 lines

In Scope

  • Split monolithic code blocks into per-command blocks with .Title labels

  • Move commands from table cells to proper [source,bash] blocks

  • Add .Title labels to untitled code blocks

  • Preserve all existing content — refactor format, not substance

  • Respect files that already follow STD-016 (many do — e.g., glab-cli, many bash entries)

Out of Scope

  • Writing new codex content

  • Changing command syntax or output

  • Restructuring the codex directory hierarchy

  • Modifying .sh or .py script files (these are already properly formatted)

Approach

Triage First

Not all 766 files need work. Many already follow STD-016 (the glab-cli entry is a good example). The first step is to identify which files have anti-patterns:

# Find files with code blocks longer than 30 lines (likely monolithic)
find docs/modules/ROOT/{partials,examples}/codex/ -name "*.adoc" \
  -exec awk '/^\[source,/{n=0; block=1} block{n++} /^----$/ && block{if(n>30) print FILENAME": "n" lines"; block=0}' {} \;

# Find files with commands in table cells
grep -rl '| `[a-z]' docs/modules/ROOT/{partials,examples}/codex/ --include="*.adoc"

Per-File Process

For each file that needs refactoring:

  1. Read the file — understand the sections and commands

  2. Identify monolithic blocks — blocks with multiple unrelated commands

  3. Split each command into its own [source,bash] block with a .Title

  4. Move any table-cell commands to proper code blocks

  5. Verify the content is unchanged (same commands, same output)

  6. Build verify

Quality Standard (STD-016)

Every command entry should look like:

.List DNS zones on the domain controller
[source,powershell]

Get-DnsServerZone -ComputerName home-dc01 | Select-Object ZoneName, ZoneType, DynamicUpdate

.Add an A record
[source,powershell]

Add-DnsServerResourceRecordA -ZoneName "inside.domusdigitalis.dev" ` -Name "newserver" ` -IPv4Address "10.50.1.100" ` -ComputerName home-dc01









NOT:








[source,powershell]
----
# List zones
Get-DnsServerZone ...

# Add A record
Add-DnsServerResourceRecordA ...

# Remove record
Remove-DnsServerResourceRecord ...
----














Schedule












Phase
Scope







Phase 0


Triage — identify files needing refactoring, estimate per-category scope






Phase 1


PowerShell codex (known issues — AD, certificates, system)






Phase 2


Bash codex entries with monolithic blocks






Phase 3


Linux/networking codex entries






Phase 4


Security/ISE/SIEM codex entries






Phase 5


Remaining categories






Phase 6


Validation — full audit of all 766 files against STD-016













Personnel












Role
Name







Implementer


Evan Rosado (with Claude Code)






Reviewer


Self-review — build clean, content unchanged, per-command blocks with titles