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

[oz-by-warp]

Patterns addressed

1. vague_wording / conditional ambiguity

   • Signal: Human review — [skill-feedback] on PR docs: Warp Agent CLI launch documentation #411 (cloud handoff model wording); repeated vague/unclear wording themes across 9 agent-related PRs in the last 30 days (333, 358, 374, 401, 407, 411, 412, 436, 473).
   • Occurrence: 1 tagged skill-feedback + multi-PR human review theme (threshold met via tagged feedback and 2+ PRs).
   • Gap: AGENTS.md covers ambiguous modals and vague pronouns, but draft_docs step 6.5 and templates lacked a concrete multi-clause/"when it can" example agents keep shipping.

2. action_first_instructions

   • Signal: Human review — [skill-feedback] on PR docs: Warp Agent CLI launch documentation #411 (reorder instructional sentence to lead with action/goal before control).
   • Occurrence: 1 tagged skill-feedback (threshold: 1 for tagged human feedback).
   • Gap: Templates say "motivate steps" but do not require the instructional sentence itself to lead with the action/goal (e.g. "To open…, press Ctrl+E" vs "To change either value…").

Improvement targets

• .agents/skills/draft_docs/SKILL.md — two new Critical formatting rules + matching quality-checklist items with ✅/❌ examples.
• .agents/templates/procedural.md — STEP WORDING bracket instruction on action-first lines and disambiguated conditionals.
• .agents/templates/feature-doc.md — same procedural wording bullets in the feature-doc procedural section (covers the common combined page type).

Patterns reviewed but not acted on

• callout, settings_path, content_structure, image_alt — already targeted by open PR docs(skills): improve drafting skills from signal log patterns 2026-08-01 #450.
• ui_label_accuracy, platform/availability honesty, related pages — already targeted by open PR docs(skills): improve drafting skills from signal log patterns 2026-08-03 #454.
• heading_specificity, frontmatter, list_format, link_quality — already targeted by open PR docs(skills): improve drafting skills from signal log patterns 2026-08-04 #468.
• missing_media, VideoEmbed title — already merged in PR docs(skills): improve drafting skills from signal log patterns 2026-08-05 #478.
• terminology — multi-PR human edits exist, but glossary/vars guidance is already strong in step 6.5 and checklist; remaining misses look like product-rename judgment calls rather than missing skill text.
• general / scannability / missing_context — high volume but mostly untagged one-off editorial preference; no clear single skill fix beyond existing scannability checklist.
• style-lint / pr-review Oz SIGNAL markers — 0 parseable markers in sampled drafting-related runs this window (inner-loop emission still sparse).

Open questions for human review

• Should style_lint grow a heuristic for stacked conditional clauses, or keep this as skill/template-only guidance?
• Is the handoff-model example too product-specific for step 6.5, or is a real review quote better than a generic grammar example?
• Prefer closing or superseding stale open improve PRs (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/docs(skills): improve drafting skills from signal log patterns 2026-08-04 #468) once their unique rules land, to reduce duplicate monthly noise?

Test plan

• git diff --check clean
• YAML frontmatter parseable on all three changed files
• Diff limited to .agents/skills/ and .agents/templates/
• Additive-only guidance (no rule removals)

Related

• Standing signal-log PR: chore: drafting signal logs #467
• Prior improve PRs: 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, docs(skills): improve drafting skills from signal log patterns 2026-08-04 #468, docs(skills): improve drafting skills from signal log patterns 2026-08-05 #478

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview	Aug 6, 2026 5:14pm

[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.