docs(skills): improve drafting skills from signal log patterns - #809
Draft
warp-factories[bot] wants to merge 1 commit into
Draft
warp-factories[bot] wants to merge 1 commit into
warp-factories[bot] wants to merge 1 commit into
Conversation
…n checks From the 2026-10-01 improve-drafting-skills signal window: human reviews kept asking for plain-language definitions with concrete examples, early orientation media without stacked videos, and less internal detail; review-docs-pr flagged compression-contract overruns on multiple PRs.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
Author
|
This PR was generated with Warp. Comment |
This branch was successfully deployed
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
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.
Run history
Patterns addressed
2026-10-01plain_language_define_show_example — human review comments across factory feature PRs (docs: document Factory Benchmarks (GROW-6129) #685, docs: nest Scorers, Self-improvement, and Benchmarks under Measure and improve (GROW-6131) #721, docs: Surface factory definition validation and schema; fix .md code blocks #727, docs: document Warp's native workspaces model #723): jargon-first sections without a plain definition or concrete example. Added a critical formatting rule + checklist item indraft_docs, and DEFINE→SHOW→LINK bracket instructions in conceptual/feature templates.2026-10-01compression_contract_enforcement —[SIGNAL:pr-review]top_categorycompression-contracton 6 of 24 sampled review runs (e.g. docs: Update cloud provider federation claims #798 over 1500 words). Elevated the mechanicalcheck_compression_contract.pyrun intodraft_docsstep 8 and the feature-doc BREVITY bracket so agents cut before review instead of shipping over-budget pages.2026-10-01orientation_media_placement — human review on docs: document Factory Benchmarks (GROW-6129) #685 (orientation video above the fold; no back-to-back videos; more screenshots for visual surfaces). Added orientation-media rule + checklist item indraft_docs, and a MEDIA bracket in the feature-doc template. Also sharpened the sidebar source-comment example from docs: nest Scorers, Self-improvement, and Benchmarks under Measure and improve (GROW-6131) #721 skill guidance.Improvement targets
2026-10-01.agents/skills/draft_docs/SKILL.md— plain-language define/show rule; orientation media rule; compression check in step 8; checklist items; sidebar comment ✅/❌2026-10-01.agents/templates/conceptual.md— DEFINE→SHOW→LINK bracket; plain-language key-concept note2026-10-01.agents/templates/feature-doc.md— DEFINE→SHOW→LINK, MEDIA, and compression BREVITY brackets; user-visible how-it-works notePatterns reviewed but not acted on
2026-10-01settings_path / list_format / frontmatter / header_case / callout / link_quality / ui_field_label_quotes / drafting_brevity_cut_again — already covered indraft_docs6.5 (including merged PR docs(skills): improve drafting skills from signal log patterns #668). Bulkhuman_editclassifications often reflect whole-diff category labels rather than new skill gaps.2026-10-01terminology / Warp Factories casing — already in AGENTS.md glossary and style_lintfactory-proper-noun.2026-10-01technical-claim-verification — scattered agent findings (1–2); verify-against-source already in 6.5; no new rule without a clearer multi-PR human pattern.2026-10-01provider-specific subpage IA (docs: add Vercel to custom webhooks and the deferred-secret setup #750) — product/IA decision more than a drafting-skill fix; left as open question.2026-10-01style-lint Oz SIGNAL markers — 0 parseable style-lint markers in sampled drafting runs this window (24 pr-review markers found).Open questions for human review
2026-10-01— Whether provider-specific webhook/integration pages (Vercel/Stripe/PagerDuty) should get a standing template rule to nest under a general overview, or stay case-by-case content design.2026-10-01— Standing log PR should be merged periodically somainpicks up the September human-feedback batch and pr-review run entry.Documentation risk
Risk: engineering-review-required
Rationale: Skill and template prose changes agent drafting behavior (plain-language, media placement, compression check), not a wording-only docs tweak.
Source files consulted: .agents/logs/human_review_feedback.jsonl (collector window), Oz [SIGNAL:pr-review] payloads from review-docs-pr runs in September 2026
Requested engineering reviewers: none
Engineering review status: pending
Docs override: none
Unverified claims
None — all UI labels, flags, defaults, and eligibility claims were verified against source.