Process Optimization: STRIX Documentation Harness Workflow
Process analyzed: Regenerating and maintaining this project's own generated
documentation (docs/process/harness-maintenance-process.md /
docs/process/runbooks/regenerate-documentation.md)
Date: 2026-08-14
1. Current State (as built)
| Step | Who | Manual? | Time (typical) |
|---|---|---|---|
| Identify which generator owns a given doc symptom | Doc harness maintainer | Manual (mental lookup table) | ~1 min |
| Edit the generator script | Doc harness maintainer | Manual | Varies |
| Run the generator command | Doc harness maintainer | Manual, one command at a time, no single "regenerate all" entry point | ~10 sec/script |
| Verify output (links resolve, design tokens intact, claims accurate) | Doc harness maintainer | Fully manual — regex link-check and visual spot-check, no automated test | 5–15 min |
Refresh samples/harness-tools/ snapshot |
Doc harness maintainer | Manual rsync, easy to forget after editing tools/ |
~30 sec (if remembered) |
Keep design tokens in sync between templates/design-system/tokens.css and the hard-coded CSS strings in two generator scripts |
Doc harness maintainer | Fully manual, duplicated by hand, not imported | Only surfaces as a bug later |
This workflow was exercised for real during this project's own build: five
separate generator scripts were each run individually and by hand, output was
verified by eye and by ad-hoc regex link extraction, and one generator
(gen_design_html.py) had to be fully rewritten after an f-string templating
bug — a class of error a pre-flight syntax check would have caught before the
run rather than after.
2. Identified Waste
- Manual work — no single "regenerate everything" entry point. Steps 1–3
of the runbook are three separate
python3invocations the maintainer must remember to run in the right order after any generator edit. Nothing enforces that all five are re-run together, so it's possible to updategen_html.pyand forgetgen_design_html.py, leavingarchitecture.htmland the HTML design docs visibly out of sync with each other. - Rework — the design-token duplication is a standing rework risk.
templates/design-system/tokens.cssis the stated "source of truth" for colors, butgen_html.pyandgen_design_html.pyeach hard-copy the same token values into a PythonCSSstring. Any token change requires editing three places by hand and remembering to keep them identical — exactly the kind of drift this project's own "never hand-edit a generated file" rule is designed to prevent, except here the generator itself is the thing duplicating source-of-truth data. - Over-processing — verification is fully manual and repeated from scratch
each time. Link-checking
architecture.htmlwas done once via an ad-hoc regex extraction during the build, but there's no saved script to re-run it — the next person doing verification (per Step 4 of the maintenance process) has to reconstruct the same check by hand. - Waiting / forgetting — the samples snapshot refresh is a separate,
easy-to-skip step.
samples/harness-tools/only stays useful as an audit copy ifrsyncis run after everytools/edit; there is no automated trigger, so it will silently drift the first time someone forgets. - Handoff risk — symptom-to-generator mapping lives only in prose. The
table in
harness-maintenance-process.mdStep 1 is the only place that says "if X is wrong, edit Y" — a new maintainer has to read and trust that table rather than the tooling enforcing it (e.g. via a manifest or naming convention).
3. Future State (recommended)
- Add a single
regenerate_all.pyentry point intools/that runsgen_html.py→gen_design_html.py→gen_modules.pyin sequence, prints a summary of what changed, and exits non-zero on any script failure. This removes the "forgot to re-run one of the three" failure mode without removing the ability to run any script individually for a targeted fix. - Make
tokens.cssthe actual import, not a manually-copied reference. Havegen_html.pyandgen_design_html.pyreadtemplates/design-system/tokens.cssat generation time and inject its contents into the<style>block, instead of maintaining a parallel hard-codedCSSstring. This turns a "remember to keep three files in sync" problem into a "there is only one file" fact. - Save the link-check as a reusable script, e.g.
tools/check_links.py, that extracts every relativehreffromarchitecture.html(and optionally the other generated HTML files) and confirms the target exists — run it as the last step ofregenerate_all.pyautomatically, turning manual verification into an automated checkpoint rather than a step someone has to remember and reconstruct. - Fold the
samples/harness-tools/refresh intoregenerate_all.py(or a git pre-commit hook, if this project moves to version control with hooks) so it can't be forgotten after atools/edit. - Turn the symptom→generator table into a comment block at the top of each generator script in addition to the prose table in the process doc, so the mapping is discoverable by reading the code, not only by reading documentation about the code.
4. Estimated Impact
| Change | Time saved per regeneration cycle | Error reduction |
|---|---|---|
Single regenerate_all.py entry point |
~2–3 min (no manual sequencing/remembering) | Eliminates "forgot to run one script" drift between generated files |
| Token import instead of duplication | 0 min normal case; avoids a full debugging cycle when it would have drifted (historically: undetected until visually spotted) | Eliminates 2 of 3 places a token value can silently diverge |
| Saved, reusable link-check script | ~5 min per verification pass (no reconstructing the regex by hand) | Makes link verification consistent instead of ad-hoc |
| Automated samples-snapshot refresh | ~30 sec, but removes a "forgot" failure mode entirely | Keeps samples/harness-tools/ trustworthy as an audit copy |
5. Implementation Plan
- Write
tools/check_links.py(lowest risk, most immediately useful, codifies work already done once by hand during the build) - Write
tools/regenerate_all.pythat calls the three existing generators plus the new link-check plus thersyncsnapshot refresh, in order, stopping on first failure - Refactor
gen_html.pyandgen_design_html.pyto readtemplates/design-system/tokens.cssinstead of hard-coding aCSSstring (highest-value but touches the most code — do last, and re-verify visual output against the existing screenshots/verification checklist after the change) - Update
docs/process/runbooks/regenerate-documentation.mdto replace Steps 1–3 and 5 with the singlepython3 tools/regenerate_all.pycommand, keeping the individual-script instructions as a "targeted fix" fallback section rather than removing them
Related Documents
docs/process/harness-maintenance-process.mddocs/process/runbooks/regenerate-documentation.mdsamples/harness-tools/README.md