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

[oz-by-warp]

Patterns addressed

1. content_structure (human feedback: review comments/verdicts across 5 PRs, plus prior log entries on error-message placement)
   • Reviewers repeatedly asked for reader-chronology section order (requirements → setup → usage) and for error strings to live in a dedicated Troubleshooting section instead of the main flow.
2. callout (human feedback: review comments + human edits across 6 PRs)
   • Agents over-used :::note / tip callouts; humans trimmed stacked callouts in favor of body prose.
3. settings_path orientation (human feedback: human edits across 7 PRs)
   • Path bolding already existed in skills; remaining gap was naming the app/tool before the first Settings path, CLI command, or URL on the page.
4. image_alt / screenshot discipline (human feedback across 4 PRs)
   • Reviewers pushed back on unnecessary screenshots and internal-only UI captures; alt-text checklist existed but placement/when-to-use guidance was thin.

Signal window: last 30 days. Primary source: GitHub human review comments, review verdicts, and post-agent human edits on 59 agent-coauthored merged PRs. Oz [SIGNAL:style-lint] / [SIGNAL:pr-review] markers: 0 found in 36 drafting-related run conversations (inner loop is not yet emitting markers reliably).

Improvement targets

• .agents/skills/draft_docs/SKILL.md — additive Critical formatting rules + checklist items for section order, Troubleshooting placement, callout sparsity, Settings/CLI/URL orientation, and screenshot discipline (applies to all drafting skills that route through draft_docs).
• .agents/templates/feature-doc.md — bracket instructions for chronology, no errors in conceptual sections, optional Troubleshooting before Related pages, sparser callouts, stronger Related pages guidance.
• .agents/templates/procedural.md — prerequisites-before-steps, app orientation, and Troubleshooting as the home for exact error strings.

Patterns reviewed but not acted on

• terminology (14 PRs) — already covered by glossary + product name variables rules in step 6.5; remaining issues were page-specific accuracy, not missing skill text.
• list_format (11 PRs) — already has explicit bold+dash rule and checklist item.
• scannability (10 PRs) — already covered by tables/parallel-bullets rule and checklist scannability item from prior loop.
• heading_specificity (4 PRs) — already has descriptive-headings rule with ✅/❌ examples.
• link_quality (2 PRs) — Related pages already in templates; count at threshold but mostly one-off “add related links” nits.
• general (20 PRs) — heterogeneous product-accuracy feedback; no single skill edit would prevent it.

Open questions for human review

1. Is “at most one or two callouts per page” the right default, or should feature docs allow a third for enterprise/security caveats?
2. Should draft_feature_doc get a type-specific Troubleshooting requirement (always include the section) rather than optional-but-recommended in the shared template?
3. Inner-loop SIGNAL emission appears broken or unused (0 markers in 30 days). Worth a follow-up so style_lint/pr-review counts can feed this loop automatically?

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

Standing signal-log PR (separate): #433

Conversation: https://app.warp.dev/conversation/6def4ca6-a9a1-4158-8027-40a525ed499d
Run: https://oz.warp.dev/runs/019fbe44-b2bf-7599-972c-0e0aef3b8974
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 1, 2026 5:17pm

[rachaelrenk]

Superseded by #487, which consolidates this PR together with the other stacked improve-drafting-skills PRs (#450, #454, #468, #484).

All four edited .agents/skills/draft_docs/SKILL.md and conflicted with each other, so none could merge cleanly. The patterns from this PR are carried over in #487 — overlapping rules were merged rather than stacked, and anything already superseded on main was dropped.

Root cause: the agent's schedule used 0 17 1-7 * 1, which is not "first Monday." Cron ORs day-of-month with day-of-week, so it fired roughly 11 times a month. #487 fixes the cron, adds a first-week guard, and gives the agent a single standing PR so this cannot recur.