missing_docs: fast-follows from the drift-watch validation runs - #631
Conversation
Documentation-only. Each item was reproduced against the current code rather than carried over from run notes; two items from the original feedback list turned out to be already fixed and are not included. 1. Snapshot regen has an unstated environment precondition. --update-snapshot rewrites the baseline from whatever the sibling repos hold and cannot tell a current checkout from a stale one, so regenerating from a feature-branched warp or a months-old warp-server silently writes surfaces that are not on the default branch -- and the next --diff compares two wrong baselines. Adds the precondition and a check. This is not hypothetical: on the machine this was written on, warp sits on a feature branch and warp-server is three months behind, and the documented check reports both. 2. Gate 0 lacked the Early Access case. A published page describing a feature is not evidence its API is released; EA features routinely have public prose while their routes stay out of the spec. The /factor while their routes stay out of the spec. The /factor while their ent rat while their routes stay out of the spec. The /factor while their rurface-scoped. audit_slash_commands counts a command as covered when any page mentions it, so /usage read as covered from the GUI s covered from the GUI s covered from the GUI s covered from the GUI sross-check caught it. The CLI and settings audits scope to the pages that own th the pages that own th the pages that own th the pages that own th ix cha the pages thlume and belongs in its own PR. 4. warp-server findings routinel4. warp-server findings routinel4. warp-server findings routinel4. warp-sewarp-server does not, and the /factory handlers have no entry, so those findings land on the dannyneira fallback. Verified by running suggest_reviewers.py against the two factory handler paths. That is the fallback working, and the run output should say so rather than reporting a resolution failure. The real fix belongs in warp-server's ownership file. Not included, because they are already handled: the stash-based branch split (the skill only recommends `git checkout <ref> -- <files>`), and the missing reviewer request on bookkeeping PRs (#619 made the fallback mandatory and verified). Co-Authored-By: Warp <agent@warp.dev>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
I'm starting a first review of this pull request. You can view the conversation on Warp. I completed the review and no human review was requested for this pull request. Comment Powered by Oz |
![warp-for-oss[bot]](https://avatars.githubusercontent.com/in/3450139?s=60&v=4){kind=small}
There was a problem hiding this comment.
Overview
This PR updates the missing_docs skill with fast-follow guidance from drift-watch validation: snapshot regeneration preconditions, Early Access API release checks, slash-command coverage limitations, and warp-server reviewer fallback reporting. The changes are documentation-only and align with the existing skill guidance.
Concerns
- None identified. No approved spec context was available, and the security pass found no security-relevant issues in the added documentation.
Verdict
Found: 0 critical, 0 important, 0 suggestions
Approve
Comment /warp-agent-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
![warp-agent-staging[bot]](https://avatars.githubusercontent.com/in/2196476?s=60&v=4){kind=small}
There was a problem hiding this comment.
Overview
This PR adds four focused safeguards to the missing_docs drift-watch skill. The OpenAPI, slash-command, and ownership-fallback guidance is clear and matches the current audit implementation.
Verdict
Found: 0 critical, 1 important, 0 suggestions
Request changes
Co-Authored-By: Warp <agent@warp.dev>
There was a problem hiding this comment.
Overview
The rework corrects the snapshot-regeneration precondition to name the actual default branches for warp and warp-server. The prior finding is resolved, and this cumulative re-review found no new issues.
Verdict
Checks: CI ✅ · build ✅ · typecheck ✅ · tests n/a (skill-prose-only) · lint n/a (Trunk is not installed locally)
Found: 0 critical, 0 important, 0 suggestions
Approve
Review run
https://oz.staging.warp.dev/runs/01a03ada-1aaf-7d36-99cd-17c3a7be5c62
…ot carry Setting the drift-watch schedule up surfaced two configuration decisions the skill never mentions, both of which change what a run does and neither of which is recoverable from the prompt text. Run identity. Quick run is the default in the agent picker, and it executes as the calling user -- so its PRs are authored by that person, which for a schedule means whoever created it. Selecting a cloud agent runs as that agent, and with team GitHub authorization its PRs are authored by the Warp Factories GitHub App. A schedule that opens PRs wants the agent. This is easy to get wrong from observation alone: the two validation runs were quick runs and their PRs were authored by a human, which looks like evidence that agent selection does not affect authorship. It is not -- those runs never selected an agent. Skill inheritance. A run inherits every skill on the agent it runs as, and the schedule form does not let you detach an agent-level skill. Pointing drift-watch at the existing general-purpose docs agent pulled release_updates in, a weekly job that defaults to running all of its tasks, onto a daily trigger. The fix is a dedicated agent, not a different skills selection. Co-Authored-By: Warp <agent@warp.dev>
1 participant
Summary
Catch-all for the fast-follow items accumulated while validating the drift-watch pipeline. Documentation-only — no script or behavior changes.
Each item was reproduced against the current code rather than carried over from run notes. Two items from the original feedback list turned out to be already handled and are not included:
git checkout <ref> -- <files>;stashappears nowhere in the skill.Changes
1. Snapshot regen has an unstated environment precondition.
--update-snapshotrewrites the baseline from whatever the sibling repos hold at that moment and cannot tell a current checkout from a stale one. Regenerating from a feature-branchedwarpor a months-oldwarp-serversilently writes surfaces that aren't on the default branch — and the next--diffthen compares two wrong baselines and reports the gap as real drift. The skill says "regenerate with--update-snapshot; never hand-edit" and nothing about where it's valid to do so.This came up concretely during the #624 rebase: the snapshot conflict looked like it needed regeneration, and regenerating locally would have corrupted it. Running the newly documented check on this machine:
A feature branch and a three-month-old checkout. Neither is a valid basis for a snapshot.
2. Gate 0 lacked the Early Access case. A published docs page describing a feature is not evidence that its API is released — EA features routinely have public prose while their REST routes stay out of the released spec. The
/factoryroutes are exactly this shape:factories/factory-api.mdxdescribes dispatching a run, but no/factorypath appears indevelopers/agent-api-openapi.yaml. Both drift-watch runs deferred them correctly, but on judgment rather than a written rule, and the next run has to re-derive it.3. Slash-command coverage is repo-wide, not surface-scoped.
audit_slash_commandscounts a command as covered when any docs page mentions it. So/usageread as covered from the GUI slash-commands page while both CLI pages omitted it, and only the changelog cross-check caught the gap. The CLI and settings audits scope their search to the pages that own those surfaces; this one searches everything.Recorded as a known limitation rather than fixed here. Narrowing the scope changes which commands become findings, so it needs its own PR and a look at the resulting volume — not a line buried in a catch-all.
4. warp-server findings routinely resolve to no owner. The warp client repo has a root ownership rule so nearly any path resolves; warp-server has none, and the
/factoryhandlers carry no entry. Reproduced directly:Post-#619 this lands on the
dannyneirafallback rather than shipping unreviewed, so the remaining gap is reporting: the run should call this the fallback working, not a resolution failure. The real fix belongs in warp-server's ownership file — noted in the skill, with an explicit instruction not to hardcode an owner in the docs repo to paper over it.5. The schedule's two setup choices were undocumented. Added after configuring the real schedule, which surfaced both.
Run identity. Quick run is the agent picker's default and executes as the calling user, so its PRs are authored by that person — for a schedule, whoever created it. Selecting a cloud agent runs as that agent, and with team GitHub authorization its PRs are authored by the Warp Factories GitHub App. A schedule that opens PRs wants the agent.
This one is genuinely trap-shaped, and I fell in it during review of this very pipeline: both validation runs were quick runs whose PRs were authored by a human, which reads like evidence that agent selection doesn't affect authorship. It isn't — those runs never selected an agent. The skill now states the rule so nobody has to re-derive it from misleading observations.
Skill inheritance. A run inherits every skill attached to the agent it runs as, and the schedule form won't let you detach an agent-level skill. Pointing drift-watch at the existing general-purpose docs agent pulled in
release_updates— a weekly job that defaults to running all of its tasks — onto a daily trigger. The fix is a dedicated agent, not a different skills selection.Verification
suggest_reviewers.pyagainst both factory handler paths; output above.audit_slash_commandsinscripts/audit_docs.py) rather than from notes.Additions only, in regions #630 doesn't touch, so the two should merge in either order.
Caveat on item 4: the local
warp-servercheckout is from 2026-05-21, so factory ownership entries may exist upstream by now. The skill text is written so that resolution starts working automatically if they do, with no further change.Rework changes
warpdefault branch ismain;warpdotdev/warp's actual remoteHEADismaster. Updated the line to saymasterforwarp,developforwarp-server(commit 1205a1a). Verified via the GitHub API thatwarpdotdev/warp's default branch ismaster.Co-Authored-By: Warp agent@warp.dev