Nigredo and Evidence-First Synthesis: Why Training-Weight Documentation Collapses Into Entropy
In classical alchemy, nigredo denotes the deliberate decomposition of impure matter before any transmutation can begin. Software organizations rarely apply the same rigor to technical writing. When teams deploy coding agents across a repository, they inherit a fast production loop that generates modules, migrations, and configuration files faster than any human architect can review them. To keep the system legible, teams ask the same agents to generate Architecture Decision Records (ADRs), Standard Operating Procedures (SOPs), and executive briefs directly from their parametric memory.
That shortcut creates an illusion of governance. A language model trained on vast web corpora can reproduce the surface cadence of an architecture record or an incident memo on demand. Yet surface fluency masks structural decay. Without live external grounding, every generated artifact drifts toward generic averages: verbose enough to evade quick inspection, ambiguous enough to resist enforcement, and detached from the actual engineering conventions practiced by mature production organizations.
Paracelsus was built to break that pattern at its root. Its core premise is falsifiable and direct: forcing an agent to retrieve, cryptographically verify, and synthesize at least five real primary documents from five distinct organizations before drafting eliminates predictable structural anti-patterns while cutting document bloat dramatically.
Anatomy of Training-Weight Entropy
When an agent drafts a critical engineering document purely from training weights, entropy manifests through concrete, machine-detectable defects rather than vague stylistic flaws. Across Paracelsus production audits and the 2026-11-21 clean-container Docker A/B benchmark, four failure modes recur whenever generation precedes research (Paracelsus Empirical A/B Report, 2026).
⚠️ Failure Mode 1: Specification Sprawl Models equate thoroughness with volume, producing unreviewable 400+ line documents that blow context budgets and stall pull-request reviews. Benchmark Delta: Control produced 443 lines (43.5 KB, +77% over the 250-line ADR ceiling); Paracelsus compressed the decision record into 98 high-density lines.
⚠️ Failure Mode 2: Phantom Status Models invent narrative lifecycle labels (e.g.,
Proposta - Aprovada para Fase 1) that fail deterministic CI regex validation, or omit a formalStatus:field altogether. Enforcement: Strictly enforced enum (DRAFT | PROPOSED | ACCEPTED | REJECTED | DEPRECATED).
⚠️ Failure Mode 3: Timeless Ghost Technical decisions and financial risk briefs decay rapidly without explicit ISO 8601 temporal anchors (
YYYY-MM-DD). Prose dates written in natural language resist deterministic freshness auditing and obscure whether telemetry reflects current load or an obsolete quarter. Enforcement: Mandatory ISO 8601Date: YYYY-MM-DDmetadata gate before write-time approval.
⚠️ Failure Mode 4: Role Blindness Structural mismatch when executive memos default to engineering implementation essays instead of fiscal P&L exposure, explicit separation of verified production telemetry from modeling assumptions, and a binary approval block. Enforcement: Mandatory
Cargo Y -> Cargo Xrole routing viadoc_check_trigger.
Why Static Templates Fail Under Real Constraints
The conventional response to inconsistent documentation is to check a static Markdown template into the repository. Static templates address spelling and heading order, yet they break down along three axes as soon as engineering work spans real organizational complexity.
First, static templates freeze a single organization’s assumptions at a single point in time. A minimal Nygard-style ADR skeleton published in 2011 (Nygard, 2011) captures Status, Context, Decision, and Consequences, which remains necessary but often omits modern invariants demanded in production multi-agent systems: explicit non-goals, phased short/medium/long-term migration triggers, and unverified architectural assumptions.
Second, static templates cannot adapt to sender-to-recipient relationships. An internal communication routed from a CTO to a Backend Developer has a fundamentally different contract from one routed from a Head of Engineering to a CFO or from a CISO to a Pentester. Static files either proliferate into dozens of unmaintained copies or flatten every audience into one lowest-common-denominator outline.
Third, static templates carry no live evidence trail. When a team asks why a template requires a specific section, such as an error-budget escalation trigger or an explicit cost-of-inaction row, a static file offers tradition rather than verifiable engineering precedent.
Paracelsus therefore ships zero static templates as base. Its engine (engine.py) maintains only a compact whitelist registry (DOC_TYPE_WHITELIST) covering official nomenclature, calibrated line limits (250 lines for adr and internal-comms; 500 lines for sop, rfc, srs, and prd; 400 lines default), lifecycle state vocabularies, and baseline domain search queries (Paracelsus MCP Repository, 2026). Every living template is synthesized empirically from current primary sources at bootstrap time.
Gate A: Cryptographic Provenance Before Synthesis
The centerpiece of Paracelsus’s research before generation mechanism is Gate A (doc_check_gate_a). Before the engine permits any template, schema, or local rulebook to be synthesized via doc_synthesize_pack, the agent must satisfy four deterministic invariants verified against <doc_type>/research_procedures/catalog.csv:
| Gate A Invariant | Deterministic Threshold | Enforcement Mechanism |
|---|---|---|
| Primary Document Count | >= 5 verified documents (tier="real") |
Rejects meta-guides or template blogs from counting toward the real-source quorum |
| Organizational Diversity | >= 5 distinct organizations |
Prevents single-vendor echo chambers by enforcing multi-organization convergence |
| Authority & Provenance Backing | Public https:// URL + ISO YYYY-MM-DD date + valid authority_tier |
Rejects localhost/mock URLs, undated posts, anonymous AI spam, and SEO template farms |
| Cryptographic Integrity | 0 SHA-256 hash mismatches |
Computes SHA-256 (NIST FIPS 180-4) on raw captured bytes and re-verifies on disk |
Every registered source via doc_register_source must classify its authority under one of four strict tiers: official_standard, verified_org_handbook, production_postmortem_or_adr, or peer_reviewed_or_docs. Raw source content is persisted locally under research_procedures/raw_sources/ alongside a 19-column provenance ledger (catalog.csv) capturing canonical URL, UTC retrieval timestamp, publication date, license, byte size, verifier identity, and SHA-256 digest (NIST FIPS 180-4, 2015; Paracelsus MCP Repository, 2026).
canonical_url,retrieval_utc,pub_date,authority_tier,byte_size,sha256_digest
https://github.com/microsoft/agent-governance-toolkit/...,2026-11-21T08:12:00Z,2026-01-15,production_postmortem_or_adr,14205,8a9f3e...
https://github.com/aws-samples/sample-agentstorming/...,2026-11-21T08:12:04Z,2026-02-10,production_postmortem_or_adr,18940,41b299...
https://github.com/dapr/dapr/...,2026-11-21T08:12:09Z,2021-07-14,production_postmortem_or_adr,11482,c3d17a...
When doc_check_gate_a evaluates the ledger on disk, it returns a typed deterministic verification contract before doc_synthesize_pack is unlocked:
{
"tool": "doc_check_gate_a",
"doc_type": "adr",
"status": "GATE_A_PASSED",
"verified_primary_sources": 6,
"distinct_organizations": 6,
"quorum_required": 5,
"sha256_mismatches": 0,
"ledger_path": "adr/research_procedures/catalog.csv"
}
In practice, Gate A transforms what the model writes because the model must reconcile concrete structural patterns across independent engineering cultures before drafting. When the Docker A/B benchmark ran Task 1 (multi-agent runtime isolation ADR), Gate A converged on six verified production ADRs: Microsoft Agent Governance Toolkit ADR-0002 (four execution rings for runtime privilege, 2026), AWS Samples ADR-009 (explicit unverified invariants and comparison matrices, 2026), CNCF Dapr ARC-001 (explicit in-scope vs. out-of-scope boundaries, 2021), Spotify Backstage ADR005 (phased incremental adoption, 2025), UK Government Digital Service ADR-0002 (container isolation trade-offs, 2020), and Mozilla UniFFI ADR-0003 (MADR decision drivers and short/long-term evolution, 2021). The resulting ADR compressed all architectural trade-offs into 98 lines and passed 8/8 Gate C checks with zero anti-patterns.
Horizon Alignment and Role Routing
Research without context still risks pulling irrelevant references. Before Gate A starts, doc_check_trigger translates three dimensions of user intent into a targeted research blueprint (research_blueprint and big_tech_alignment).
First, horizon alignment inspects explicit short_term_goal (0 to 3 months), medium_term_goal (3 to 12 months), and long_term_goal (12+ months) parameters. Domain keywords automatically bias benchmark organization selection toward relevant engineering leaders: security and compliance goals align toward NIST, OWASP, Cloudflare, AWS Security, and Google Project Zero; scale and reliability goals align toward Google SRE, AWS Builders’ Library, Cloudflare, Netflix Tech, and PagerDuty; AI agent and MCP goals align toward Anthropic, OpenAI, Google DeepMind, Model Context Protocol, and GitHub (Paracelsus MCP Repository, 2026).
Second, explicit role routing (Cargo Y -> Cargo X) is enforced for internal-comms and sop document types. If either sender_role or recipient_role is absent, doc_check_trigger returns role_routing.status == "clarification_required" so the agent clarifies authority and readership before drafting. In the benchmark’s Task 2 (Head of Engineering -> CFO), this mechanism aligned research across GitHub Engineering (2023), PagerDuty Incident Response Docs (2025), Google SRE Workbook Appendix B (2018), Sourcegraph Company Handbook (2023), AWS Well-Architected Cost Optimization (2026), and FinOps Foundation Principles (2025).
Third, economic amortization ensures Gate A is not a permanent tax. Once Gate A and Gate B pass, doc_synthesize_pack persists the living schema (index.json), synthesized template (template.md), empirical anti-patterns catalog (anti-patterns.md), profile (profile.md), usage guide (guide.md), and reusable project rulebook (local-rules.md) inside ~/.cache/paracelsos/workspaces/<doc_type>/, stamped with ttl_days and refresh_after_utc (365 days default for ADRs, 180 days default for operational specs). From Document #2 onward, agents call doc_get_pack(detail="summary") within the TTL window and inherit the empirical rigor immediately.
Limits and Failure Modes
Evidence-first synthesis trades upfront latency for downstream precision, and that trade-off must be stated plainly. First-time bootstrap of a brand-new document type requires live web access and adds roughly three minutes of retrieval, verification, and synthesis overhead (364s for Task 1 and 385s for Task 2 in cold-start Docker runs versus 177s and 205s for unassisted generation). In air-gapped environments where public HTTPS retrieval is blocked, teams must pre-populate and mirror verified workspace packs under PARACELSOS_PIPELINE_ROOT before running offline.
Gate A also verifies structural provenance and cryptographic integrity, not factual truthfulness of internal company metrics supplied by the user. A document that passes Gate A, Gate B, and Gate C is structurally disciplined, role-routed, and bounded in scope, yet engineering leaders remain responsible for validating internal telemetry numbers, budget figures, and legal SLA clauses before signing off.
Sources
- Michael Nygard (2011), Documenting Architecture Decisions: https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions
- NIST FIPS 180-4 (2015), Secure Hash Standard (SHS): https://csrc.nist.gov/pubs/fips/180-4/upd1/final
- Paracelsus MCP Repository (
brontesiastudio/paracelsos-mcp, 2026): https://github.com/brontesiastudio/paracelsos-mcp - Microsoft Agent Governance Toolkit (2026), ADR 0002: Use four execution rings instead of RBAC for runtime privilege: https://github.com/microsoft/agent-governance-toolkit/blob/main/docs/adr/0002-use-four-execution-rings-for-runtime-privilege.md
- AWS Samples (2026), ADR-009: Host cloud personas on AgentCore Runtime Instances, not bare EC2: https://github.com/aws-samples/sample-agentstorming/blob/main/docs/adr/ADR-009-agentcore-runtime-instances-for-personas.md
- CNCF Dapr (2021), ARC-001: Refactor for modularity and testability: https://github.com/dapr/dapr/blob/master/docs/decision_records/architecture/ARC-001-refactor-for-modularity-and-testability.md
- Spotify Backstage (2025), ADR005: Catalog Core Entities: https://github.com/backstage/backstage/blob/master/docs/architecture-decisions/adr005-catalog-core-entities.md
- UK Government Digital Service (2020), ADR-0002: Docker images for Ruby Applications: https://github.com/alphagov/govuk-docker/blob/main/docs/adr/0002-docker-images-for-ruby-applications.md
- Mozilla UniFFI (2021), ADR-0003: Let consumers opt out of HandleMap locking if their interface is threadsafe: https://github.com/mozilla/uniffi-rs/blob/main/docs/adr/0003-threadsafe-interfaces.md
- Google SRE Workbook (2018), Appendix B: Example Error Budget Policy: https://sre.google/workbook/error-budget-policy/