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

.agents/skills/create_pr/SKILL.md

@@ -133,6 +133,25 @@ This PR updates the Terminal and Agent modes documentation for the Oz launch.
 - Updated navigation entry title
 ```
 
+### Unverified claims (required on drafting PRs)
+
+Any PR that adds or updates page content must state which UI labels, Settings paths, CLI flags, permission defaults, plan eligibility, and platform-support claims could not be verified against `warp-internal`, `warp-server`, or a live build. See step 9.5 of the `draft_docs` skill.
+
+Include the section even when nothing is outstanding:
+
+```markdown
+## Unverified claims
+None — all UI labels, flags, defaults, and eligibility claims were verified against source.
+```
+
+When claims are outstanding, give the reviewer one bullet per claim with what would confirm it:
+
+```markdown
+## Unverified claims
+- `--auto-approve` flag name — `cloud-agents.mdx`, "Run an agent" — taken from the PRD; confirm against `TuiArgs` in `warp-internal`.
+- **Settings** > **Agents** > **Permissions** path — `permissions.mdx`, "Defaults" — source repos were not available in this environment.
+```
+
 ### Additional context (optional)
 - Link to related issues or discussions
 - Screenshots for visual changes

.agents/skills/draft_docs/SKILL.md

@@ -81,6 +81,15 @@ To find these repos, search for directories named `warp-internal` and `warp-serv
 
 Use source code to verify technical behavior, understand feature implementation, and find accurate terminology.
 
+When the draft names UI labels, Settings paths, CLI flags, default permissions, plan eligibility, or platform support, treat source (or a live build) as required verification—not optional color. A PRD or spec is not verification: labels and flag names routinely change between spec and ship.
+
+If you cannot verify a claim (for example, the source repos are not available in this environment), do not guess and do not silently drop it. Choose one of these, and record the claim either way:
+
+1. **Omit the claim** - Write around it when the page still works without it. Describe the action without naming the exact flag, or link to the reference page that will carry the detail.
+2. **Include it with an inline marker** - Keep the spec's wording and flag it in an MDX comment next to the claim: `{/* VERIFY: flag name from PRD, unconfirmed against warp-internal */}`.
+
+Keep a running list of every unverified claim as you draft. Reporting that list is required — see step 9.5.
+
 ### 6.5. Critical formatting rules
 
 These rules are frequently violated by agents. Apply them carefully during drafting:
@@ -93,6 +102,11 @@ These rules are frequently violated by agents. Apply them carefully during draft
 - **Tables or parallel bullets for comparison and reference data** — When you present two or more parallel items (key types, plan tiers, environments) or structured reference data (API endpoints, parameters), use a Markdown table or tightly parallel bullets instead of one dense paragraph. ✅ a table with one row per API endpoint, or parallel `**Personal API keys**` / `**Agent API keys**` bullet groups ❌ a single paragraph mixing both key types and their billing rules
 - **Bold for UI elements** — Use `**Save**` not `` `Save` `` after action verbs like "click"
 - **Bold per-segment for Settings paths** — Use `**Settings** > **AI** > **Knowledge**` not `` `Settings > AI > Knowledge` ``
+- **Verify labels, flags, and defaults against source** — Before documenting a button name, Settings path, CLI flag, permission default, or eligibility rule, confirm it in `warp-internal` / `warp-server` (or the live UI). ✅ `warp --auto-approve` after checking `TuiArgs` ❌ inventing `--fast-forward` from memory or an old PR description
+- **Document durable behavior, not ephemeral chrome** — Prefer workflows, shortcuts, and outcomes that stay true when styling shifts. Drop glyph colors, pixel-level layout narration, and other pure presentation detail unless the reader must recognize them to succeed. ✅ "Press `Ctrl+C` once to stop the in-progress response." ❌ a full inventory of pending/running/failed glyph colors
+- **State availability honestly** — If a capability is preview-only, platform-limited, interactive-only, or not yet in cloud agents, say so next to the claim. Never describe limited-preview behavior as generally available. ✅ "Linux post-processing adds smart cut; macOS applies a uniform speedup." ❌ listing smart cut as a property of every recording
+- **Cover team-wide and admin effects** — For integrations and team features, state who can install, whether every teammate gets access immediately, and any per-user auth or admin steps on the external system. ✅ "A Jira admin must install the app; each teammate links their own account for run attribution." ❌ setup steps that only describe the installer's happy path
+- **Related pages are required on new pages** — End new feature, integration, and guide pages with a Related pages (or Next steps) section. Link siblings and the natural next workflow so the page does not dead-end. ✅ Integrations overview + Agent Management Panel + a sibling Slack/Linear page ❌ no cross-links after Troubleshooting
 
 ### 7. Draft the doc
 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.
@@ -120,14 +134,27 @@ Before presenting the draft, verify against the quality checklist in `AGENTS.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
+- [ ] Cross-references to related features are included (new pages include a Related pages or Next steps section)
 - [ ] 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`
+- [ ] UI labels, CLI flags, permission defaults, and eligibility claims were verified against source or the live product — anything unverified is marked inline and reported per step 9.5
+- [ ] The draft emphasizes durable behavior over ephemeral UI chrome (glyphs, pure styling, layout minutiae)
+- [ ] Preview-only, platform-limited, or interactive-only capabilities are labeled as such
+- [ ] Integrations and team features state admin requirements and who gets access after install
 - [ ] Product names with a corresponding entry in `src/data/vars.ts` use the variable syntax (`{VARS.KEY}` in prose, `{{TOKEN}}` in frontmatter) — not hardcoded strings
 - [ ] 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
 
+### 9.5. Report unverified claims
+
+Inline markers alone are skippable: a reviewer who skims the rendered page or the diff will miss them. Surface the full list where the human cannot miss it.
+
+- **Agent-authored PRs** - Add an `## Unverified claims` section to the PR description. Include one bullet per claim with the claim itself, the file and section where it appears, and what would confirm it (for example, "check `TuiArgs` in `warp-internal`"). Include the section even when the list is empty, with the single line `None — all UI labels, flags, defaults, and eligibility claims were verified against source.` Never drop the section.
+- **Local or interactive sessions** - List the same claims in your response to the user, before they review the draft.
+
+A reviewer must be able to see every unconfirmed claim without opening the diff.
+
 ### 10. Update navigation and redirects
 If this is a new page, remind the user to:
 - Add it to the relevant section in `src/sidebar.ts`.

.agents/templates/feature-doc.md

@@ -34,20 +34,25 @@ Focus on what each capability means for the user.]
 Explain "what" and "why" before "how."
 Define new terms when they first appear.
 IMPORTANT: Do NOT include step-by-step procedures in this section.
-Keep the conceptual and procedural sections clearly separated.]
+Keep the conceptual and procedural sections clearly separated.
+State platform, plan, preview, or interactive-only limits next to the behavior they constrain.
+Do not invent internal tool names or implementation details the reader cannot act on.]
 
 ## [Usage/configuration section — sentence case. Rename to match the feature, e.g., "Creating environments", "Configuring integrations"]
 
 [PROCEDURAL section: step-by-step instructions.
 Apply all procedural rules from AGENTS.md:
 - Motivate steps before giving instructions
 - Include expected outcomes after key steps
-- Group related actions when they share the same UI context]
+- Group related actions when they share the same UI context
+- Verify every UI label, Settings path, and CLI flag against source or the live product before publishing. If you cannot verify one, omit it or mark it with an inline `{/* VERIFY: ... */}` comment and report it per step 9.5 of the draft_docs skill
+- Prefer durable actions and outcomes over ephemeral chrome (glyph colors, pure layout narration)]
 
 ### Prerequisites
 
 [Bulleted list with inline context for each prerequisite.
-Include: what the thing is, where to get it, link to full reference.]
+Include: what the thing is, where to get it, link to full reference.
+For integrations and team features, include admin requirements, who gains access after install, and any per-user auth steps.]
 
 ### [Task name — sentence case. e.g., "Create an environment with the CLI"]
 
@@ -62,8 +67,9 @@ Keep sections clearly delineated by type.]
 
 ## Related pages
 
-[Cross-references to related features, next steps, deeper references.
-Use descriptive link text.]
+[Required on new feature and integration pages so the page does not dead-end.
+Cross-reference related features, sibling integrations, next steps, and deeper references.
+Use descriptive link text. Include at least one sibling or overview link and one next-step workflow link.]
 
 * [Related feature](path/to/page.md)
 * [Deeper guide](path/to/page.md)

.agents/templates/guide-page.md

@@ -13,16 +13,18 @@ import VideoEmbed from '@components/VideoEmbed.astro';
 {/* VARS: Also add the line below if this guide references product names from src/data/vars.ts. Then use {VARS.KEY} in prose. Use {{TOKEN}} in frontmatter YAML values above. See AGENTS.md → Content variables. */}
 {/* import { VARS } from '@data/vars'; */}
 
-<VideoEmbed url="[YouTube or Loom URL — remove this block if no video]" />
+<VideoEmbed url="[YouTube or Loom URL — remove this block if no video]" title="[Specific title describing the workflow or feature demo — required]" />
 
 ## Prerequisites
 
-[List what the reader needs before starting. Include inline context: what each prerequisite is, where to get it, and a link to more info. Orient the reader by naming the application before any menu paths.]
+[List what the reader needs before starting. Include inline context: what each prerequisite is, where to get it, and a link to more info. Orient the reader by naming the application before any menu paths.
+If the workflow touches a team tool (Jira, Slack, GitHub, and so on), say who can install it, whether teammates get access immediately, and any per-user auth steps.]
 
 * **[Prerequisite 1]** — [What it is and where to get it]. See [link to docs] for details.
 * **[Prerequisite 2]** — [Brief context].
 
-[Use numbered H2 headings for each step (e.g., "## 1. Install Claude Code"). Do not add a "## Steps" wrapper heading — jump straight into the numbered steps after Prerequisites. Motivate each step: explain WHY before HOW, especially for setup steps. End each numbered sub-step with a period. Use ALL_CAPS for placeholder values in commands (e.g., YOUR_API_KEY). Do not use em dashes in procedural or instructional text. If there's an open-source repo for an example, link it. When referencing a Settings path or menu for the first time, orient the reader: "in the Warp app, go to **Settings** > ...".]
+[Use numbered H2 headings for each step (e.g., "## 1. Install Claude Code"). Do not add a "## Steps" wrapper heading — jump straight into the numbered steps after Prerequisites. Motivate each step: explain WHY before HOW, especially for setup steps. End each numbered sub-step with a period. Use ALL_CAPS for placeholder values in commands (e.g., YOUR_API_KEY). Do not use em dashes in procedural or instructional text. If there's an open-source repo for an example, link it. When referencing a Settings path or menu for the first time, orient the reader: "in the Warp app, go to **Settings** > ...".
+Keep prompts and UI detail durable: teach the workflow and decisions, not glyph colors or layout minutiae that drift. Verify flag names and menu labels against source before publishing.]
 
 ## [Action-oriented step title]