skills: retire scan-new-specs and remove write-feature-docs ambient mode - #77
Merged
Conversation
scan-new-specs fired on spec merge, which happens before a feature ships. That one design choice produced both failure modes we saw: docs drafted for unreleased and sometimes abandoned work, and every spec treated as a docs task with nothing asking whether the change warranted documentation. Replace the skill body with a deprecation notice that explains why it was retired and redirects to the replacement. The description field leads with DEPRECATED so an agent scanning descriptions does not select it. Its schedule (0ITuF9vNJ1RiO00Szlm1fW) stays paused. Remove ambient mode from write-feature-docs. It existed only so scan-new-specs could drive the skill headlessly, and it worked by skipping the outline confirmation -- the one checkpoint where a human could redirect a draft before the prose was written. Replace the section with an explicit statement that there is no unattended path and a note not to re-add one, so the next author does not rebuild it. write-feature-docs stays useful for its original purpose: an engineer invoking it directly, present to confirm the outline and the TECH.md boundary. Its Step 5 now also requires the docs repo's worthiness gateStep 5 now also requires the docs repo's worthiness gateStep 5 now also requia page is not by itself evidence the page should exist -- the most common failure is drafting for something that has not shipped. Co-AuthoreCo-AuthoreCo-AuthoreCo-AuthoreCo-AuthoreCo-AuthoreCo-AuthoreCo-AuthoreCotxt
Contributor
|
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}
Contributor
There was a problem hiding this comment.
Overview
This PR retires scan-new-specs and removes the unattended ambient path from write-feature-docs, redirecting automated docs gap detection to missing_docs and adding docs-worthiness/content-design requirements before PR creation.
Concerns
- The updated
write-feature-docsskill description drops the existingstarting the eng-docs workflowtrigger phrase even though the skill remains the direct, engineer-led eng-docs workflow. That can make agents fail to select this skill for an existing supported request shape. - No security findings were identified in the changed skill text.
spec_context.mdcontains no approved or repository spec context, so no material spec drift was found.
Verdict
Found: 0 critical, 1 important, 0 suggestions
Request changes
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
Step 5 required the full worthiness gate before opening a PR, including the judgment gates about whether a change warrants docs at all. That is the wrong bar for this skill: it is invoked by an engineer who wrote the feature and usually knows more about who needs the docs than the gate can infer. Keep the factual half. "Has this shipped and is the surface public" is worth verifying regardless of who asked, because an engineer close to the work can easily be a release ahead of their users, and drafting for something unshipped was the most common failure in the retired pipeline. Drop the judgment half. Those gates govern the automated pipeline in warpdotdev/docs, not an engineer asking for docs on their own shipped feature. Co-Authored-By: Warp <agent@warp.dev>
…in Step 3 Step 5 asked for a content design plan at PR time, which is too late to be useful. By then the prose exists, so the engineer can only react to a finished page -- the plan becomes a form to fill in rather than a decision to make. The skill already has the right checkpoint. Step 3 presents an outline and waits for confirmation before drafting. Present the plan there too, in the same message, so the engineer confirms audience and shape in one pass. They answer different questions and both are worth confirming early: the outline says what sections the page will have, the plan says who it is for and which scenarios it deliberately leaves out. Getting either wrong after the draft exists means rewriting it. Step 5 now just carries the confirmed plan into the PR body, and points at .agents/templates/content-design-plan.md rather than restating the fields. Co-Authored-By: Warp <agent@warp.dev>
…e it Presenting the content design plan and the outline in one message was the same mistake as putting the plan in the PR body, one level down: showing a derived artifact before the decision it derives from has been agreed. The outline is downstream of the plan. The plan picks the content type, and the content type determines what sections the outline has. Presenting both at once shows the engineer an outline built on an audience they have not approved, and invites them to anchor on the concrete sections in front of them instead of questioning the audience above them. If they then change the reader, the outline was wasted work. Split into two sequential checkpoints: 3. Present the content design plan, wait for confirmation -- who the page is for 4. Present the outline, wait for confirmation -- what the page will contain Drafting, screenshots, and the PR renumber to 5, 5.5, and 6. Cross-references updated; the Step 1-4 labels inside the screenshot capture protocol are local sub-steps and deliberately left alone. Step 4 also now says to revise the plan if outline feedback contradicts it. The plan travels into the PR body, so a stale one misleads the reviewer. The cost is one extra round trip. The plan is seven short fields, and the alternative is redrafting an outline built on the wrong reader. Also fixed the embedded MDX sketch in the drafting step, which still showed a body "# [Feature name]" H1 and no frontmatter title -- the exact pattern just removed from the docs repo templates. It now points at the canonical templates in .agents/templates/ as the source of truth rather than carrying a duplicate that drifts, and calls out the two rules easiest to get wrong from memory. Co-Authored-By: Warp <agent@warp.dev>
Dropping "starting the eng-docs workflow" from the description removed a routing surface. The interactive engineer-led workflow is still supported, so an engineer who asks for it by its old name should still land here. Agents match on the description, and that phrase was the only thing catching the legacy name. Caught by warp-for-oss[bot] on PR #77. Restored, with "eng-owned docs" added alongside it since both names are in use for the same workflow. Did not apply the bot's suggestion verbatim. It was generated against an earlier commit and still said "confirms an outline before drafting", so accepting it would have reverted the two-checkpoint change to confirm the content design plan before the outline. Took the intent and left the rest of the description alone. The phrase is now ambiguous in one direction -- it could mean the retired auto-draft-on-merged-spec trigger rather than interactive drafting. That is already handled: the description says the skill requires an interactive session and points automated, release-triggered work at missing_docs. Co-Authored-By: Warp <agent@warp.dev>
The phrase was never in circulation outside the two people who coined it, so it adds no routing value and reads as an artifact of a name we are moving away from. Keeping only 'eng-docs workflow', which was the phrase actually shipped in the description and the one warp-for-oss[bot] asked to preserve. Co-Authored-By: Warp <agent@warp.dev>
hongyi-chen
approved these changes
Aug 26, 2026
common-skills-sync Bot
added a commit
to warpdotdev/warp
that referenced
this pull request
Aug 26, 2026
## Description Updates `skills-lock.json` to distribute the common skills from [warpdotdev/common-skills#77](warpdotdev/common-skills#77). ## Testing Generated with `scripts/update_common_skills_lock`. Co-authored-by: rachaelrenk <91027132+rachaelrenk@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Retires
scan-new-specsand removes ambient mode fromwrite-feature-docs.scan-new-specsfired on spec merge, which happens before a feature ships. That single design choice produced both failure modes we saw inwarpdotdev/docs:Its schedule (
0ITuF9vNJ1RiO00Szlm1fW) has been paused since 2026-07-31 and stays paused.Changes
scan-new-specs→ deprecation noticeReplaces the skill body with a notice explaining why it was retired and where to go instead. The
descriptionfield leads with DEPRECATED so an agent scanning descriptions to pick a skill does not select it, and the body names the three cases someone might arrive with (looking for docs gaps, wanting docs for their feature, setting up a scheduled agent) and redirects each.write-feature-docs— ambient mode removedAmbient mode existed only so
scan-new-specscould drive the skill headlessly, and it worked by skipping the outline confirmation — the one checkpoint where a human could redirect a draft before the prose was written. It also had to treat allTECH.md-derived content as unpublishable, because no engineer was present to say what was confidential.The section is replaced with an explicit statement that there is no unattended path, plus a note not to re-add one. Without that, the next author rebuilds it.
The skill stays useful for its original purpose: an engineer invoking it directly, present to confirm the outline and the
TECH.mdboundary. Itsdescriptionnow says so, and points automated callers atmissing_docs.Step 5 additionally requires two things from the docs repo before opening a PR:
The remaining worthiness gates are judgment calls that govern the automated pipeline, not this skill. An engineer asking for docs on their own shipped feature has context the gate cannot see, so the skill does not decline on those grounds.
Replacement
missing_docsinwarpdotdev/docs, running in drift-watch mode. It differs in the two ways that mattered:.agents/references/docs-worthiness-criteria.mdbefore anything is drafted, with verdicts recorded so rejections are not re-litigated.Merge order
Merge warpdotdev/docs#586 first. This PR references
.agents/references/docs-worthiness-criteria.mdand.agents/references/content-design-plan.mdby path, and both are created there.There is no urgency on this one:
scan-new-specsis already paused and cannot fire, so this PR documents a decision already in effect rather than being the thing that stops the flooding.Validation
scan-new-specsanywhere else in the repo.write-feature-docs, including theTECH.mdhandling note and the engineer-handle lookup path that both previously branched on it.Co-Authored-By: Warp agent@warp.dev