docs: add AEO drafting workflow guidance#159
Open
rachaelrenk wants to merge 2 commits into
Open
Conversation
Co-Authored-By: Oz <oz-agent@warp.dev>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
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 |
![oz-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 adds an AEO brief skill and updates docs drafting/review workflows to account for Peec/source-data-driven documentation requests. The workflow direction is useful, but several newly added path references do not match the current docs repository structure, so following this guidance would send agents to nonexistent directories or nav files and create broken links.
Concerns
- The updated guide drafting instructions name
src/content/docs/guides/devops-and-infrastructure/andsrc/content/docs/guides/frontend-and-ui/, but the actual guide directories aresrc/content/docs/guides/devops/andsrc/content/docs/guides/frontend/. - The updated guide workflow and link-verification guidance point to per-section
astro.config.mjssidebar files that do not exist; guide sidebar entries are managed insrc/sidebar.ts. - The guide template points writers at
src/content/docs/agent-platform/third-party-agents/, but current third-party CLI agent pages live undersrc/content/docs/agent-platform/cli-agents/. - Security review: no security-specific findings; this is documentation/workflow guidance only and does not add executable code, dependencies, auth logic, or secret handling.
- Spec context: no approved or repository spec context was provided, so there is no spec-alignment concern to raise.
Verdict
Found: 0 critical, 4 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
Comment on lines
+19
to
+20
| - `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 |
Contributor
There was a problem hiding this comment.
guides/devops/ and guides/frontend/, so agents following this will create pages outside the real structure.
Suggested change
| - `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 |
| - `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)`: |
Contributor
There was a problem hiding this comment.
src/content/docs/guides/astro.config.mjs does not exist; the Guides sidebar is configured in src/sidebar.ts, so this guidance sends agents to a missing file when adding nav entries.
Suggested change
| 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`: |
| 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. |
Contributor
There was a problem hiding this comment.
astro.config.mjs files are not present in this repo; link verification should check src/sidebar.ts plus the target MDX file instead.
Suggested change
| - **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. |
| ## 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.] |
Contributor
There was a problem hiding this comment.
third-party-agents directory does not exist; current Claude Code/Codex/OpenCode pages live under agent-platform/cli-agents, so drafts that follow this path will generate broken links.
Suggested change
| [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.] |
Co-Authored-By: Oz <oz-agent@warp.dev>
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
1 participant
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
aeo_briefskill for source-grounded AEO docs planning with Peec workflows, vocabulary mapping, scope guidance, and open questions..warp/...references in touched workflow files and point guide guidance at the currentsrc/content/docs/guides/structure.Validation
git diff --check.warp/skills,.warp/templates, or.warp/referencespaths.Artifacts
Co-Authored-By: Oz oz-agent@warp.dev