T-ETML-decouple-regen-from-task-work-prs
Status: closed/obsoleted · Impact: medium · Complexity: small
Auto-generated from a /sdlc:task-work post-mortem. Review and
promote to open/ready before picking up.
When a per-task PR happens to need site/scripts/regen.mjs to land
its own site-reference updates (e.g.
T-UBJK-co-locate-skill-specific-scripts needed the three
moved-script reference pages cleaned up), running regen also picks up
unrelated drift that accumulated since the last /dev-update-docs
sweep — new skills, new shared scripts, content changes to other
skills’ reference pages. Including that drift couples the per-task PR
to unrelated changes and inflates review surface. The
T-UBJK-co-locate-skill-specific-scripts run had to manually
git restore four unrelated skill reference pages and delete three
unrelated new pages. That’s manual judgment work the orchestrator
should not require.
site/scripts/regen.mjs is a deterministic full regenerator: it walks
the entire plugin source tree and writes one page per skill / entity
/ script under site/src/content/docs/reference/. There is no
“targeted” mode that regenerates only the pages affected by a
specific set of changed paths. /dev-update-docs is the scheduled
docs-refresh skill but runs as a separate sweep, so between runs
ambient drift can accumulate.
Proposed
Section titled “Proposed”Pick one of:
- (a) Targeted regen. Extend
regen.mjswith a--pathsflag that takes a list of changed source paths and regenerates only the reference pages those paths feed. Per-task PRs that touch plugin source then run regen with their own changed-paths list and produce a focused diff. - (b) Scheduled drift sweep. Treat
/dev-update-docsas the only path to refresh the site reference; per-task PRs do not run regen at all and rely on the next scheduled sweep to refresh whatever they touched. Document this contract intask-workandorchestrate.
(a) is more useful (per-PR diffs stay self-contained) but is more script work. (b) is mechanically simpler but loses the “your PR ships its own site-reference updates” property.
Approach
Section titled “Approach”- Decide between (a) and (b). Surface the trade-off to the user.
- If (a): add
--pathstoregen.mjs, teach it to map source paths to destination pages, and update the task-work / orchestrate prose to invoke it with the just-committed-paths list. - If (b): remove any task-work / orchestrate steps that mention
running regen; clearly document that site drift is
/dev-update-docs’s problem.
Files to touch
Section titled “Files to touch”| Location | Kind | Change |
|---|---|---|
site/scripts/regen.mjs | modify | if (a), add --paths mode. |
plugin/skills/task-work/SKILL.md | modify | and |
Acceptance criteria
Section titled “Acceptance criteria”- AC-1: A per-task PR that modifies one plugin source file (a SKILL.md or a script) can refresh its own reference page without pulling in unrelated reference-page drift.
- AC-2: The decision and any new prose is consistent across
task-workandorchestrate.
Out of scope
Section titled “Out of scope”- none
Dependencies
Section titled “Dependencies”- none
Discovery context
Section titled “Discovery context”Spawned by /sdlc:task-work post-mortem of T-UBJK-co-locate-skill-specific-scripts on 2026-05-20.