Add write-feature-docs skill#26
Conversation
Engineer-facing skill that drafts the first ~80% documentation page for a new Warp feature from its PRODUCT.md and/or TECH.md spec. Part of the eng-owned docs workflow: reads the feature spec, generates a concise outline for the engineer to confirm technical accuracy, then produces a complete MDX draft ready for a draft PR to warpdotdev/docs. Includes: - Outline generation with terminal-based confirmation (no Ask_User_Question for the main flow — free-form reply keeps it low friction for engineers) - No-spec fallback via Ask_User_Question interview - Warp docs style rules baked in (sentence case headings, bold+dash lists, UI element formatting, active voice, frontmatter description standards) - Handoff instructions pointing engineers to warpdotdev/docs draft PR Companion to write-product-spec and write-tech-spec. Co-Authored-By: Oz <oz-agent@warp.dev>
|
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 |
![oz-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 adds a new write-feature-docs common skill that turns PRODUCT.md and optional TECH.md specs into an outline and MDX draft for Warp feature documentation.
Concerns
- The no-spec fallback references
Ask_User_Question, but existing common-skills guidance usesask_user_question; this can break the interactive fallback path when no spec files exist. - The handoff instructions tell engineers to open public docs draft PRs for feature docs by default, which can disclose unreleased feature details before launch approval.
README.mdwas not updated to listwrite-feature-docsunder the current skills, so repository-level discovery will be stale.
Security
- The docs handoff should not default to public PRs unless the feature is already safe to discuss publicly.
Verdict
Found: 0 critical, 2 important, 1 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
|
|
||
| ## No-spec fallback | ||
|
|
||
| If `specs/<id>/PRODUCT.md` and `specs/<id>/TECH.md` don't exist, use `Ask_User_Question` to interview the engineer. Ask about: |
There was a problem hiding this comment.
Ask_User_Question does not match the existing common-skills tool spelling, so agents may not invoke the interview step when no spec exists.
| If `specs/<id>/PRODUCT.md` and `specs/<id>/TECH.md` don't exist, use `Ask_User_Question` to interview the engineer. Ask about: | |
| If `specs/<id>/PRODUCT.md` and `specs/<id>/TECH.md` don't exist, use `ask_user_question` to interview the engineer. Ask about: |
| > | ||
| > 1. Save this file to the `warpdotdev/docs` repo at the proposed path above | ||
| > 2. Add an entry for it in `src/sidebar.ts` under the appropriate section | ||
| > 3. Open a **draft PR** in `warpdotdev/docs` — feature docs PRs don't need to be kept private before launch |
There was a problem hiding this comment.
1 participant
Summary
Adds the
write-feature-docsskill — an engineer-facing skill that drafts the first ~80% documentation page for a new Warp feature from itsPRODUCT.mdand/orTECH.mdspec.This is the core artifact for the eng-owned docs workflow. Platform engineers run this skill from
warp-internalorwarp-serveralongside the existingwrite-product-spec/write-tech-specskills.How it works
specs/<id>/PRODUCT.md+ optionallyTECH.mdwarpdotdev/docsNo-spec fallback uses
Ask_User_Questionto interview the engineer when no spec exists.Key design decisions
warpdotdev/docs AGENTS.md[TODO: docs reviewer]placeholders — skill marks screenshots, video embeds, and unconfirmed UI paths so the docs team knows exactly what to fill inCo-Authored-By: Oz oz-agent@warp.dev