[self-care:docs-build-time-investigator] Skip redundant dashboard rebuilds in docs publishes by reusing same-SHA dashboard output

Investigated the last 12 successful `docs.yml` runs in the last 14 days and found the reusable dashboard generation is the dominant repeated cost, with the outer docs workflow itself staying fast. The main opportunity is to stop dispatching `dashboard-build.yml` on every scheduled `docs.yml` run when the source SHA already has a cached dashboard artifact or when no dashboard inputs changed. **Action:** Repository maintainers should update `.github/workflows/docs.yml` and/or `.github/workflows/dashboard-build.yml` to skip redundant dashboard rebuild dispatches for unchanged source revisions, and accept this when median scheduled `docs.yml` runtime drops by at least 60 seconds without reducing freshness or deployment correctness.

### Summary
The reusable dashboard generation path is the only bottleneck that repeatedly clears the actionability threshold. Across 12 comparable successful `docs.yml` runs from 2026-09-08, the outer `docs.yml` workflow had median execution time 104.5s (p90 215.2s), but its `dashboard` job mostly just waited on the dispatched reusable workflow. For normal scheduled runs, the `dashboard` job median was 50s while the `build` job median was 34s and the `deploy` job median was 10s. One like-for-like push run on the same source SHA (`2bca2b1cc79e33ce2c4d81163e63c32cbc8e5da4`) took 700s end-to-end because the dispatched dashboard build expanded to 10m29s, showing this stage dominates tail latency when cache/freshness paths miss.

### Timing evidence
- Evidence window: latest completed `docs.yml` runs from the last 14 days, sampled from 2026-09-08T07:35:55Z through 2026-09-08T11:21:36Z
- Comparable successful samples used: 12 `docs.yml` runs (8 `schedule`, 4 `push`)
- Excluded from timing baselines: 4 failed `docs.yml` runs in the same window (`34211843376`, `34210903440`, `34201029490`, `34200965924`) and 1 in-progress run was ignored while sampling
- Queue time: median 0s, p90 0s for the sampled `docs.yml` runs
- Full `docs.yml` execution time: median 104.5s, p90 215.2s
- `dashboard` job: median 50s, p90 75.5s
- `build` job: median 34s, p90 39.8s
- `deploy` job: median 10s, p90 40.8s
- Representative same-SHA comparison on `2bca2b1cc79e33ce2c4d81163e63c32cbc8e5da4`:
- scheduled run `34220268241`: 138s total, 47s `dashboard`, 35s `build`, 44s `deploy`
- push run `34218898322`: 700s total, 637s `dashboard`, 40s `build`, 9s `deploy`
- Build-step evidence from successful runs showed `build` job steps are already small and stable: `Restore node_modules` usually ~5-14s, `Build documentation` ~4-6s, `Mount dashboard at /cao` ~1-3s, `Upload Pages artifact` ~3-4s.
- Cache evidence verified from job metadata/log-derived step conclusions:
- `Install dependencies` and `Save node_modules` were skipped in all sampled successful `build` jobs, indicating `node_modules` restore hit repeatedly.
- `Restore dashboard from cache` completed but `Mount dashboard at /cao` still ran in sampled outer builds, which is expected because the outer workflow restores a per-run key (`cao-dashboard-${run-id}-${run-attempt}`) that only exists after the dispatched dashboard build saves it.
- Confidence: medium-high for the bottleneck location because the sampled runs consistently show outer build/deploy work is small, while dashboard generation dominates both the normal path and the worst tail.

### Bottleneck
`.github/workflows/docs.yml` always dispatches `.github/workflows/dashboard-build.yml` from the `dashboard` job, even on the 15-minute schedule and even when the same source SHA already had a recent successful dashboard build. In `dashboard-build.yml`, the expensive work sits behind the dispatched workflow’s activity/data refresh and dashboard assembly path, while the outer docs build only consumes the produced artifact. This means most scheduled docs publishes pay the dashboard orchestration cost every time instead of reusing an artifact across like-for-like runs.

Relevant source locations:
- `.github/workflows/docs.yml`: scheduled trigger, `dashboard` job dispatch, and per-run dashboard cache restore/download in `build`
- `.github/workflows/dashboard-build.yml`: activity cache lookup, activity refresh dispatch, dashboard assembly, and dashboard artifact/cache save

### Recommended changes
1. Add a source-revision-aware reuse gate before dispatching `dashboard-build.yml` from `.github/workflows/docs.yml`.
- For scheduled docs runs, first attempt to restore a dashboard artifact/cache keyed by dashboard-relevant inputs such as `${{ github.workflow_sha }}`, dashboard mode, and any authoritative activity snapshot identifier.
- Only dispatch `dashboard-build.yml` when that lookup misses or freshness policy requires a newer snapshot.
2. In `.github/workflows/dashboard-build.yml`, save the assembled dashboard under a reusable key derived from the source SHA plus freshness inputs, not only `cao-dashboard-${{ github.run_id }}-${{ github.run_attempt }}`.
- Keep the current per-run handoff if needed for exact parent-child coordination, but add a second reusable cache/artifact key for cross-run reuse.
3. Narrow scheduled rebuilds to dashboard-affecting freshness events.
- If a scheduled docs publish is allowed to use cached activity (`inputs.mode || 'cache'` already defaults the dispatch path toward cache), skip dispatch entirely when both dashboard sources and the most recent acceptable activity snapshot are unchanged.

### Expected effect and validation
Expected savings: at least 60 seconds and likely more than 15% of median `docs.yml` execution time for scheduled runs, because the current median scheduled `dashboard` wait is about 50s and the outer workflow has only ~34s of build work after that. The observed 10m29s same-SHA push outlier also suggests large tail-risk reduction when a rebuild path unexpectedly goes cold or refresh work expands.

Validate by comparing at least five post-change successful scheduled runs against the current baseline:
- median `docs.yml` execution time below 45s, or at minimum reduced by >=60s from comparable rebuild-prone runs
- `dashboard` job median near zero or replaced by a short cache-lookup step on unchanged SHAs
- no increase in docs or Pages deployment failures
- dashboard content freshness still matches the intended snapshot/update policy

### Caveats
- This recommendation assumes maintainers still want scheduled docs publishes, so it preserves correctness by gating only on validated artifact/snapshot reuse rather than removing the schedule.
- Cross-run cache keys must include any data-freshness input that changes rendered dashboard output; otherwise stale activity could be published.
- The sample window was limited to the latest 20 completed `docs.yml` runs and yielded 12 successful runs on one day, so confidence is strongest for current behavior rather than long-term seasonal patterns.
- Several failed runs existed in the same window and should be reviewed separately for reliability, but they were not treated as normal timing samples.

### Control Plane
- Correlation ID: `34219878561-399`
- Central repository: `githubnext/gh-aw-cao`
- Control plane run: https://github.com/githubnext/gh-aw-cao/actions/runs/34219878561

### References
- `docs.yml` runs: `34220268241`, `34218898322`, `34218564742`, `34217155303`, `34216553488`, `34216058956`, `34215282019`, `34213285165`, `34213281018`, `34209983281`, `34207779868`, `34206996741`
- Reusable `dashboard-build.yml` runs observed from docs dispatches: `34220278619`, `34218911532`, `34218577833`, `34217167610`, `34216564757`, `34216072373`, `34215292312`, `34213447864`, `34213292437`, `34209997064`, `34207797320`, `34207009931`
- Workflow sources: `.github/workflows/docs.yml`, `.github/workflows/dashboard-build.yml`

> Generated by [SelfCare / Docs Build Time](https://github.com/githubnext/gh-aw-cao/actions/runs/34220267125) · pi · gpt54 · 30.6 AIC · ⌖ 8.61 AIC · ⊞ 8.8K · [◷](https://github.com/search?q=repo%3Agithubnext%2Fgh-aw-cao+is%3Aissue+%22gh-aw-workflow-call-id%3A+githubnext%2Fgh-aw-cao%2Fself-care-docs-build-time-investigator%22&type=issues)
> - [x] expires on Sep 22, 2026, 11:27 AM UTC

Start with the scheduled trigger and dashboard dispatch in .github/workflows/docs.yml, then trace the activity cache lookup, dashboard assembly, and artifact/cache save in .github/workflows/dashboard-build.yml. Run comparable docs.yml workflows to establish the current timing and verify cache behavior. Done means unchanged source revisions reuse valid dashboard output, freshness and deployment correctness are preserved, and at least five successful scheduled runs meet the stated runtime and reliability targets.

Written by the indexing model from the issue text.