docs: allow one-to-two-sentence frontmatter descriptions consistently - #660
Conversation
Reconcile AGENTS.md's frontmatter description rule with draft_docs/SKILL.md:143, which already documented the more permissive one-to-two-sentence guidance. Update the two contradicting spots in AGENTS.md (Description rules, SEO section, and the quality checklist), plus every content-type template and draft_* skill that still stated a strict one-sentence-only rule, so the whole repo is internally consistent. The 50-160 character budget is unchanged. Co-Authored-By: Warp <agent@warp.dev>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
@warp-agent-staging[bot] 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 |
|
This PR was generated with Warp. Comment    |
![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 reconciles the docs repository's frontmatter-description guidance so AGENTS.md, content-type templates, and draft skills all allow one to two concise sentences within the existing 50-160 character budget. The diff is scoped to prose guidance and does not add code, tests, links, or user-facing documentation pages.
Concerns
- No blocking concerns found.
- Security pass: no security-relevant code, configuration, authentication, authorization, secrets, or data-handling changes are present in the diff.
- Spec check: no approved or repository spec context was provided for this PR.
- Comment/test audit: the PR does not add or modify code comments or tests.
Verdict
Found: 0 critical, 0 important, 0 suggestions
Approve
Comment /warp-agent-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
1 participant
Summary
AGENTS.md's frontmatter description rule contradicteddocs/.agents/skills/draft_docs/SKILL.md:143, which already documents the correct, more permissive rule: "One to two sentences, roughly 50-160 characters, stating the user benefit and primary keywords." This inconsistency caused JAS-5's code review of PR #656 to flag an in-budget two-sentence description as a blocking finding.This PR reconciles the rule across the repo:
AGENTS.md"Description rules" subsection: now allows up to two short sentences when they stay within the 50-160 character budget and genuinely improve readability/clarity, while keeping the "prefer one sentence when it earns its length" guidance.AGENTS.mdfrontmatter YAML example and SEO section: updated to match.AGENTS.mdQuality checklist: "one-sentence description" → "one-to-two-sentence description".conceptual.md,procedural.md,quickstart.md,reference.md,feature-doc.md,guide-page.md,faq.md,troubleshooting.md) and every correspondingdraft_*skill: updated the same frontmatter-description guidance for consistency.The 50-160 character budget itself is unchanged — only the strict one-sentence-only constraint was relaxed.
Verification
This is a skill-doc/style-guide prose change with no new testable code (skill-doc-only exemption per
factory-verification), so no regression test was added. Ran the repo's documented checks:trunk check/trunk fmt— Trunk is not vendored in this sandbox and is not installed, so these could not be run (consistent with prior PRs in this thread).python3 .agents/skills/style_lint/style_lint.py --changed— 0 files scanned (style lint targetssrc/content/docs/pages; this change only touchesAGENTS.mdand.agents/), no issues found.AGENTS.mdand.agents/templates/+.agents/skills/draft_*— no unrelated files touched, and thecreate_pr/SKILL.mdPR-body word-budget rule was left untouched as instructed.This unblocks JAS-5 (PR #656's review), which was blocked on a two-sentence-but-in-budget frontmatter description finding.
Originating thread: https://warpdev.slack.com/archives/C09BVK0PL3Y/p1787900556500469