From 8a0f33f50297fac7b1b8a2072909ac4826a5804a Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Fri, 29 May 2026 10:58:45 -0600 Subject: [PATCH 1/3] docs: add AEO drafting workflow guidance Co-Authored-By: Oz --- .agents/skills/aeo_brief/SKILL.md | 96 ++++++++++++++++++++++++ .agents/skills/draft_docs/SKILL.md | 34 ++++++--- .agents/skills/draft_guide/SKILL.md | 45 +++++++---- .agents/skills/draft_procedural/SKILL.md | 19 ++++- .agents/skills/review-docs-pr/SKILL.md | 18 ++++- .agents/templates/guide-page.md | 6 +- .agents/templates/procedural.md | 6 +- 7 files changed, 192 insertions(+), 32 deletions(-) create mode 100644 .agents/skills/aeo_brief/SKILL.md diff --git a/.agents/skills/aeo_brief/SKILL.md b/.agents/skills/aeo_brief/SKILL.md new file mode 100644 index 00000000..7eebf170 --- /dev/null +++ b/.agents/skills/aeo_brief/SKILL.md @@ -0,0 +1,96 @@ +--- +name: aeo_brief +description: Build a source-grounded AEO brief for Warp docs using Peec data, existing docs, and product terminology. Use whenever a docs request mentions AEO, answer-engine optimization, SEO visibility, Peec recommendations, AI search prompts, content gaps, search-query vocabulary, or deciding whether to create new docs versus update existing docs. +--- + +# AEO brief + +Create a concise, source-grounded brief before drafting or revising AEO-driven Warp documentation. The brief should help the human reviewer decide what content is worth creating and help the drafting agent use the right vocabulary without turning the doc into a keyword dump. + +## When to use + +Use this skill when the user asks for docs work based on: +- AEO, answer-engine optimization, AI search visibility, or SEO goals +- Peec recommendations, prompts, topics, search queries, or source URLs +- A content gap, competitive/source-data comparison, or ranking opportunity +- A question about whether to create a new page, update an existing page, or avoid duplicative content + +If the task is not AEO-driven, use the normal docs drafting workflow instead. + +## Inputs to gather + +Start with the smallest set of inputs that can support a useful brief: +- **Goal** - What decision or draft should this brief support? +- **Target topic** - The feature, workflow, product area, or user problem. +- **Known source data** - Peec project, prompts, topics, recommendations, source URLs, or notes supplied by the user. +- **Target docs area** - Existing page, section, or proposed new page if known. +- **Open questions** - Anything that affects scope, placement, or product accuracy. + +Ask the user only when a missing input blocks the brief. Otherwise, use the available context and flag assumptions as open questions. + +## Peec research workflow + +Use the Peec MCP when available. Prefer source data over invented SEO advice. + +1. **Resolve the project.** Use `list_projects` if the project ID is not already known. +2. **Find relevant prompts.** Use `list_prompts` to identify prompts tied to the topic, tag, or project. Capture the exact prompt text when it informs the brief. +3. **Extract search-query vocabulary.** Use `list_search_queries` for the relevant prompts, topic, or date range. Group repeated phrasing and note user-language variants, not every raw query. +4. **Inspect recommendations.** Use `get_actions` with `scope=overview` first, then drill into the highest-opportunity slices that matter for docs content. Use the returned recommendation text as the source of truth. +5. **Review source URLs when useful.** Use `get_url_content` for specific source URLs when the brief needs to compare content coverage, language, or examples. + +Keep Peec output compact. The brief should explain what the data suggests, not reproduce a full report. + +## Repo research workflow + +Ground every recommendation in the current docs: +- Read `AGENTS.md` and `.agents/references/terminology.md` when drafting language or naming product surfaces. +- Search existing docs for the target topic before recommending a new page. +- Identify the best existing pages to update, link from, or avoid duplicating. +- Note when a proposed topic risks becoming a thin page or junk-drawer doc. + +## Vocabulary translation + +Translate AEO/source-data language into user-facing docs language: +- Preserve high-intent search terms when they are accurate and useful. +- Replace vague or internal shorthand with precise product names and UI surfaces. +- Explain the feature or workflow in plain developer language before using branded terms. +- Avoid keyword stuffing. AEO vocabulary should appear where it helps readers understand the page. + +Example pattern: +- **Source-data language** - “Track or observe AI agents in real time.” +- **Docs translation** - “Track and review cloud agent runs in the Agent Management Panel in the Warp app or the Runs page in the Oz web app.” + +## Brief format + +Return the brief in this structure: + +## AEO brief + +**Goal:** [What this brief supports.] + +**Recommendation:** [Create a new page, update an existing page, merge into another page, or do not pursue yet.] + +**Source signals:** +- [Peec prompt, search-query cluster, action recommendation, or source URL.] +- [Existing docs signal, gap, or duplication risk.] + +**Vocabulary map:** +- **Users/answer engines say:** [Raw or clustered phrase.] + **Docs should say:** [Natural, accurate Warp docs phrasing.] + +**Content scope:** +- **Include** - [High-value topics, procedures, examples, or links.] +- **Avoid** - [Junk-drawer coverage, duplicate explanations, unsupported claims, or outdated terms.] + +**Existing docs to touch or link:** +- `[path]` - [Why it matters.] + +**Open questions for human review:** +- [Question that affects accuracy, positioning, or scope.] + +## Handoff rules + +- If the user asked for a plan, use the brief as research context before creating the plan. +- If the user asked for a draft, use the brief before drafting and include only the decisions that matter in the final summary. +- If the brief shows the content should not be created, recommend the smaller update instead of forcing a new page. +- If Peec or Notion data is unavailable, say what could not be verified and proceed with repo-grounded recommendations. diff --git a/.agents/skills/draft_docs/SKILL.md b/.agents/skills/draft_docs/SKILL.md index 6b44a4ee..7b904d0b 100644 --- a/.agents/skills/draft_docs/SKILL.md +++ b/.agents/skills/draft_docs/SKILL.md @@ -14,6 +14,7 @@ Invoke this skill with any context that describes what you want to document: - Slack threads or meeting notes - Existing documentation that needs updating - A description of a feature or concept +- AEO, SEO, Peec, or answer-engine source data that should inform a draft Example: "Use the draft_docs skill to write docs for [feature name] based on this PRD: [context]" @@ -27,6 +28,14 @@ Review all provided context (PRD, spec, existing doc, etc.). Identify: - Key user benefits and capabilities - Technical details that need explaining +### 1.5. Create an AEO brief when source data drives the request +If the request mentions AEO, SEO, Peec, answer-engine visibility, search-query vocabulary, content gaps, or whether to create a new page versus update an existing page, read `.agents/skills/aeo_brief/SKILL.md` and create the brief before drafting. Use the brief to decide: +- Which page or section should change +- Which user/search vocabulary belongs in the draft +- Which product terms or UI surfaces need precise naming +- Which topics to avoid because they duplicate existing docs or create a junk-drawer page +- Which questions require human review before publishing + ### 2. Clarify placement Ask the user where the doc should live. The docs are organized into sections, each with its own `astro.config.mjs (sidebar config)`: - `src/content/docs/` - Warp Terminal and IDE → `docs.warp.dev/` @@ -46,14 +55,14 @@ Using the "Drafting by content type" section in `AGENTS.md`, determine which con | Content type | Use when | Template | Skill | |---|---|---|---| -| **Conceptual** | Explains what/why, no procedures | `.warp/templates/conceptual.md` | `draft_conceptual` | -| **Procedural** | Step-by-step task instructions | `.warp/templates/procedural.md` | `draft_procedural` | -| **Quickstart** | Fast path to a working result | `.warp/templates/quickstart.md` | `draft_quickstart` | -| **Reference** | Structured information for lookup | `.warp/templates/reference.md` | `draft_reference` | -| **Troubleshooting** | Problem → cause → solution | `.warp/templates/troubleshooting.md` | `draft_troubleshooting` | -| **FAQ** | Question-and-answer format | `.warp/templates/faq.md` | `draft_faq` | -| **Guide** | Task-oriented walkthrough (Guides section) | `.warp/templates/guide-page.md` | `draft_guide` | -| **Feature documentation** | Combined conceptual + procedural (most common) | `.warp/templates/feature-doc.md` | `draft_feature_doc` | +| **Conceptual** | Explains what/why, no procedures | `.agents/templates/conceptual.md` | `draft_conceptual` | +| **Procedural** | Step-by-step task instructions | `.agents/templates/procedural.md` | `draft_procedural` | +| **Quickstart** | Fast path to a working result | `.agents/templates/quickstart.md` | `draft_quickstart` | +| **Reference** | Structured information for lookup | `.agents/templates/reference.md` | `draft_reference` | +| **Troubleshooting** | Problem → cause → solution | `.agents/templates/troubleshooting.md` | `draft_troubleshooting` | +| **FAQ** | Question-and-answer format | `.agents/templates/faq.md` | `draft_faq` | +| **Guide** | Task-oriented walkthrough (Guides section) | `.agents/templates/guide-page.md` | `draft_guide` | +| **Feature documentation** | Combined conceptual + procedural (most common) | `.agents/templates/feature-doc.md` | `draft_feature_doc` | Once the content type is identified: - Use the corresponding **template** as the starting scaffold for the page. @@ -82,20 +91,23 @@ These rules are frequently violated by agents. Apply them carefully during draft - **Bold per-segment for Settings paths** — Use `**Settings** > **AI** > **Knowledge**` not `` `Settings > AI > Knowledge` `` ### 7. Draft the doc -Create the documentation using the appropriate template from `.warp/templates/`. Follow the structure for the identified content type and all rules in `AGENTS.md`. Each template includes visible bracketed instructions explaining what to put in each section. +Create the documentation using the appropriate template from `.agents/templates/`. Follow the structure for the identified content type and all rules in `AGENTS.md`. Each template includes visible bracketed instructions explaining what to put in each section. ### 8. Run style lint -Run `python3 .warp/skills/style_lint/style_lint.py --changed` on the drafted file to catch formatting and terminology issues before presenting to the user. +Run `python3 .agents/skills/style_lint/style_lint.py --changed` on the drafted file to catch formatting and terminology issues before presenting to the user. ### 9. Review against checklist Before presenting the draft, verify against the quality checklist in `AGENTS.md`: - [ ] Frontmatter includes clear description written as a standalone summary - [ ] Content follows the structure for its content type -- [ ] Terminology matches the glossary (`.warp/references/terminology.md`) +- [ ] Terminology matches the glossary (`.agents/references/terminology.md`) - [ ] Headers use sentence case (with proper feature name capitalization) - [ ] Lists use bold term + dash + explanation format - [ ] Cross-references to related features are included - [ ] Instructions include expected outcomes +- [ ] Procedures are scannable: dense sections are split into numbered steps, short bullets, or concise subsections +- [ ] UI surfaces and product terms use canonical names from `.agents/references/terminology.md` +- [ ] If AEO-driven, the draft follows the AEO brief, uses source vocabulary naturally, and avoids duplicative or junk-drawer coverage - [ ] Images have descriptive alt text ### 10. Update navigation and redirects diff --git a/.agents/skills/draft_guide/SKILL.md b/.agents/skills/draft_guide/SKILL.md index 808bbe90..c02ccc3d 100644 --- a/.agents/skills/draft_guide/SKILL.md +++ b/.agents/skills/draft_guide/SKILL.md @@ -1,6 +1,6 @@ --- name: draft_guide -description: Draft a new guide page for the Guides section (src/content/docs/university/). Use for practical, task-oriented walkthroughs that help developers accomplish a specific goal — like setting up a tool, completing a workflow, or learning a technique. Guides focus on the "how" with real prompts and reproducible results, targeting non-branded search queries. +description: Draft a new guide page for the Guides section (src/content/docs/guides/). Use for practical, task-oriented walkthroughs that help developers accomplish a specific goal — like setting up a tool, completing a workflow, or learning a technique. Guides focus on the "how" with real prompts and reproducible results, targeting non-branded search queries. --- # Draft guide page @@ -9,15 +9,17 @@ Draft a practical guide that walks a developer through accomplishing a specific ## Workflow -Follow the workflow in `.warp/skills/draft_docs/SKILL.md`, using the **guide template** at `.warp/templates/guide-page.md`. +Follow the workflow in `.agents/skills/draft_docs/SKILL.md`, using the **guide template** at `.agents/templates/guide-page.md`. -Guide pages live in `src/content/docs/university/` (the Guides Astro Starlight space), not in `docs/`. When placing the file, use these directories: -- `src/content/docs/university/integrations/` — Setup guides for external tools (Claude Code, Codex, MCP servers) -- `src/content/docs/university/developer-workflows/` — Workflow and technique guides (code review, parallel agents, voice input) -- `src/content/docs/university/end-to-end-builds/` — Full app builds from start to finish -- `src/content/docs/university/mcp-servers/` — MCP-specific guides +Guide pages live in `src/content/docs/guides/` (the Guides Astro Starlight space), not in the main product reference sections. When placing the file, use these directories: +- `src/content/docs/guides/agent-workflows/` — Using coding agents to explain code, review PRs, run parallel tasks, and attach session context +- `src/content/docs/guides/configuration/` — Rules, agent profiles, saved prompts, and related setup guides +- `src/content/docs/guides/external-tools/` — MCP servers, third-party tools, and integrations +- `src/content/docs/guides/build-an-app-in-warp/` — End-to-end app builds from start to finish +- `src/content/docs/guides/devops-and-infrastructure/` — Cloud logs, Docker, Kubernetes, testing, and database optimization +- `src/content/docs/guides/frontend-and-ui/` — Building and refining UI components with coding agents -The sidebar nav is defined in `src/content/docs/university/astro.config.mjs (sidebar config)`, which organizes guides into topic-based sections. When adding a new guide, place the file in the appropriate directory above and add the nav entry under the matching section in `astro.config.mjs (sidebar config)`: +The sidebar nav is defined in `src/content/docs/guides/astro.config.mjs (sidebar config)`, which organizes guides into topic-based sections. When adding a new guide, place the file in the appropriate directory above and add the nav entry under the matching section in `astro.config.mjs (sidebar config)`: - **Getting started** — First steps with Warp: setup, appearance, key features - **Agent workflows** — Using coding agents to explain code, review PRs, run parallel tasks - **Configuration** — Rules, agent profiles, saved prompts, monorepo sync @@ -31,7 +33,7 @@ The sidebar nav is defined in `src/content/docs/university/astro.config.mjs (sid These rules are specific to guide pages (from the "Drafting by content type" section of `AGENTS.md`): - **Titles should be task-oriented** and read like a search query. Use shortened titles in the Astro Starlight nav and full descriptive titles in the article H1. -- **For SEO: capture the non-branded query.** Write the title a developer would actually search for, not "How to do X in Warp." Example: "How to Set Up Claude Code" not "How to Set Up Claude Code in Warp." +- **For SEO: capture the non-branded query.** Write the title a developer would actually search for, not "How to do X in Warp." Example: "How to set up Claude Code" not "How to set up Claude Code in Warp." - All procedural rules apply (focused steps, motivate steps, expected outcomes). - Link to relevant feature documentation in the main docs (`docs/`) where concepts need deeper explanation. - When a guide has a companion video, the written content should stand alone. @@ -41,9 +43,11 @@ These rules are specific to guide pages (from the "Drafting by content type" sec When drafting a guide, check for relevant SEO and AEO data: -1. **Use SEO and AEO data** to inform titles, descriptions, and content coverage. The `docs-seo-audit` skill (`.warp/skills/docs-seo-audit/`) can identify technical SEO issues. -2. **Write the frontmatter `description`** to include the primary target keyword naturally. Keep under 160 characters. -3. **Frame the title for non-branded search.** The page should answer the user's actual question, with Warp features as the natural solution in the guide body. +1. **Create an AEO brief when source data drives the guide.** If the guide request mentions AEO, Peec, AI search prompts, answer-engine visibility, search-query vocabulary, or content gaps, read `.agents/skills/aeo_brief/SKILL.md` before drafting. Use the brief to map source-data language to natural docs language and to decide whether this should be a new guide or an update to an existing guide. +2. **Use SEO and AEO data** to inform titles, descriptions, and content coverage. The `docs-seo-audit` skill (`.agents/skills/docs-seo-audit/`) can identify technical SEO issues. +3. **Write the frontmatter `description`** to include the primary target keyword naturally. Keep under 160 characters. +4. **Frame the title for non-branded search.** The page should answer the user's actual question, with Warp features as the natural solution in the guide body. +5. **Avoid keyword stuffing.** Preserve high-intent query terms only where they make the guide clearer or more discoverable. Rewrite awkward source-data phrasing into natural developer language. ## Third-party tool accuracy @@ -60,7 +64,7 @@ When a guide documents a third-party tool (Claude Code, Codex, OpenCode, etc.): Before adding any internal documentation link: -- **Verify the target page exists.** Check the relevant `astro.config.mjs (sidebar config)` file (`src/content/docs/astro.config.mjs (sidebar config)`, `src/content/docs/agent-platform/astro.config.mjs (sidebar config)`, `src/content/docs/university/astro.config.mjs (sidebar config)`) to confirm the page is listed. Do NOT generate plausible-looking URLs to pages that don't exist. +- **Verify the target page exists.** Check the relevant `astro.config.mjs (sidebar config)` file (`src/content/docs/astro.config.mjs (sidebar config)`, `src/content/docs/agent-platform/astro.config.mjs (sidebar config)`, `src/content/docs/guides/astro.config.mjs (sidebar config)`) to confirm the page is listed. Do NOT generate plausible-looking URLs to pages that don't exist. - **If a target page is planned but not yet published**, link to the closest existing page and add a TODO comment with the intended future path: `` - **For third-party agent pages**, the current paths are under `src/content/docs/agent-platform/third-party-agents/` (e.g., `claude-code.mdx`, `codex.mdx`, `opencode.mdx`). @@ -71,9 +75,18 @@ Every guide should link to: - Relevant feature documentation in the main docs (`src/content/docs/` or `src/content/docs/agent-platform/`) - If applicable, pages in the Coding Agents section (`src/content/docs/agent-platform/third-party-agents/`) +## Pre-handoff self-review + +Before presenting a guide draft, do an editorial pass focused on the issues that often create avoidable review back-and-forth: +- **Scannability** - Break dense procedure sections into numbered steps, short bullets, or concise subsections. Avoid long H2 sections that mix multiple actions. +- **Usefulness** - Confirm the guide teaches a real workflow and does not become a junk drawer of loosely related AEO topics. +- **Vocabulary translation** - Check that Peec/search phrasing is translated into natural docs language while preserving accurate high-intent terms like third-party product names. +- **Product and UI names** - Check product surfaces against `.agents/references/terminology.md` and validate UI paths or command names when the guide depends on exact navigation. +- **Human-review questions** - Surface unresolved questions about product behavior, placement, or terminology instead of hiding them in the draft. + ## Existing examples Read 2-3 of these strong examples to match the existing pattern: -- `university/mcp-servers/sentry-mcp-fix-sentry-error-in-empower-website.mdx` -- `university/end-to-end-builds/building-a-real-time-chat-app-github-mcp-+-railway.mdx` -- `university/developer-workflows/beginner/how-to-explain-your-codebase-using-warp-rust-codebase.mdx` +- `src/content/docs/guides/external-tools/sentry-mcp-fix-sentry-error-in-empower-website.mdx` +- `src/content/docs/guides/build-an-app-in-warp/building-a-real-time-chat-app-github-mcp-railway.mdx` +- `src/content/docs/guides/agent-workflows/how-to-explain-your-codebase-using-warp-rust-codebase.mdx` diff --git a/.agents/skills/draft_procedural/SKILL.md b/.agents/skills/draft_procedural/SKILL.md index e91c4e4a..3945e36b 100644 --- a/.agents/skills/draft_procedural/SKILL.md +++ b/.agents/skills/draft_procedural/SKILL.md @@ -9,7 +9,7 @@ Draft a procedural documentation page with step-by-step instructions to accompli ## Workflow -Follow the workflow in `.warp/skills/draft_docs/SKILL.md`, using the **procedural template** at `.warp/templates/procedural.md`. +Follow the workflow in `.agents/skills/draft_docs/SKILL.md`, using the **procedural template** at `.agents/templates/procedural.md`. ## Content type rules @@ -23,6 +23,23 @@ These rules are specific to procedural pages (from the "Drafting by content type - Don't over-explain — link to conceptual pages for the "why." - Title convention: gerund ("Configuring X", "Managing X") +## AEO-driven procedures + +If the request is driven by AEO, Peec, AI search prompts, answer-engine visibility, or search-query vocabulary, read `.agents/skills/aeo_brief/SKILL.md` before drafting. Use the brief to: +- Translate source-data language into precise procedure titles, headings, and descriptions +- Preserve accurate high-intent phrases without keyword stuffing +- Decide whether the procedure belongs in a new page or as a tighter update to an existing page +- Surface product or UI terminology questions before presenting the draft + +## Pre-handoff self-review + +Before presenting the draft, check: +- **Scannability** - Long procedure sections should use numbered steps, short bullets, or concise subsections. Do not leave dense paragraphs that hide actions. +- **Expected outcomes** - Readers should know what success looks like after important steps. +- **UI accuracy** - Product surfaces, buttons, settings paths, and command names should match the current product terminology. +- **Value over coverage** - AEO-driven procedures should solve a real task, not collect loosely related keywords. +- **Open questions** - Flag any steps that still need human product testing or UI verification. + ## Heading case All headings (H1–H4) must use **sentence case**: capitalize only the first word and proper feature names. diff --git a/.agents/skills/review-docs-pr/SKILL.md b/.agents/skills/review-docs-pr/SKILL.md index b96593f8..0fe960ff 100644 --- a/.agents/skills/review-docs-pr/SKILL.md +++ b/.agents/skills/review-docs-pr/SKILL.md @@ -1,6 +1,6 @@ --- name: review-docs-pr -description: Reviews documentation pull requests for the Warp docs repository. Checks for broken links, style guide compliance, content quality, and Astro Starlight structure. Use when reviewing documentation PRs or when you need to provide feedback on markdown documentation changes. +description: Reviews documentation pull requests for the Warp docs repository. Checks for broken links, style guide compliance, content quality, AEO/source-data fit, and Astro Starlight structure. Use when reviewing documentation PRs or when you need to provide feedback on markdown documentation changes. --- # Review Documentation PR @@ -13,6 +13,7 @@ Use this skill when reviewing documentation changes in PRs. The skill will: - Check for potential broken links - Verify style guide compliance - Review content quality +- Review AEO/source-data fit for docs changes that target search or answer-engine visibility - Check Astro Starlight structure integrity ## Review Instructions @@ -20,11 +21,12 @@ Use this skill when reviewing documentation changes in PRs. The skill will: Review this documentation PR for the docs repository. Focus on: -1. **Broken links**: Check for potential broken internal links (relative paths, cross-space links). You can run the broken link checker at `python3 .warp/skills/check_for_broken_links/check_links.py --internal-only` if helpful. +1. **Broken links**: Check for potential broken internal links (relative paths, cross-space links). You can run the broken link checker at `python3 .agents/skills/check_for_broken_links/check_links.py --internal-only` if helpful. 2. **Style guide compliance**: Reference `AGENTS.md` for documentation standards (voice, formatting, terminology). 3. **Content quality**: Check for clarity, accuracy, proper frontmatter, and appropriate use of headers/lists. 4. **Code snippets**: Verify that any code examples, commands, or configuration snippets are correct and will work as documented. If you're unsure about technical details, use the `answer_question` skill to verify against the docs or search the source code. 5. **Astro Starlight structure**: Verify astro.config.mjs (sidebar config) updates if files were moved/renamed, and that redirects are added to vercel.json (redirects) when needed. +6. **AEO/source-data fit**: For docs changes that target AEO, SEO, Peec recommendations, AI search prompts, or content gaps, check whether the PR has a clear source-data rationale, uses query vocabulary naturally, avoids junk-drawer coverage, and updates or links existing docs instead of creating duplicative content. Provide actionable, constructive feedback. Focus on documentation quality issues, not code bugs. @@ -46,6 +48,18 @@ If you encounter: Use the `answer_question` skill to search the documentation and source code for authoritative information before making your review comment. +### AEO review guidance + +For AEO-driven docs PRs, review the diff through these questions: +- **Source rationale** - Is it clear which Peec prompt, search-query cluster, recommendation, or content gap motivated the change? If not, ask for the source signal or suggest narrowing the scope. +- **Vocabulary translation** - Does the draft preserve high-intent search terms where useful while translating awkward source-data language into natural docs language? +- **Reader value** - Would the page help a developer complete or understand a real workflow, or is it collecting loosely related keywords? +- **Terminology and UI surfaces** - Are product names, settings paths, panel names, and navigation labels consistent with `AGENTS.md`, `.agents/references/terminology.md`, and the actual UI? +- **Scannability** - Are dense procedures broken into numbered steps, bullets, or concise subsections with expected outcomes? +- **Duplication risk** - Should the content update an existing page, link to an existing page, or be merged with related content instead of living as a new standalone doc? + +When the issue is a judgment call, prefer a `💡 [SUGGESTION]` comment that explains the tradeoff rather than blocking the PR. + ## Output Format Create a `review.json` file with the following structure: diff --git a/.agents/templates/guide-page.md b/.agents/templates/guide-page.md index 6669456f..4533517f 100644 --- a/.agents/templates/guide-page.md +++ b/.agents/templates/guide-page.md @@ -10,6 +10,8 @@ description: >- [One sentence: what you'll accomplish by following this guide. Mention Warp by name. Include a time estimate if possible (e.g., "takes about 10 minutes").] +[AEO GUIDANCE: If this guide is based on Peec, answer-engine prompts, search-query data, or AEO goals, create an AEO brief first using `.agents/skills/aeo_brief/SKILL.md`. Use the brief to preserve high-intent vocabulary naturally, translate awkward source-data phrasing into developer-friendly docs language, and decide whether this should be a new guide or an update to an existing page.] + import VideoEmbed from '@components/VideoEmbed.astro'; @@ -52,10 +54,12 @@ import VideoEmbed from '@components/VideoEmbed.astro'; ## Next steps -[2-3 sentence summary of what the reader accomplished. Then list links to related content. CROSS-LINKING: Always link to at least one other guide in the Guides section and one feature documentation page in the main docs. If this guide relates to features covered in the Coding Agents section (src/content/docs/coding-agents/), link there too. If a standalone summary section feels valuable, add a ## Recap heading above the summary paragraph.] +[2-3 sentence summary of what the reader accomplished. Then list links to related content. CROSS-LINKING: Always link to at least one other guide in the Guides section and one feature documentation page in the main docs. If this guide relates to features covered in the third-party agents section (src/content/docs/agent-platform/third-party-agents/), link there too. If a standalone summary section feels valuable, add a ## Recap heading above the summary paragraph.] * [Link to related guide in the Guides section] * [Link to relevant feature documentation in the main docs] * [Link to deeper reference or advanced usage] [LINK VERIFICATION: Before publishing, verify every internal link points to an existing page by checking the relevant astro.config.mjs (sidebar config). If a target page is planned but not live, use the closest existing page and add a TODO comment.] + +[PRE-HANDOFF REVIEW: Before presenting the draft, check whether procedures are easy to scan, whether dense sections should become numbered steps or bullets, whether UI surfaces use canonical product names, whether the page adds value beyond existing docs, and whether any product behavior needs human testing.] diff --git a/.agents/templates/procedural.md b/.agents/templates/procedural.md index b3147d86..ea740663 100644 --- a/.agents/templates/procedural.md +++ b/.agents/templates/procedural.md @@ -9,6 +9,8 @@ description: >- [Opening paragraph: What the reader will accomplish and why. 1-2 sentences. Focus on the goal, not the tool.] +[AEO GUIDANCE: If this procedure is based on Peec, answer-engine prompts, search-query data, or AEO goals, create an AEO brief first using `.agents/skills/aeo_brief/SKILL.md`. Use the brief to translate source-data vocabulary into precise, natural docs language and confirm whether this belongs in a new page or an existing page.] + ## Prerequisites [Only if needed. Bulleted list with inline context for each prerequisite. @@ -16,7 +18,7 @@ Each item should include: what it is (1 short clause), where to get or create it, and a link to the full reference. Example: * **A Warp API key** - Authenticate API requests with a key from - **Settings** > **Platform** in the Warp app. See [API Keys](path) for details.] + **Settings** > **Cloud platform** > **Oz Cloud API Keys** in the Warp app. See [API Keys](path) for details.] ## [Primary task name — sentence case. e.g., "Creating API keys"] @@ -49,3 +51,5 @@ Format: symptom/error as bold text, then cause and fix.] Bold the key action at the start of each item.] * **Use environment variables** - Avoid passing secrets directly in commands. + +[PRE-HANDOFF REVIEW: Before presenting the draft, check whether steps are easy to scan, whether each important step has an expected outcome, whether UI names and Settings paths are current, whether AEO vocabulary is natural rather than stuffed, and whether any step needs human product testing.] From f65254acd27f5762e52665ed6b7d1d581510fb36 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Fri, 29 May 2026 11:54:52 -0600 Subject: [PATCH 2/3] docs: fix AEO workflow path references Co-Authored-By: Oz --- .agents/skills/draft_docs/SKILL.md | 4 ++-- .agents/skills/draft_guide/SKILL.md | 12 ++++++------ .agents/skills/review-docs-pr/SKILL.md | 2 +- .agents/templates/guide-page.md | 4 ++-- 4 files changed, 11 insertions(+), 11 deletions(-) diff --git a/.agents/skills/draft_docs/SKILL.md b/.agents/skills/draft_docs/SKILL.md index 7b904d0b..b8e95e88 100644 --- a/.agents/skills/draft_docs/SKILL.md +++ b/.agents/skills/draft_docs/SKILL.md @@ -37,7 +37,7 @@ If the request mentions AEO, SEO, Peec, answer-engine visibility, search-query v - Which questions require human review before publishing ### 2. Clarify placement -Ask the user where the doc should live. The docs are organized into sections, each with its own `astro.config.mjs (sidebar config)`: +Ask the user where the doc should live. The docs are organized into sections, with navigation configured in `src/sidebar.ts`: - `src/content/docs/` - Warp Terminal and IDE → `docs.warp.dev/` - `src/content/docs/agent-platform/` - Agent Platform → `docs.warp.dev/agent-platform/` - `src/content/docs/reference/` - Technical reference (CLI, API & SDK) → `docs.warp.dev/reference/` @@ -112,7 +112,7 @@ Before presenting the draft, verify against the quality checklist in `AGENTS.md` ### 10. Update navigation and redirects If this is a new page, remind the user to: -- Add it to the relevant section's `astro.config.mjs (sidebar config)`. +- Add it to the relevant section in `src/sidebar.ts`. If this page replaces, renames, or moves an existing page, remind the user to add a redirect: - **Same-space redirect**: Add an entry to the space's `vercel.json (redirects)` file under `redirects:`. diff --git a/.agents/skills/draft_guide/SKILL.md b/.agents/skills/draft_guide/SKILL.md index c02ccc3d..d8659f89 100644 --- a/.agents/skills/draft_guide/SKILL.md +++ b/.agents/skills/draft_guide/SKILL.md @@ -16,10 +16,10 @@ Guide pages live in `src/content/docs/guides/` (the Guides Astro Starlight space - `src/content/docs/guides/configuration/` — Rules, agent profiles, saved prompts, and related setup guides - `src/content/docs/guides/external-tools/` — MCP servers, third-party tools, and integrations - `src/content/docs/guides/build-an-app-in-warp/` — End-to-end app builds from start to finish -- `src/content/docs/guides/devops-and-infrastructure/` — Cloud logs, Docker, Kubernetes, testing, and database optimization -- `src/content/docs/guides/frontend-and-ui/` — Building and refining UI components with coding agents +- `src/content/docs/guides/devops/` — Cloud logs, Docker, Kubernetes, testing, and database optimization +- `src/content/docs/guides/frontend/` — Building and refining UI components with coding agents -The sidebar nav is defined in `src/content/docs/guides/astro.config.mjs (sidebar config)`, which organizes guides into topic-based sections. When adding a new guide, place the file in the appropriate directory above and add the nav entry under the matching section in `astro.config.mjs (sidebar config)`: +The sidebar nav is defined in `src/sidebar.ts`, which organizes guides into topic-based sections. When adding a new guide, place the file in the appropriate directory above and add the nav entry under the matching section in `src/sidebar.ts`: - **Getting started** — First steps with Warp: setup, appearance, key features - **Agent workflows** — Using coding agents to explain code, review PRs, run parallel tasks - **Configuration** — Rules, agent profiles, saved prompts, monorepo sync @@ -64,16 +64,16 @@ When a guide documents a third-party tool (Claude Code, Codex, OpenCode, etc.): Before adding any internal documentation link: -- **Verify the target page exists.** Check the relevant `astro.config.mjs (sidebar config)` file (`src/content/docs/astro.config.mjs (sidebar config)`, `src/content/docs/agent-platform/astro.config.mjs (sidebar config)`, `src/content/docs/guides/astro.config.mjs (sidebar config)`) to confirm the page is listed. Do NOT generate plausible-looking URLs to pages that don't exist. +- **Verify the target page exists.** Check `src/sidebar.ts` for sidebar entries and the corresponding file under `src/content/docs/` to confirm the page exists. Do NOT generate plausible-looking URLs to pages that don't exist. - **If a target page is planned but not yet published**, link to the closest existing page and add a TODO comment with the intended future path: `` -- **For third-party agent pages**, the current paths are under `src/content/docs/agent-platform/third-party-agents/` (e.g., `claude-code.mdx`, `codex.mdx`, `opencode.mdx`). +- **For third-party CLI agent pages**, the current paths are under `src/content/docs/agent-platform/cli-agents/` (e.g., `claude-code.mdx`, `codex.mdx`, `opencode.mdx`). ## Cross-linking Every guide should link to: - At least one other guide in the Guides section - Relevant feature documentation in the main docs (`src/content/docs/` or `src/content/docs/agent-platform/`) -- If applicable, pages in the Coding Agents section (`src/content/docs/agent-platform/third-party-agents/`) +- If applicable, pages in the Third-Party CLI Agents section (`src/content/docs/agent-platform/cli-agents/`) ## Pre-handoff self-review diff --git a/.agents/skills/review-docs-pr/SKILL.md b/.agents/skills/review-docs-pr/SKILL.md index 0fe960ff..06668730 100644 --- a/.agents/skills/review-docs-pr/SKILL.md +++ b/.agents/skills/review-docs-pr/SKILL.md @@ -25,7 +25,7 @@ Focus on: 2. **Style guide compliance**: Reference `AGENTS.md` for documentation standards (voice, formatting, terminology). 3. **Content quality**: Check for clarity, accuracy, proper frontmatter, and appropriate use of headers/lists. 4. **Code snippets**: Verify that any code examples, commands, or configuration snippets are correct and will work as documented. If you're unsure about technical details, use the `answer_question` skill to verify against the docs or search the source code. -5. **Astro Starlight structure**: Verify astro.config.mjs (sidebar config) updates if files were moved/renamed, and that redirects are added to vercel.json (redirects) when needed. +5. **Astro Starlight structure**: Verify `src/sidebar.ts` updates if files were added, moved, or renamed, and that redirects are added to vercel.json (redirects) when needed. 6. **AEO/source-data fit**: For docs changes that target AEO, SEO, Peec recommendations, AI search prompts, or content gaps, check whether the PR has a clear source-data rationale, uses query vocabulary naturally, avoids junk-drawer coverage, and updates or links existing docs instead of creating duplicative content. Provide actionable, constructive feedback. Focus on documentation quality issues, not code bugs. diff --git a/.agents/templates/guide-page.md b/.agents/templates/guide-page.md index 4533517f..2a7aea40 100644 --- a/.agents/templates/guide-page.md +++ b/.agents/templates/guide-page.md @@ -54,12 +54,12 @@ import VideoEmbed from '@components/VideoEmbed.astro'; ## Next steps -[2-3 sentence summary of what the reader accomplished. Then list links to related content. CROSS-LINKING: Always link to at least one other guide in the Guides section and one feature documentation page in the main docs. If this guide relates to features covered in the third-party agents section (src/content/docs/agent-platform/third-party-agents/), link there too. If a standalone summary section feels valuable, add a ## Recap heading above the summary paragraph.] +[2-3 sentence summary of what the reader accomplished. Then list links to related content. CROSS-LINKING: Always link to at least one other guide in the Guides section and one feature documentation page in the main docs. If this guide relates to features covered in the Third-Party CLI Agents section (src/content/docs/agent-platform/cli-agents/), link there too. If a standalone summary section feels valuable, add a ## Recap heading above the summary paragraph.] * [Link to related guide in the Guides section] * [Link to relevant feature documentation in the main docs] * [Link to deeper reference or advanced usage] -[LINK VERIFICATION: Before publishing, verify every internal link points to an existing page by checking the relevant astro.config.mjs (sidebar config). If a target page is planned but not live, use the closest existing page and add a TODO comment.] +[LINK VERIFICATION: Before publishing, verify every internal link points to an existing file under `src/content/docs/` and, when the page should appear in navigation, a matching entry in `src/sidebar.ts`. If a target page is planned but not live, use the closest existing page and add a TODO comment.] [PRE-HANDOFF REVIEW: Before presenting the draft, check whether procedures are easy to scan, whether dense sections should become numbered steps or bullets, whether UI surfaces use canonical product names, whether the page adds value beyond existing docs, and whether any product behavior needs human testing.] From a49aa8c6010499cb50129f7bc16125ce405d3f76 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Mon, 1 Jun 2026 08:24:59 -0600 Subject: [PATCH 3/3] docs: clarify AEO brief relationship to Peec gap skill Co-Authored-By: Oz --- .agents/skills/aeo_brief/SKILL.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/.agents/skills/aeo_brief/SKILL.md b/.agents/skills/aeo_brief/SKILL.md index 7eebf170..e11fd12d 100644 --- a/.agents/skills/aeo_brief/SKILL.md +++ b/.agents/skills/aeo_brief/SKILL.md @@ -17,6 +17,14 @@ Use this skill when the user asks for docs work based on: If the task is not AEO-driven, use the normal docs drafting workflow instead. +## Relationship to peec-content-gap + +Do not copy Buzz's `peec-content-gap` workflow into docs. Treat that skill as the broader upstream workflow for diagnosing Peec/AEO content gaps across docs, marketing pages, third-party or UGC opportunities, technical SEO, and competitor visibility. + +Use this docs-specific `aeo_brief` skill when the likely next step is drafting or revising documentation, or when a broader Peec content-gap analysis already recommends docs work. Reference any `peec-content-gap` findings as source signals in the brief, then translate them into docs scope, existing pages to update or link, terminology, and open questions for review. + +If the broader analysis suggests the best fix is not docs, do not force it into docs. Recommend the appropriate non-docs follow-up or note that docs are not the right channel yet. + ## Inputs to gather Start with the smallest set of inputs that can support a useful brief: