📝 Documentation drift detected — workspace values and schedule intervals incomplete in authoring prompt

[github-actions]

Documentation Freshness Audit

The documentation audit found the following inconsistencies between code and documentation:

Findings

Area	Issue	File(s)
Workspace values	self alias and repository alias support missing from authoring prompt	prompts/create-ado-agentic-workflow.md
Workspace values	README front matter table only shows root | repo — missing self alias	README.md
Schedule syntax	every N days interval not listed in authoring prompt frequency table	prompts/create-ado-agentic-workflow.md

---

Details

1. prompts/create-ado-agentic-workflow.md — Step 4 Workspace table is incomplete

The Step 4 table documents only two workspace values:

| `root` (default) | `$(Build.SourcesDirectory)` | Only checking out `self` |
| `repo`           | `$(Build.SourcesDirectory)/$(Build.Repository.Name)` | Multiple repos checked out |
```

But `src/compile/common.rs` (`compute_effective_workspace`, line 362) accepts **three** kinds of value:
- `"root"` — maps to `$(Build.SourcesDirectory)` ✅ documented
- `"repo"` **or `"self"`** — maps to the trigger repo subdirectory. `"self"` is an alias per `RESERVED_WORKSPACE_NAMES` and the `"repo" | "self"` match arm ❌ not documented in prompt
- **Any repository alias listed in `checkout:`** — maps to `$(Build.SourcesDirectory)/<alias>` ❌ not documented in prompt

`docs/front-matter.md` already documents all three correctly:
> `workspace: repo # Optional: "root", "repo" (alias: "self"), or a checked-out repository alias.`

The gap in the authoring prompt means AI agents will never suggest or use `workspace: self` or `workspace: my-other-repo`, even when it would be the right choice.

---

#### 2. `README.md` — Front Matter Fields table shows `workspace` as `root | repo`

The table at line 238:
```
| `workspace` | `root` \| `repo` | auto | Working directory mode |

Missing: self as an alias for repo, and the fact that any checked-out repository alias is also a valid value.

---

3. prompts/create-ado-agentic-workflow.md — Step 3 Schedule table missing every N days

The frequency table in Step 3 lists every 2h and every 15 minutes but omits the every N days form documented in docs/schedule-syntax.md:

schedule: every 2 days # Every 2 days at scattered time

This is a valid interval parsed by src/fuzzy_schedule.rs (parse_interval_schedule, unit "days"). It falls between the minute-interval and bi-weekly/tri-weekly special forms and is a common scheduling need.

---

Suggested Fixes

• prompts/create-ado-agentic-workflow.md Step 4: Expand the workspace table to include self as an alias for repo, and a row explaining that any checkout alias can be used directly (e.g., workspace: my-other-repo).
• prompts/create-ado-agentic-workflow.md Step 3: Add every N days to the frequency table (e.g., every 2 days / every 7 days).
• README.md Front Matter Fields: Update the workspace field type column from `root` \| `repo` to `root` \| `repo` \| `self` \| *alias* (or similar) to reflect the full accepted value set.

---

This issue was created by the automated documentation freshness check.

Generated by Documentation Freshness Check · ● 2M · ◷