scan-new-specs

by warpdotdev

Scan warpdotdev/warp and warp-server for recently merged PRODUCT.md specs that don't yet have a corresponding docs PR in warpdotdev/docs. When a complete spec is found, auto-generates a full docs draft PR and tags the engineer. When a spec is too thin to draft from, pings the engineer directly. Designed to run as a scheduled Oz ambient agent (e.g., every 2-3 days). Use when setting up the automated docs trigger or running a manual docs coverage sweep.

npx skills add https://github.com/warpdotdev/common-skills --skill scan-new-specs
Download ZIPGitHub
223
Try this skillSponsored

scan-new-specs (deprecated)

Retired 2026-08-20. Do not invoke this skill and do not schedule it.

Its scheduled agent (0ITuF9vNJ1RiO00Szlm1fW) is paused and stays paused.

Why it was retired

The skill fired on spec merge, which happens before a feature ships. Two failures followed from that single design choice:

  • It drafted docs for unreleased and sometimes abandoned work. A merged spec is not a shipped feature. The agent had no evidence of what users had actually received, so pages were written for behavior that had not landed, or had landed differently, or never landed at all.
  • It treated every spec as a docs task. Nothing asked whether a change warranted documentation. Pure UI changes, small intuitive additions, and behind-the-scenes work all became draft PRs, and the docs repo accumulated unvetted content debt faster than anyone could review it.

What replaces it

The missing_docs skill in warpdotdev/docs, running in drift-watch mode. It differs in the two ways that matter:

  • Release-triggered. scripts/check_new_release.py gates each run on a new stable release, so the pipeline sees what actually shipped rather than what was planned. A daily schedule does per-release work.
  • Gated on worthiness. Every candidate is evaluated against .agents/references/docs-worthiness-criteria.md before anything is drafted, with a default of no docs and a requirement to name concrete evidence. Verdicts, including rejections, are recorded in references/changelog_decisions.md so nothing is re-litigated.

Anything genuinely worth documenting re-surfaces there once it ships.

If you were about to run this

  • Looking for docs gaps? Run missing_docs in drift-watch mode from the warpdotdev/docs repo.
  • You are an engineer who wants docs for your feature? Invoke write-feature-docs directly and interactively. It still works, and it still walks you through spec research and outline confirmation. It no longer runs headlessly.
  • Setting up a scheduled docs agent? Use missing_docs, not this. Scheduling this skill reintroduces exactly the flooding it was retired for.

Related skills

  • missing_docs (in warpdotdev/docs) — the release-triggered, worthiness-gated replacement
  • write-feature-docs — still supported for direct, interactive use by an engineer

More skills from warpdotdev

council
warpdotdev
Run a model-diverse subagent council to investigate the same problem from multiple perspectives, compare findings, and produce a final recommendation. Use this skill whenever the user asks for a council, second opinions, multiple agents/models to evaluate one question, parallel investigation, red-team/blue-team comparison, or help deciding between competing technical approaches.
researchcommunicationproject-management
spec-driven-implementation
warpdotdev
Drive a spec-first workflow for substantial features by writing PRODUCT.md before implementation, writing TECH.md when warranted, and keeping both specs updated as implementation evolves. Use when starting a significant feature, planning agent-driven implementation, or when the user wants product and tech specs checked into source control.
developmentdocumentproject-management
review-pr
warpdotdev
Review a pull request diff and write structured feedback to review.json for the workflow to publish. Use when reviewing a checked-out PR from local artifacts like pr_diff.txt and pr_description.txt and producing machine-readable review output instead of posting directly to GitHub.
code-reviewdevelopment
create-pr
warpdotdev
Create a pull request in the warp repository for the current branch. Use when the user mentions opening a PR, creating a pull request, submitting changes for review, or preparing code for merge.
developmentcode-review
implement-specs
warpdotdev
Implement an approved feature from PRODUCT.md and TECH.md, keeping specs and code aligned in the same PR as implementation evolves. Use after the product and tech specs are approved and the next step is building the feature.
developmentcode-reviewapi
cross-critique
warpdotdev
Run a second round on a contested question by circulating each subagent's independent proposal to the other authors and asking for structured pros and cons, then synthesize. Use this skill whenever you have multiple independent proposals or opinions on a contested decision — architecture tradeoffs, code review disagreements, design choices, competing root-cause theories — and want sharper analysis than you'd produce by synthesizing alone. Pairs naturally with the council and research skills;...
resolve-merge-conflicts
warpdotdev
Resolve Git merge conflicts by extracting only unresolved paths, conflict hunks, and compact diffs instead of loading whole files into context. Use when a merge, rebase, cherry-pick, or stash pop stops on conflicts, when `git status` shows unmerged paths, or when files contain conflict markers.
developmentcode-review
brandalf
warpdotdev
Guides creation, revision, and review of Warp- or Oz-branded assets. Use when working on launch pages, docs, HTML/CSS components, UI mockups, prompts, social assets, copy, presentations, or any other branded deliverable that should look and sound unmistakably Warp or Oz.
designcreativemarketing