docs(skills): improve drafting skills from signal log patterns - #668
Conversation
Elevate recurring human review nits into draft_docs critical rules and procedural/feature templates: quotation marks for non-clickable field labels, and an explicit Cut again pass before shipping long pages.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
This PR was generated with Warp. Comment |
|
I'm starting a first review of this pull request. You can view the conversation on Warp. I completed the review and no human review was requested for this pull request. Comment Powered by Oz |
![warp-for-oss[bot]](https://avatars.githubusercontent.com/in/3450139?s=60&v=4){kind=small}
There was a problem hiding this comment.
Overview
This PR updates the docs drafting skill and feature/procedural templates to reinforce field-label formatting and brevity guidance.
Concerns
- The new field-label rule can be read as telling agents to bold generic control words like "dropdown" or "input," which conflicts with the rule's examples and the docs style guide.
- No approved spec context applies to this PR, and I found no security concerns in the changed skill/template guidance.
Verdict
Found: 0 critical, 1 important, 0 suggestions
Request changes
Comment /warp-agent-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
Co-authored-by: warp-for-oss[bot] <277970191+warp-for-oss[bot]@users.noreply.github.com>
![warp-factories[bot]](https://avatars.githubusercontent.com/in/2278701?s=60&v=4){kind=small}
There was a problem hiding this comment.
Overview
Adds a field-label bold/quote rule and a "cut before splitting" drafting step to draft_docs and its templates, based on prior human review feedback signals. Net position: approve (posted as a comment — GitHub blocks this bot from approving its own PR).
Verdict
Checks: build/link-check/audit and CodeQL pending (none failing), tests n/a (doc-only skill/template change, exempt as pure copy), visual proof n/a
Found: 0 critical, 0 important, 0 suggestions, 0 nits
One internal inconsistency was found during review (the new "Bold the control next to it (dropdown, input, or the option you choose)" wording in .agents/skills/draft_docs/SKILL.md conflicted with its own ✅ example and with the parallel template wording) — it was already corrected in commit b751797 before this review posted, so no outstanding action is needed.
1 participant
Run history
Patterns addressed
2026-09-01ui_field_label_quotes — human review comments across factory/procedural PRs (e.g. docs: expand Factory agents third-party harness setup (DOCFAC-1787856600) #647): non-clickable field labels like "Harness" were bolded. Added a critical formatting rule + checklist item indraft_docs, and bracket instructions in procedural/feature templates. Quotes for labels; bold only for interactive controls and selected options.2026-09-01drafting_brevity_cut_again — human review comments on multi-PR factory docs (e.g. docs: expand Factory agents third-party harness setup (DOCFAC-1787856600) #647 verbosity / over-explained internals) plus prior signal that length was review-only. Elevated Cut again intodraft_docsstep 6.5 as a drafting rule with a concrete ✅/❌, and added step-level brevity guidance in templates. (review-docs-pralready flags length after PR Overhaul docs tone guidance and rewrite platform overview as example #606.)Improvement targets
2026-09-01.agents/skills/draft_docs/SKILL.md— field-label quotes rule; Cut length before shipping rule; checklist item for non-clickable labels2026-09-01.agents/templates/procedural.md— UI LABELS + BREVITY IN STEPS bracket instructions2026-09-01.agents/templates/feature-doc.md— procedural section notes for quotes and short stepsPatterns reviewed but not acted on
2026-09-01settings_path / list_format / frontmatter / heading_specificity / callout / link_quality / screenshots / VideoEmbed / action_first / ambiguous wording / product vars — already covered indraft_docs6.5 (including merged PR docs(skills): improve drafting skills from signal log patterns 2026-08-05 #478). Bulkhuman_editclassifications often reflect whole-diff category labels rather than new skill gaps.2026-09-01terminology / Warp Factories casing — already in AGENTS.md glossary and style_lintfactory-proper-noun; no additional draft_docs example without exceeding the 3-file cap.2026-09-01code_fence — most hits were GitHubsuggestionblocks misclassified as fence issues; true fence guidance already in AGENTS.md.2026-09-01[skill-feedback] x3 on PR docs: Warp Agent CLI launch documentation #411 — product-vars, ambiguous "when", and action-first already present in 6.5 from earlier loops.2026-09-01style-lint / pr-review Oz SIGNAL markers — none in drafting skill runs this window (draft_*/review-docs-pr/style_lintlisted 0 runs).Open questions for human review
2026-09-01— Whether multi-platform filesystem paths (macOS/Linux/Windows) deserve a dedicated 6.5 bullet, or stay as case-by-case verification under "verify labels against source" (one CLI log-path review comment).2026-09-01— Standing log PR chore: drafting signal logs #467 should be merged periodically somainpicks up the 171 new human-feedback records from this run.