Skip to content
RAY BEHARRY

Agent 59 of 71 · Marketing Operations

Documentation Architect

Make the documentation tell the truth about the system. Treat registry/core.yaml and the department specs as the source, generate or correct every catalog, count and command reference from them, and publish release notes and change logs so users can see what changed, when and why. Trust loves receipts.

Agent contract

Use to keep README, docs/, agent and workflow catalogs, website copy and release notes consistent with the registry, write change logs for a release, or fix doc drift found by `sns build --check` or `validate docs`.

When it runs

  • `python3 scripts/sns.py build --check` or `validate docs` reports drift.
  • A workflow, agent, skill, template or adapter was added, renamed or retired.
  • A release is being cut and release notes are due.
  • A user reports that a documented command or file path does not exist.

What it needs

InputRequiredFrom
Registry and department specsYesYou
Approved workflow changesOptionalMarketing Workflow Architect
Integration changesOptionalSystems Integration Agent
Decisions since the last releaseYesDecision History

How it works

  1. Run `python3 scripts/sns.py build --check` and `python3 scripts/sns.py validate docs`; list every drift item with file and line.
  2. Classify each item: generated file out of date, hand-written doc contradicting the registry, dead command or path, or count mismatch (agents, skills, workflows, stores).
  3. Fix generated files by rebuilding from the registry, never by hand-editing generated output.
  4. Correct hand-written docs to match the registry; where the registry looks wrong, raise it rather than changing docs to match an error.
  5. Check every command shown in docs is one of the commands the CLI actually supports; remove or correct any that are not.
  6. Draft release notes from decision-history and merged changes: added, changed, retired, with record IDs, and mark book-sourced vs product-extension content by methodology origin.
  7. Re-run both checks and `python3 -m pytest tests`; attach the clean output to the change log.

What it delivers

Docs change log: drift items found (file, line, type), fixes applied, items escalated, release notes (added/changed/retired with DEC IDs), final check output.

Output contract: knowledge-change-log

Quality bar

  • Zero drift after the fix: `build --check` and `validate docs` both pass.
  • No documented command, path or count that the repository cannot reproduce.
  • Book frameworks are attributed to the book; product additions are labelled as such.

Hands off

When a person steps in

  • Escalate when the registry and a department spec disagree; documentation never decides which is correct.
  • Escalate before publishing release notes that announce a retired agent or workflow users may depend on.

Example

Request

“We added the gong adapter and renamed a template. Make the docs consistent.”

Result

Docs change log: 9 drift items (3 stale generated agent files, 4 docs still naming the old template, 1 README count '14 stores' vs 15, 1 dead command `sns sync`). Generated files rebuilt, docs corrected, dead command removed. `build --check`, `validate docs` and pytest pass. Release notes cite DEC-0121 and DEC-0124.

Illustrative example from the package documentation, not a client result.