From f39a55ecbb86e35b7374bac045d318dc6d2683a2 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Fri, 12 Jun 2026 10:50:40 -0600 Subject: [PATCH 1/3] Add write-feature-docs skill MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- .agents/skills/write-feature-docs/SKILL.md | 213 +++++++++++++++++++++ 1 file changed, 213 insertions(+) create mode 100644 .agents/skills/write-feature-docs/SKILL.md diff --git a/.agents/skills/write-feature-docs/SKILL.md b/.agents/skills/write-feature-docs/SKILL.md new file mode 100644 index 0000000..528b5a4 --- /dev/null +++ b/.agents/skills/write-feature-docs/SKILL.md @@ -0,0 +1,213 @@ +--- +name: write-feature-docs +description: Draft the first ~80% documentation page for a new Warp feature from its PRODUCT.md and/or TECH.md spec. Use when an engineer has written a spec and needs to produce a first-pass MDX draft for the warpdotdev/docs repo. Also handles features without specs via an interactive interview. Invoke this skill whenever an engineer mentions writing docs for a feature, drafting a docs page, creating feature documentation, starting the eng-docs workflow, or converting a spec into documentation. Works from warp-internal or warp-server. +--- + +# write-feature-docs + +Draft the first ~80% documentation page for a new Warp feature. You read the feature's spec, generate a concise outline for the engineer to confirm, then produce a complete MDX draft ready for a draft PR to `warpdotdev/docs`. + +The engineer's job is to verify **technical accuracy** — not polish prose, fix formatting, or know docs conventions. Your job is everything else. + +## The workflow + +1. Find the spec files for the feature +2. Generate a concise outline and present it in the terminal +3. Engineer confirms the outline is accurate (or replies with corrections) +4. Generate the full ~80% MDX draft from the confirmed outline +5. Tell the engineer how to submit it as a draft PR to `warpdotdev/docs` + +--- + +## Step 1: Find the spec + +Ask the engineer for the spec ID if they haven't provided it. The spec ID is one of: +- A Linear ticket number: `APP-1234` +- A GitHub issue (prefixed with `gh-`): `gh-4567` +- A short kebab-case feature name: `vertical-tabs-hover-sidecar` + +Look for the spec files at: +- `specs//PRODUCT.md` — primary source: user-facing behavior, what and why +- `specs//TECH.md` — secondary source: implementation, data model + +Read both files if both exist. `PRODUCT.md` is the primary driver for the docs content. Reference `TECH.md` only to check technical accuracy and understand implementation constraints — don't let implementation details leak into the user-facing prose. + +If neither file exists, skip to [No-spec fallback](#no-spec-fallback). + +--- + +## Step 2: Generate and present the outline + +Read the spec(s) and generate a concise outline. **The outline has no prose** — its purpose is to give the engineer a quick technical accuracy check before you write anything. + +Print the outline to the terminal in this format: + +``` +📄 Docs outline for [Feature name] + +PROPOSED PLACEMENT + Section: src/content/docs/
/ (e.g., agent-platform/cloud-agents/) + File: .mdx + URL: docs.warp.dev// + +CONTENT SECTIONS + H1: + Opening paragraph: [1-sentence description of what you'll write] + ## Key features — [which 2-4 capabilities to highlight as bullets] + ## How it works — [the conceptual model: what and why, no steps] + ## — [e.g., "Creating environments", "Configuring X"] + Prerequisites: [any prerequisites to list] + Steps: + 1. [Step description] + 2. [Step description] + 3. [Step description] + ... + ## Related pages — [cross-links to suggest] + +KEY TERMS TO VERIFY + - "": [your understanding — confirm this is accurate] + - "": [your understanding — confirm this is accurate] +``` + +After printing the outline, say: + +> "Does this outline accurately represent the feature? Reply with any corrections or say 'looks good' to proceed to the full draft." + +Wait for the engineer's reply before continuing. Their reply is a free-form terminal response — they may correct steps, rename concepts, add missing behavior, or just confirm. Incorporate their feedback before drafting. + +--- + +## Step 3: Generate the MDX draft + +Generate a complete `.mdx` file based on the confirmed outline. The output should be ready to drop into `src/content/docs/
/.mdx` in the `warpdotdev/docs` repo. + +### Template structure + +```mdx +--- +description: >- + [1-2 sentence standalone summary. Lead with the user benefit. Include the + feature name and a key term or two so it works as a search result snippet.] +--- + +# [Feature name] + +[Opening paragraph: what the feature does and its primary benefit. +1-3 sentences. Lead with what the user can accomplish, not the implementation.] + +:::note +[Optional: key context the reader needs upfront — a prerequisite, a limitation, +or when NOT to use this feature. Delete this callout if nothing applies.] +::: + +## Key features + +* **Feature A** - What it does and why it matters to the user. +* **Feature B** - What it does and why it matters to the user. + +## How it works + +[CONCEPTUAL section: explain system behavior, data flow, or architecture. +Answer "what" and "why" before "how." Define any new terms when they +first appear. Do NOT include step-by-step procedures in this section — +keep conceptual and procedural content clearly separated.] + +## [Usage section title] + +[PROCEDURAL section: motivate the task first, then give numbered steps. +Briefly explain why the user is doing this before telling them how.] + +### Prerequisites + +* **[Prerequisite]** - What it is and where to get it. See [full reference](link-here). + +### [Task name — sentence case, e.g., "Create an environment with the CLI"] + +1. First step. Expected outcome if not obvious. +2. Second step. +3. Third step. + +## Related pages + +* [Related feature](../path/to/page.md) +* [Deeper guide](../path/to/guide.md) +``` + +### Style rules — apply exactly + +These conventions come from the Warp docs style guide and must be followed: + +**Headings** +- Sentence case for all headings: capitalize only the first word and proper feature names +- Proper feature names keep their capitalization: "Agent Mode", "Warp Drive", "Oz", "Command Palette" +- ✅ `## How it works` — ❌ `## How It Works` +- ✅ `## Agent Mode settings` — ❌ `## Agent mode settings` + +**Lists** +- Bold term + dash + description: `* **Term** - Description` +- Never use a colon: ❌ `* **Term**: Description` + +**UI elements and paths** +- Bold for buttons, links, menu items: `Click **Save**`, not `` Click `Save` `` +- Bold each segment in a Settings path, leave `>` plain: `**Settings** > **AI** > **Knowledge**` + +**Voice and tone** +- Second person: "you can," "allows you to" +- Active voice: "Warp indexes your codebase" — not "your codebase is indexed" +- Avoid "simple," "easy," "just" — these dismiss the reader's experience +- Present tense for how things work; imperative for instructions + +**Frontmatter description** +- Write as a standalone summary that works as a search result snippet +- Lead with user benefit, include the feature name and key terms +- ✅ `Environments ensure your cloud agents run with a consistent toolchain. Learn when to use environments and how to configure them.` +- ❌ `This page describes environments.` + +**Callout syntax** (Astro Starlight) +- `:::note` — supplemental context, tips +- `:::caution` — caveats, limitations +- `:::danger` — destructive or irreversible actions +- `:::tip` — confirmation of expected outcomes + +**What to leave as placeholders** +Mark these with `[TODO: docs reviewer — ...]` in the draft: +- Screenshots (you can't capture live UI) +- Video/GIF embeds +- Exact Settings path if the feature hasn't shipped yet +- Final URL path (docs team confirms placement) +- Any behavior you're uncertain about after reading the spec + +--- + +## No-spec fallback + +If `specs//PRODUCT.md` and `specs//TECH.md` don't exist, use `Ask_User_Question` to interview the engineer. Ask about: + +1. What this feature does in one sentence +2. The 2–3 most important things a user can do with it +3. The step-by-step actions a user takes to use it +4. Any prerequisites, limitations, or gotchas the reader needs to know +5. Any related features or pages to cross-reference + +Build the outline from their answers, then present it for confirmation (Step 2) before drafting. Don't skip the outline confirmation step — it's the engineer's technical accuracy check regardless of whether a spec exists. + +--- + +## Step 4: Handoff instructions + +After presenting the draft, tell the engineer: + +> "Here's your ~80% draft. To hand it off for docs review: +> +> 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 +> +> The docs team will take it from there: terminology, readability, screenshots, final placement, navigation, and redirects." + +--- + +## Related skills + +- `write-product-spec` — produces the `PRODUCT.md` this skill reads +- `write-tech-spec` — produces the `TECH.md` this skill reads From 33e983e3c27969d97bfecf3f7dec2477e97c29ef Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Tue, 16 Jun 2026 11:05:42 -0700 Subject: [PATCH 2/3] Apply suggestion from @oz-for-oss[bot] Co-authored-by: oz-for-oss[bot] <277970191+oz-for-oss[bot]@users.noreply.github.com> --- .agents/skills/write-feature-docs/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.agents/skills/write-feature-docs/SKILL.md b/.agents/skills/write-feature-docs/SKILL.md index 528b5a4..cdb5db8 100644 --- a/.agents/skills/write-feature-docs/SKILL.md +++ b/.agents/skills/write-feature-docs/SKILL.md @@ -181,7 +181,7 @@ Mark these with `[TODO: docs reviewer — ...]` in the draft: ## No-spec fallback -If `specs//PRODUCT.md` and `specs//TECH.md` don't exist, use `Ask_User_Question` to interview the engineer. Ask about: +If `specs//PRODUCT.md` and `specs//TECH.md` don't exist, use `ask_user_question` to interview the engineer. Ask about: 1. What this feature does in one sentence 2. The 2–3 most important things a user can do with it From fb0b4e8cf51a4fcf74f02b51fec7a764e3a2d81f Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Tue, 16 Jun 2026 15:51:49 -0600 Subject: [PATCH 3/3] Add scan-new-specs ambient trigger skill MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Scheduled Oz agent skill that scans warp-internal and warp-server for recently merged PRODUCT.md specs without a corresponding docs PR in warpdotdev/docs. Posts Slack nudges to #growth-docs for each gap. This is the automated trigger companion to write-feature-docs — removes the dependency on engineers remembering to kick off the docs workflow. Behavior: - Looks back N days (default: 3) for merged PRs that added specs/*/PRODUCT.md - Checks warpdotdev/docs for any open/merged/draft PR covering each spec - Posts grouped Slack nudge(s) to #growth-docs for uncovered specs - Falls back to stdout if SLACK_WEBHOOK_URL is not configured - Prints a run summary every time Suggested schedule: Mon/Wed/Fri at 9am PT. Note: deduplication is PR-based (no persistent state). A spec stops generating nudges once any docs PR is opened, even a draft. Co-Authored-By: Oz --- .agents/skills/scan-new-specs/SKILL.md | 138 +++++++++++++++++++++++++ 1 file changed, 138 insertions(+) create mode 100644 .agents/skills/scan-new-specs/SKILL.md diff --git a/.agents/skills/scan-new-specs/SKILL.md b/.agents/skills/scan-new-specs/SKILL.md new file mode 100644 index 0000000..09ff9a7 --- /dev/null +++ b/.agents/skills/scan-new-specs/SKILL.md @@ -0,0 +1,138 @@ +--- +name: scan-new-specs +description: Scan warp-internal and warp-server for recently merged PRODUCT.md specs that don't yet have a corresponding docs PR in warpdotdev/docs, then post Slack nudges to a configured channel. Designed to run as a scheduled Oz ambient agent (e.g., every 2-3 days). Use when setting up the automated docs trigger, running a manual docs coverage sweep, or checking whether any new specs are missing documentation. +--- + +# scan-new-specs + +Scan `warp-internal` and `warp-server` for recently merged specs that lack a corresponding docs draft, and post a Slack nudge to `#growth-docs` for each gap. This is the automated companion to the `write-feature-docs` skill — it surfaces docs gaps so the docs team can follow up with the engineer, without requiring engineers to remember to kick off the docs-drafting workflow themselves. + +## Configuration + +Before running, confirm these values (or accept the defaults): + +| Setting | Default | Description | +|---|---|---| +| `LOOKBACK_DAYS` | `3` | How many days back to scan for merged spec PRs | +| `SLACK_CHANNEL` | `#growth-docs` | Slack channel to post nudges to | +| `SLACK_WEBHOOK_URL` | Required | Slack incoming webhook URL (should be stored as a secret) | + +If `SLACK_WEBHOOK_URL` is not set in the environment, print the nudge messages to stdout instead so the output can be reviewed manually. + +## Step 1: Find recently merged specs + +Use the GitHub CLI to search both repos for PRs merged in the last `LOOKBACK_DAYS` days that added a new `PRODUCT.md` file under `specs/`: + +```bash +# Find merged PRs in warp-internal that added a PRODUCT.md +gh pr list \ + --repo warpdotdev/warp-internal \ + --state merged \ + --search "merged:>$(date -v-${LOOKBACK_DAYS}d +%Y-%m-%d) specs PRODUCT.md in:files" \ + --json number,title,author,mergedAt,url \ + --limit 50 + +# Repeat for warp-server +gh pr list \ + --repo warpdotdev/warp-server \ + --state merged \ + --search "merged:>$(date -v-${LOOKBACK_DAYS}d +%Y-%m-%d) specs PRODUCT.md in:files" \ + --json number,title,author,mergedAt,url \ + --limit 50 +``` + +For each PR returned, verify it actually contains a new `specs/*/PRODUCT.md` by inspecting the files changed: + +```bash +gh pr view --repo warpdotdev/ --json files -q '.files[].path' \ + | grep -E '^specs/.+/PRODUCT\.md$' +``` + +Collect the list of: spec ID (the directory name under `specs/`), spec PR number and URL, PR author GitHub username, repo (`warp-internal` or `warp-server`), and merge date. + +## Step 2: Check for existing docs coverage + +For each spec found, search `warpdotdev/docs` for an open or recently merged PR that mentions the spec ID or feature name: + +```bash +gh pr list \ + --repo warpdotdev/docs \ + --state all \ + --search "" \ + --json number,title,state,url \ + --limit 10 +``` + +A spec is considered **covered** if any matching PR exists (open, merged, or draft). Skip covered specs — do not send a nudge. + +A spec is **uncovered** if no matching PR is found in `warpdotdev/docs`. + +## Step 3: Build the nudge messages + +For each uncovered spec, compose a Slack message. Keep it brief and actionable: + +``` +📄 *New spec merged, no docs yet* + +Feature: ** (from ``) +Spec PR: +Merged by: @ on + +To create the docs draft, run `write-feature-docs` from `` with spec ID ``. +``` + +Group multiple nudges into a single Slack message when possible to avoid spamming the channel. Use a summary header if there are 3+ uncovered specs: + +``` +📄 *Docs coverage scan — specs need docs* + + +``` + +If there are no uncovered specs, post a single brief message: + +``` +✅ *Docs coverage scan complete* — all recently merged specs have docs coverage. +``` + +## Step 4: Post to Slack + +Send the composed message to `SLACK_CHANNEL` via the incoming webhook: + +```bash +curl -s -X POST "$SLACK_WEBHOOK_URL" \ + -H 'Content-type: application/json' \ + --data "{\"text\": \"$MESSAGE\"}" +``` + +If `SLACK_WEBHOOK_URL` is not set, print the message to stdout instead and note that no Slack notification was sent. + +## Step 5: Print a summary + +Always print a run summary to stdout: + +``` +scan-new-specs run summary + Repos scanned: warp-internal, warp-server + Lookback window: days (since ) + Specs found: + Already covered: + Nudges sent: + Slack channel: +``` + +## Scheduling + +This skill is designed to run as a **scheduled Oz ambient agent** every 2–3 days. A suggested prompt for the Oz agent configuration: + +> "Run scan-new-specs to check warp-internal and warp-server for newly merged PRODUCT.md specs that don't have a corresponding docs PR in warpdotdev/docs. Post nudges to #growth-docs for any gaps. Use the last 3 days as the lookback window." + +Suggested schedule: every Monday, Wednesday, and Friday at 9am PT — frequent enough to catch specs quickly, but not noisy. + +## Deduplication note + +This skill does not maintain persistent state between runs. Deduplication relies entirely on whether a docs PR exists in `warpdotdev/docs` — if a PR is open or merged for a spec, it won't be flagged again. This means a spec will continue to generate nudges until someone opens a docs PR for it (even a draft). + +## Related skills + +- `write-feature-docs` — the skill engineers run to generate the docs draft after being nudged