[self-care:docs-build-time-investigator] Narrow Documentation Pages dashboard rebuild triggers to actual dashboard inputs

Dashboard regeneration is the dominant avoidable cost in Documentation Pages: across 19 successful docs.yml runs from the last 14 days, the full workflow median was 94s (p90 167s), while the `dashboard` job alone was 35s median (p90 53s) and repeatedly rebuilt the dashboard even though the dashboard-build workflow itself usually finished in 26.5s median end-to-end. The current push trigger includes broad paths like `.github/workflows/*.md`, `.github/workflows/*.lock.yml`, `*/aw.yml`, and `.github/cao/**`, so many control-plane or package-manifest edits pay that dashboard rebuild cost even when dashboard source files did not change.

**Action:** Dashboard maintainers should narrow `docs.yml` push paths so the workflow dispatches `dashboard-build.yml` only when dashboard inputs actually change; acceptance check: a docs-only or control-plane-only change that does not touch dashboard inputs should skip the dashboard rebuild path and reduce Documentation Pages median runtime by at least 35s on comparable push runs.

### Summary
- Evidence window: latest 19 comparable successful `docs.yml` runs inspected from 2026-09-04T16:33:15Z to 2026-09-04T17:48:13Z; 1 cancelled run was excluded and 3 longer successful outliers were disclosed.
- Current timing: `docs.yml` median 94s, p90 167s; queue median 4s, p90 75s.
- Job medians: `dashboard` 35s (p90 53s), `build` 27s (p90 40s), `deploy` 10s (p90 16s).
- Recommendation: stop rebuilding the dashboard for pushes that only change docs or control-plane files outside actual dashboard inputs.
- Confidence: medium-high for wasted rebuild frequency, medium for exact savings because the sample window is short and very recent.

### Timing evidence
- `docs.yml` successful sample size: 19.
- `dashboard-build.yml` successful corroborating sample size: 20 dispatched runs.
- `docs.yml` outliers disclosed, not treated as normal: runs `33898354855` (196s, schedule), `33899878233` (167s, push), and `33900020668` (160s, schedule).
- Step medians in `docs.yml` build job show dependency caching is already effective: `Install dependencies` was skipped in all 19 runs after `Restore node_modules` cache hits; `Set up Node.js` median 6s, `Restore node_modules` median 5s, `Build documentation` median 5s, `Upload Pages artifact` median 2s.
- The dominant repeated visible cost in `docs.yml` is `Dispatch dashboard build` at 29s median and 48s p90, plus downstream waiting for that workflow before the main build can proceed.
- Corroborating `dashboard-build.yml` timings: overall median 26.5s, p90 36s; `activity` job median 6s, `build` job median 11.5s. Inside the dashboard build, `Restore collected activity data` median 1s, `Assemble Dashboard Language site` median 0s, `Build Dashboard Language sources` median 1s, and each artifact upload median 2s. This indicates the cost is primarily paying the whole extra workflow orchestration on many pushes, not slow site generation.

### Bottleneck
`.github/workflows/docs.yml` currently triggers on many non-dashboard paths, including `.github/cao/**`, `.github/workflows/*.md`, `.github/workflows/*.lock.yml`, and `*/aw.yml`, then always runs the `dashboard` job first. That job unconditionally dispatches `.github/workflows/dashboard-build.yml`, which in turn can refresh or restore activity data and re-upload dashboard artifacts. Because the docs build job waits on `needs.dashboard.outputs.run-id`, these pushes pay an extra ~35s median before the docs site can complete, even though the dashboard build's own inner steps are already fast.

### Recommended changes
1. In `.github/workflows/docs.yml`, split dashboard-affecting push paths from docs-only/control-plane paths.
2. Gate the `dashboard` job so it runs only when the event is `schedule`, `workflow_dispatch`, or a push that changed one of the dashboard inputs actually consumed by `dashboard-build.yml` (for example `dashboard/**`, `.github/workflows/dashboard-build.yml`, `.github/workflows/activity.yml`, and files that feed the dashboard artifact).
3. For pushes that only change docs-page content or non-dashboard workflow/control metadata, build and deploy the docs site without redispatching `dashboard-build.yml`; keep mounting the most recent published dashboard artifact only when safe, or skip the dashboard mount when the `/cao` subtree is unchanged.
4. If path gating needs change detection logic, implement it explicitly in `docs.yml` rather than broadening workflow triggers.

### Expected effect and validation
- Expected savings on affected push runs: about 35s median from eliminating the `dashboard` job, which is ~37% of the current 94s median full workflow runtime and comfortably above the 60s-or-15% actionability threshold on percentage.
- Validation plan:
- Compare at least five push runs before and after the path narrowing on the same trigger class.
- Verify that docs-only changes still publish correctly.
- Verify that dashboard-affecting changes still dispatch `dashboard-build.yml` and refresh the mounted `/cao` artifact.
- Confirm post-change medians separately for push and schedule runs so skipped dashboard builds are not mixed with scheduled refreshes.

### Caveats
- This recommendation is about avoidable rebuild frequency, not cache misses: trusted run metadata showed `node_modules` cache hits across all inspected `docs.yml` successes.
- Schedule runs should likely continue rebuilding the dashboard because freshness is the point of that trigger.
- Some currently broad trigger paths may intentionally keep dashboard content in sync with package or workflow changes; if so, narrow them only to files that materially affect dashboard output.
- The evidence window is rich enough for comparison but concentrated in a recent high-activity period, so maintainers should validate on a few more push runs after changing path filters.

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

### References
- Workflow source: `.github/workflows/docs.yml`
- Reusable workflow source: `.github/workflows/dashboard-build.yml`
- Sample `docs.yml` runs: `33902502865`, `33902286958`, `33902139011`, `33901710401`, `33901562872`, `33901123326`, `33901004190`, `33900324869`, `33900020668`, `33899878233`, `33899850625`, `33899511867`, `33899287855`, `33899214495`, `33898354855`, `33898314731`, `33897562245`, `33896950885`, `33895784928`
- Corroborating dispatched dashboard runs: `33902516177`, `33902298283`, `33902151123`, `33901735084`, `33901579606`, `33901156450`, `33901016242`, `33900335750`, `33900141695`, `33899980227`, `33899862245`, `33899523690`, `33899340515`, `33899225114`, `33898474962`, `33898327327`, `33897573563`, `33896964105`, `33895797083`, `33895171218`

> Generated by [SelfCare / Docs Build Time](https://github.com/githubnext/gh-aw-cao/actions/runs/33902651488) · pi · gpt54 · 39.9 AIC · ⌖ 8.55 AIC · ⊞ 8.6K · [◷](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 18, 2026, 5:56 PM UTC

Start with .github/workflows/docs.yml and .github/workflows/dashboard-build.yml, tracing the current push paths, dashboard job, and dispatch inputs. Compare the workflow behavior for docs-only, control-plane-only, dashboard-affecting, and scheduled changes. Done means at least five comparable push runs show docs-only changes skip the dashboard rebuild while dashboard changes still refresh it and publish the docs site correctly.

Written by the indexing model from the issue text.