Process Optimization: STRIX Documentation Harness Workflow

docs / process / harness-process-optimization

← all docs

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

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

  1. Write tools/check_links.py (lowest risk, most immediately useful, codifies work already done once by hand during the build)
  2. Write tools/regenerate_all.py that calls the three existing generators plus the new link-check plus the rsync snapshot refresh, in order, stopping on first failure
  3. Refactor gen_html.py and gen_design_html.py to read templates/design-system/tokens.css instead of hard-coding a CSS string (highest-value but touches the most code — do last, and re-verify visual output against the existing screenshots/verification checklist after the change)
  4. Update docs/process/runbooks/regenerate-documentation.md to replace Steps 1–3 and 5 with the single python3 tools/regenerate_all.py command, keeping the individual-script instructions as a "targeted fix" fallback section rather than removing them