Skip to article frontmatterSkip to article content
Site not loading correctly?

This may be due to an incorrect BASE_URL configuration. See the MyST Documentation for reference.

A-26014: Script Suite Documentation Redundancy — Triad to Dyad Evolution

title: Script Suite Documentation Redundancy — Triad to Dyad Evolution authors:

A-26014: Script Suite Documentation Redundancy — Triad to Dyad Evolution

Problem Statement

ADR-26011 mandates a three-part convention for every script: the script itself, a test suite, and an instruction document in tools/docs/scripts_instructions/. The check_script_suite.py pre-commit hook enforces this triad — failing the commit if any leg is missing when the others are modified.

Since ADR-26011 was written, two developments have changed the documentation landscape:

  1. Contract docstrings became mandatory. Every module must open with a docstring covering scope, public interface, design decisions, and dependencies (CLAUDE.md convention). This is exactly what the instruction docs were created to provide.

  2. Test suites document contracts by example. With the TDD standard and test quality guidelines (semantic assertions, config-driven parametrization), tests serve as living documentation that stays in sync by construction.

The instruction docs now duplicate information that already lives in two other places — and unlike docstrings and tests, docs are not verified by CI to be correct.

Key Insights

Maintenance Cost Is Non-Trivial

During the YAML→JSON config migration (step 7 of the governance plan), every script change required a corresponding doc update. The evidence script doc referenced evidence.config.yaml and architecture.config.yaml — both deleted files. These stale references would have passed CI silently (docs are not validated for semantic correctness).

The current inventory:

Three Documentation Layers Now Exist

LayerLocationVerified by CIStays in sync
Contract docstringIn the script fileImport-time (syntax)Yes — lives with the code
Test suitetools/tests/test_*.pypytestYes — fails if contract breaks
Instruction doctools/docs/scripts_instructions/check_script_suite (existence only)No — content can drift

The instruction doc is the only layer where content correctness is not enforced. check_script_suite verifies the file exists and is staged — not that it accurately describes the script.

Package Extraction Makes Docs Obsolete

When vadocs is extracted as a standalone package (Phase 1.3 of the roadmap), standard Python documentation tools (sphinx, mkdocs) auto-generate API documentation from docstrings. Per-script instruction docs:

Investing in strong docstrings now produces documentation that travels with the code through extraction.

The Triad Served Its Original Purpose

ADR-26011 was written when scripts were atomic with no shared modules, minimal docstrings, and no test quality standards. The instruction docs filled a real gap — they were the only place explaining how a script worked. That gap no longer exists.

Approach Evaluation

Supersede ADR-26011 with a new ADR requiring only script + test. Update check_script_suite.py to drop the doc requirement. Existing docs remain but are not maintained — they age out naturally.

Pros:

Cons:

Mitigation: The README in tools/docs/scripts_instructions/ can link to the package-level guide when vadocs is extracted.

Option B: Keep Triad, Automate Doc Generation

Generate instruction docs from docstrings + test metadata. Keep check_script_suite enforcing the triad but auto-produce the doc content.

Pros:

Cons:

Option C: Status Quo

Keep the triad as-is, accept the maintenance cost.

Pros:

Cons:

References

Analyses
A-26013: JSON as Governance Config Format — Migration from YAML
Analyses
A-26015: Frontmatter Validator Architecture — Config-Code Divergence and Resolution