Skip to content

missing_docs: fast-follows from the drift-watch validation runs #631

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rachaelrenk merged 3 commits into from
Aug 26, 2026
+51 −0
Merged

missing_docs: fast-follows from the drift-watch validation runs #631

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a464d16
missing_docs: four fast-follows from the drift-watch validation runs
rachaelrenk Aug 25, 2026
1205a1a
missing_docs: fix warp default branch to master, not main
warp-agent-staging[bot] Aug 25, 2026
509fd3a
missing_docs: document the two schedule-setup choices the prompt cann…
rachaelrenk Aug 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 51 additions & 0 deletions .agents/skills/missing_docs/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,27 @@ a fresh sandbox does not have. Install once per sandbox:
npm ci
```

### Regenerate the snapshot only from current checkouts

`--update-snapshot` rewrites `references/surface_snapshot.json` from whatever the sibling
repos hold at that moment, and it cannot tell a current checkout from a stale one. Running
it against an old or feature-branched `warp` / `warp-server` writes a baseline describing
surfaces that are not on the default branch, and the next `--diff` then reports the gap
between two wrong baselines as real drift. Confirm both repos are current and on their
default branch — `master` for `warp`, `develop` for `warp-server` — before regenerating:

```bash
for repo in ../warp ../warp-server; do
git -C "$repo" fetch --quiet origin
echo "$repo $(git -C "$repo" rev-parse --abbrev-ref HEAD) \
$(git -C "$repo" log -1 --format=%cd --date=short)"
done
```

A cloud sandbox provisions fresh checkouts and satisfies this by construction; a
developer's machine usually does not. When you cannot confirm it, leave the regen to a
scheduled run rather than committing a snapshot you cannot vouch for.

## Public vs. private surfaces (what you may document)

Only document surfaces that are **publicly released**. This is the most important guardrail in this skill: do not reveal private or unreleased surfaces in public docs. Two independent gates, both required:
Expand All @@ -66,6 +87,7 @@ Only document surfaces that are **publicly released**. This is the most importan
Rules of thumb:
- A `warp-server` API endpoint that is **not already in the OpenAPI spec** is treated as not-yet-public: do NOT hand-write docs for it. Either confirm it has been publicly released and let the `sync-openapi-spec` skill bring it into the spec, or map it `-> internal` / defer it. When unsure, defer — never expose an unreleased endpoint or feature in public docs.
- A CLI command or API route gated by a **non-GA feature flag** should be mapped `-> gated:<Flag>` (for example, `gated:AIMemories`) rather than `-> internal`: the audit auto-defers it while the flag is non-GA and auto-surfaces it for docs once the flag goes GA. (Feature flags and settings already auto-defer by rollout status; `gated:` extends that to CLI/API.)
- **A published docs page is not evidence that an API is released.** Early Access features routinely have public pages describing what the product does while their REST routes stay out of the released spec, so "we already document this feature" does not clear Gate 0 for an endpoint. For API surfaces the released OpenAPI spec is the only test. The Factory pages describe dispatching a run, yet no `/factory` path appears in `developers/agent-api-openapi.yaml` — those routes are Gate 0 deferrals despite the prose.
- The audit still *detects* these as gaps (useful signal), but detection is not permission to document. Every resolution must respect this boundary.

This section is the source of truth for **Gate 0** in
Expand Down Expand Up @@ -121,6 +143,15 @@ The script performs these coverage audits:
4. **Slash command coverage** — parses the static registry in the warp client repo's
`app/src/search/slash_command_menu/static_commands/` and checks each `/command`
is mentioned in docs.

**Known limitation: this check is repo-wide, not surface-scoped.** A command counts as
covered when *any* page mentions it (`audit_slash_commands` in `scripts/audit_docs.py`
searches every docs page), so a command documented on the GUI slash-commands page reads
as covered even when the CLI reference omits it. That is how `/usage` reached a release
undocumented for CLI users — only the changelog cross-check caught it. The CLI and
settings audits scope their search to the pages that own those surfaces; this one does
not. Until that is fixed, do not read a slash command's `doc_covered` bucket as
"documented in the right place."
5. **Settings coverage** — parses every `toml_path: "section.key"` setting
registration in the warp client repo (the same registry the JSON-schema generator uses)
and checks the all-settings reference page documents it. Private and
Expand Down Expand Up @@ -403,6 +434,8 @@ Then **actually request the review on GitHub** with `gh pr edit <PR> --add-revie

An individual unresolved *path* is non-fatal — other paths usually resolve the same owner. An empty *result* is not: fall back to `dannyneira` rather than opening the PR with no reviewer. See step 7 of drift-watch mode for the required command.

**Expect warp-server-only findings to fall back.** The warp client repo's ownership file has a root rule, so nearly any path in it resolves. warp-server's does not, and whole areas — the `/factory` handlers among them — carry no entry, so a finding whose only source file is a warp-server handler resolves to nothing and lands on `dannyneira`. That is the fallback doing its job; report it that way rather than as a resolution failure. Do not hardcode an owner here to paper over it — the fix belongs in warp-server's ownership file, and once an entry exists resolution starts working with no change to this skill.

### PR strategy: one PR per feature

Ship each documented feature as its own focused PR so the owning engineer reviews only
Expand Down Expand Up @@ -534,6 +567,24 @@ A run that gates out every candidate is a successful run. It opens no feature PR
only the bookkeeping PR recording the verdicts. Do not manufacture work to justify the
run.

#### Schedule setup

Two configuration choices decide whether the schedule behaves, and neither is visible from
the prompt below:

- **Select a cloud agent, not Quick run.** Quick run executes as the calling user, so its
pull requests are authored by that person — which for a schedule means whoever created
it. Selecting a cloud agent runs as that agent instead, and with team GitHub
authorization configured its pull requests are authored by the Warp Factories GitHub
App. Any schedule that opens PRs wants the agent. See
[Cloud agent accounts](https://docs.warp.dev/platform/agents/).
- **Give that agent this skill and nothing else.** A run inherits every skill attached to
the agent it runs as, and the schedule form will not let you detach an agent-level
skill. Pointing drift-watch at a general-purpose docs agent therefore pulls that agent's
other skills into every run — and a weekly release-updates skill that defaults to
running all of its tasks will do exactly that, daily. Create a dedicated agent rather
than reusing one that already carries other work.

Recommended scheduled-agent prompt (copy when setting up the agent):

> Run the missing_docs skill in drift-watch mode. Work from the docs repo root — every
Expand Down
Loading