docs(skills): improve drafting skills from signal log patterns 2026-08-03

[oz-by-warp]

Patterns addressed

1. ui_label_accuracy / source verification (human feedback across 14+ clean PRs, including 399, 401, 402, 404, 405)
   • Reviewers repeatedly corrected invented or stale CLI flags, permission defaults, and UI chrome that did not match warp-internal / shipped product behavior.
2. Durable vs ephemeral UI detail (human feedback across multiple PRs, especially 399 and 404)
   • Humans trimmed glyph-color inventories, layout narration, and other presentation detail that drifts; agents should document durable workflows and shortcuts instead.
3. Availability / platform honesty (human feedback on content_structure and feature_status_accuracy, e.g. 373, 374)
   • Preview-only, platform-limited, or interactive-only behavior was sometimes written as generally available.
4. Team-wide / admin effects for integrations (human feedback on missing_context, e.g. 281, 338)
   • Integration drafts often omitted who can install, whether teammates get access immediately, and per-user auth steps.
5. Related pages dead-ends (human feedback on link_quality, e.g. 281, 295, 407)
   • New feature/integration pages shipped without sibling or next-step cross-links.

Signal window: last 30 days (2026-07-04 → 2026-08-03).
Primary source: GitHub human review comments and verdicts on agent-coauthored merged PRs (noise from Oz /oz-review template verdicts filtered out).
Oz [SIGNAL:style-lint] / [SIGNAL:pr-review] markers: 0 found in drafting-related run conversations (inner loop still not emitting markers reliably).
Standing signal-log PR: #433

Improvement targets

• .agents/skills/draft_docs/SKILL.md — require source/live verification for labels/flags/defaults; add durable-UI, availability, team-access, and Related pages rules plus checklist items (applies to all drafting skills that route through draft_docs).
• .agents/templates/feature-doc.md — bracket instructions for platform/preview limits, source-verified procedures, integration admin/access prerequisites, and required Related pages.
• .agents/templates/guide-page.md — required VideoEmbed title, team-tool access prerequisites, and durable prompt/UI guidance.

Patterns reviewed but not acted on

• callout / settings_path / content_structure (chronology, Troubleshooting placement) — already proposed in open PR docs(skills): improve drafting skills from signal log patterns 2026-08-01 #450; not duplicated here.
• list_format / heading_specificity / terminology / scannability — already covered by existing step 6.5 rules and glossary guidance; remaining hits were page-specific accuracy.
• frontmatter {{TOKEN}} substitution bugs — appears to be a build/transform issue called out in human replies (tokens not substituted), not a missing drafting-skill example; needs eng follow-up rather than another skill bullet.
• general — heterogeneous product-accuracy feedback; no single skill edit would prevent it.
• missing_media — mixed human preference (add screenshot vs land without media); PR 450 already tightens screenshot discipline.

Open questions for human review

1. Should source verification be a hard blocker (omit unverified claims) even when only a PRD is available and warp-internal is not checked out?
2. Is “Related pages required on every new feature/integration page” too strict for thin stub pages that will grow later?
3. Inner-loop SIGNAL emission is still 0/30 days — worth a dedicated fix so style_lint/pr-review counts feed this loop automatically?
4. Open PR docs(skills): improve drafting skills from signal log patterns 2026-08-01 #450 overlaps thematically (callouts/orientation/structure); consider merging docs(skills): improve drafting skills from signal log patterns 2026-08-01 #450 first, then this PR, or combining after review.

Test plan

• git diff --check clean
• YAML frontmatter parse check on changed skill/template files
• Human review of whether the new rules match intended style guide emphasis

Conversation: https://app.warp.dev/conversation/23ca1da7-5292-48dc-bb3d-bb8a337eb730
Run: https://app.warp.dev/conversation/23ca1da7-5292-48dc-bb3d-bb8a337eb730
This PR was generated with Oz.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview	Aug 3, 2026 10:26pm

[oz-for-oss]

@hongyi-chen

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 /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

[oz-for-oss]

Overview

This PR updates the docs drafting skill and feature/guide templates to require source or live-product verification for user-facing labels and flags, prefer durable behavior over ephemeral UI details, state availability limits, cover team/admin effects for integrations, and strengthen related-page expectations.

Concerns

• No blocking concerns found in the attached diff. The supplemental security pass found no changed code or configuration introducing security-relevant risk, and spec_context.md reports that no approved or repository spec context exists for spec-drift review.

Verdict

Found: 0 critical, 0 important, 0 suggestions

Approve

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

[rachaelrenk]

This rule may be too strict for thin and newer stub pages that will be expanded on later. Update rule to include some flexibility around this. If there a logical and valuable next step exists, we should include that on the docs page.