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

[oz-by-warp]

Patterns addressed

Signal window: last 30 days (through 2026-08-04). Primary source: GitHub human review comments, review verdicts, and post-agent human edits on agent-coauthored merged PRs (96 agent PRs identified; 866 prior log rows in-window plus 232 newly collected records). Oz [SIGNAL:style-lint] / [SIGNAL:pr-review] markers: 0 found in recent oz run list conversations (inner loop still not emitting markers reliably).

1. heading_specificity (human feedback across 16+ PRs in the durable log; 24 multi-PR human-edit clusters in this collector pass)

   • Agents still ship vague section labels (Overview, More details, Other) even when sentence case is correct.
   • Sharpened the existing “descriptive headings” rule with concrete ❌ labels and checklist coverage.

2. frontmatter (human feedback across 22 PRs in-window)

   • Descriptions that only restate the title or say “This page describes…” keep landing in review.
   • Added an explicit frontmatter description rule in draft_docs step 6.5 and mirrored it into conceptual/reference template brackets.

3. list_format (human feedback across 25 PRs in-window; reviewers explicitly asked for * markers to match templates)

   • Clarified bold-term separator (hyphen-minus, not em dash/colon) and required * as the top-level unordered marker.

4. link_quality (human feedback across 24 PRs in-window)

   • New pages still dead-end without Related pages / descriptive anchors.
   • Added a combined descriptive-link + required Related pages (or Next steps) rule, plus checklist items.

Improvement targets

• .agents/skills/draft_docs/SKILL.md — step 6.5 critical formatting rules + step 9 checklist (shared by all drafting skills)
• .agents/templates/conceptual.md — description, heading, list-marker, and Related pages bracket instructions
• .agents/templates/reference.md — description, heading specificity, * list markers, and Related pages section

Intentionally not editing feature-doc.md, procedural.md, guide-page.md, or create_pr/SKILL.md in this PR — open PRs #450 and #454 already target those for callouts, Settings orientation, troubleshooting placement, UI verification, and Unverified claims.

Patterns reviewed but not acted on

• callout / settings_path / ui_label_accuracy / content_structure / troubleshooting placement — meet threshold but are already proposed in open PRs docs(skills): improve drafting skills from signal log patterns 2026-08-01 #450 and docs(skills): improve drafting skills from signal log patterns 2026-08-03 #454; acting here would duplicate or conflict.
• terminology / video_embed / image_alt / scannability — signal present, but either already covered in AGENTS.md / step 6.5 at useful specificity, or lacks a single tight skill edit that would change agent behavior beyond existing rules.
• style-lint / pr-review Oz markers — below threshold (0 markers); collector logged the gap on the standing signal-log PR.

Open questions for human review

1. Should “bare ## Overview” be treated as always-wrong, or allowed when it is the only H2 under a highly specific page title?
2. Reference pages: is a trailing ## Related pages desirable on pure CLI flag dumps, or only when a conceptual companion exists (current wording is “when a companion exists”)?
3. Open PRs docs(skills): improve drafting skills from signal log patterns 2026-08-01 #450 and docs(skills): improve drafting skills from signal log patterns 2026-08-03 #454 should probably merge (or close) before or with this one to avoid three parallel skill diffs on draft_docs/SKILL.md.

Test plan

• Confirm diff is limited to .agents/skills/ and .agents/templates/
• Confirm edits are additive (no removals of existing rules)
• Spot-check that rules do not contradict AGENTS.md
• Coordinate with docs(skills): improve drafting skills from signal log patterns 2026-08-01 #450 / docs(skills): improve drafting skills from signal log patterns 2026-08-03 #454 reviewers on merge order for draft_docs/SKILL.md

Standing signal-log PR: #467

---

Conversation: https://app.warp.dev/conversation/a9840e05-2c60-408a-8a1b-4698ca367442
Run: https://oz.warp.dev/runs/019fcdb7-dc3a-7ca7-989f-cd2b3b359dd1
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 4, 2026 5:17pm