docs(skills): improve drafting skills from signal log patterns 2026-08-04 - #468
Closed
oz-by-warp[bot] wants to merge 1 commit into
Closed
docs(skills): improve drafting skills from signal log patterns 2026-08-04#468oz-by-warp[bot] wants to merge 1 commit into
oz-by-warp[bot] wants to merge 1 commit into
Conversation
…ules Co-Authored-By: Oz <oz-agent@warp.dev>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
This was referenced Aug 5, 2026
Contributor
|
Superseded by #487, which consolidates this PR together with the other stacked All four edited Root cause: the agent's schedule used |
rachaelrenk
added a commit
that referenced
this pull request
Aug 7, 2026
…ements (#487) * docs(skills): reduce automation noise and consolidate drafting improvements Recurring docs agents were producing more PRs and Slack messages than the team could absorb. Three systemic causes, plus a batch of GitBook-era migration artifacts that left several skills unable to run as written. Shared conventions (skill-authoring-guidelines.md): - Add "One standing PR per automation": stable branch and title, look before creating, add to the existing PR rather than opening another. - Invert "Slack notifications" to actionable-only. The old rule required posting on every run and was the direct cause of the channel noise. Its silent-failure rationale is preserved by requiring a run log instead. - Rewrite "Log availability" so outer loops read the log branch rather than main, and never merge the standing log PR as a workflow step. Cron correctness: - `0 17 1-7 * 1` is not "first Monday". Cron ORs day-of-month with day-of-week, so it fired ~11 times a month and produced four conflicting PRs in six days. Replace with `0 17 * * 1` plus an in-skill first-week guard in improve-drafting-skills, improve-aeo-crosslink-skill, and improve-404-monitor-skill. PR reuse applied to: improve-drafting-skills, weekly-404-monitor, afdocs-fix, sync-error-docs, sync_terminology, sync-openapi-spec, improve-aeo-crosslink-skill, improve-404-monitor-skill. update-changelog keeps one PR per release (correct) but now detects stacked release PRs. Slack volume: aeo_crosslink_audit no longer posts on no-change runs; weekly-404-monitor gates on threshold and folds its Phase 2 results into a single message instead of two; afdocs-audit posts only on regression or a blocked audit, backed by a new run log for the baseline. Migration artifacts: a find-and-replace during the GitBook-to-Astro move substituted descriptions into file paths. sync-error-docs referenced `astro.config.mjs (sidebar config)` and `vercel.json (redirects)` as real paths, had an invalid grep, and still called the GitBook API - it could not have succeeded. Also corrected the sidebar location to src/sidebar.ts, dropped the GITBOOK_TOKEN dependency, and fixed dead `.warp/references/terminology.md` paths in four skills. Consolidates PRs #450, #454, #468, and #484, which all edited draft_docs/SKILL.md and conflicted with each other. Overlapping patterns were merged rather than stacked, and PR #468's frontmatter-description edits were dropped as already superseded on main. Co-Authored-By: Warp Agent <agent@warp.dev> * docs(skills): document the deployed monthly cron for improve-drafting-skills The schedule was deployed as `0 15 1 * *` (the 1st of each month) rather than the `0 17 * * 1` + first-week-guard combination the skill documented. Both are correct and both fire exactly once a month, but the docs and the deployed schedule disagreed. Documented the deployed expression. Restricting only day-of-month is unambiguous because day-of-week stays `*`, so there is no ORing hazard. The tradeoff is noted: the 1st can land on a weekend, delaying review. Kept the first-week guard as a safety net and explained why, since it no longer trips on its own: it is what would narrow a day-of-week expression back to the first Monday, and it contains the blast radius if the day-of-month/day-of-week ORing mistake is ever reintroduced. Reworded the guard's skip message, which still referenced 'first Monday'. Co-Authored-By: Warp Agent <agent@warp.dev> * docs(skills): treat a log-branch fetch failure as blocked, not a stale fallback Review catch on improve-aeo-crosslink-skill: its step 0 said to fall back to the log copy in the current checkout when the branch fetch fails. That copy comes from `main` — precisely the truncated history the branch read exists to avoid — so the fallback reintroduced the problem this PR set out to fix. The file also contradicted itself: its Slack section already listed 'could not fetch the log branch' as a blocked-run example while step 0 said not to abort. The failure mode is quiet, which is what makes it worth fixing. A short log still parses; only the counts change. The run then either drops below the 8-entry minimum and reports 'too early to analyze', or clears the minimum on stale entries and proposes skill edits from an incomplete picture. Both look like ordinary outcomes, so nobody investigates. Both outer loops that read a log branch now stop before analysis on a fetch failure and post the blocked-run message. improve-drafting-skills already had this behavior documented and is unchanged. Also generalized the rule in the authoring guidelines, since this is a class of bug rather than a one-off: do not adopt a fallback that is quieter but less correct than failing. The test is whether the fallback can change the answer ratherratherratherratherratherratherratherratherratherratherratherratverage transparently — proceeding on one source signal and recording the gap — remain fine, because the reader can see what was missing. Co-Authored-By: Warp Agent <agent@warp.dev> --------- Co-authored-by: Warp Agent <agent@warp.dev>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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 recentoz run listconversations (inner loop still not emitting markers reliably).heading_specificity (human feedback across 16+ PRs in the durable log; 24 multi-PR human-edit clusters in this collector pass)
Overview,More details,Other) even when sentence case is correct.frontmatter (human feedback across 22 PRs in-window)
descriptionrule indraft_docsstep 6.5 and mirrored it into conceptual/reference template brackets.list_format (human feedback across 25 PRs in-window; reviewers explicitly asked for
*markers to match templates)*as the top-level unordered marker.link_quality (human feedback across 24 PRs in-window)
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 sectionIntentionally not editing
feature-doc.md,procedural.md,guide-page.md, orcreate_pr/SKILL.mdin 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
AGENTS.md/ step 6.5 at useful specificity, or lacks a single tight skill edit that would change agent behavior beyond existing rules.Open questions for human review
## Overview” be treated as always-wrong, or allowed when it is the only H2 under a highly specific page title?## Related pagesdesirable on pure CLI flag dumps, or only when a conceptual companion exists (current wording is “when a companion exists”)?draft_docs/SKILL.md.Test plan
.agents/skills/and.agents/templates/AGENTS.mddraft_docs/SKILL.mdStanding 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.