---
name: docs-dry-run
description: Phases 0+1 of the docs pipeline, read-only. Clones the three product repos into a temp workspace, diffs them since the last processed commit, plans the documentation work items, and reports. Writes nothing under src/ and never advances state.json.
---

# Docs pipeline dry run (Phases 0+1, read-only)

Run the diff and planning phases of the weekly docs pipeline and report what a full run WOULD do. Hard rules for this skill:

- **Never** edit anything under `src/`, `automation/state.json`, or `automation/*-baseline.json`.
- **Never** commit, push, branch, or open a PR.
- Write only under `automation/runs/<date>/` (gitignored).

## Steps

1. **Prepare.** Let `DATE` = today as `YYYY-MM-DD`, `RUN_DIR` = `automation/runs/<DATE>`. Create `RUN_DIR`. Read `automation/state.json` and `automation/repos.json`.

2. **Phase 0, diff.** Invoke the Workflow tool with `scriptPath: ".claude/workflows/docs-diff.js"` (by path, not by name, see DESIGN.md 5.2.1) and:
   ```
   args: {
     date: <DATE>,
     runDir: "automation/runs/<DATE>",
     repos: [
       { key, product, url, lastSha: state.lastSha[key], docsTargets, productMapPath: "automation/product-map.json" only for teamspro }
       ... one entry per repo in repos.json
     ]
   }
   ```
   Save the returned object to `RUN_DIR/diff.json`.

3. **Phase 1, plan.** Spawn one `doc-gap-analyst` agent. Give it: the full contents of `RUN_DIR/diff.json`, the writer cap (12), and note that analytics signals are not yet available (M4). Ask for the structured work plan (workItems, deferred, attention, stats). Save it to `RUN_DIR/plan.json`.

4. **Validators (read-only).** Run `node automation/scripts/validate-sidebar.js --json` and `node automation/scripts/check-links.js --json` and capture their summaries (counts by type, do not paste hundreds of findings).

5. **Report.** Print a readable summary for the user:
   - Per repo: commits analyzed (diff range), user-facing changes found, anything in `attention` (unmapped modules, suite-wide changes), fallback windows or clone errors.
   - The ranked work items: id, action, product, pages, priority, one-line rationale. Then the deferred list.
   - Screenshot requests the plan generated (they would be captured in Phase 3).
   - Current docs health from the validators (counts only).
   - Close with: what a full `/docs-weekly` run would now do (write, screenshot, validate, open PR) and that state.json was NOT advanced.

6. **Cleanup.** Delete `RUN_DIR/sources/` (the temp clones). Keep the JSON artifacts for inspection.