[rachaelrenk]

Summary

Preserves reusable lessons from the combined factory-recipe review in #895 without coupling the guidance changes to that content stack. This PR changes internal Docs guidance and evaluation inputs only; it adds no public product claims or runtime behavior.

Changes

• Strengthens AGENTS.md as the authoritative home for task-first field instructions, coherent setup phases, existing-resource paths, configuration/access versus skill instructions, and safety beside copyable actions.
• Adds composed-workflow review guidance for overlapping triggers, cumulative exclusions, handoffs, stopping points, and continued-conversation ownership.
• Keeps standalone answers naturally attributable while separating measured umbrella signals from unmeasured topic-level recommendations.
• Adds concise pointers in draft_docs, review-docs-pr, and aeo_brief, plus bracketed hints in the procedural and feature templates.
• Corrects the procedural template's prerequisite example to use the existing unbolded-bullet convention.
• Adds four fixed-fact editing cases at .agents/skills/draft_docs/evals/evals.json, with 28 assertions.

Factory-specific labels, routing semantics, credentials, and deployment facts remain in product references rather than universal style rules. No public recipe pages or serializer code are included.

Validation and evaluation

• test_editorial_guidance.py: 8 tests passed.
• test_publishing_snippet.py: 4 tests passed.
• git diff --check passed.
• Checked template bracket conventions, unchanged skill names/frontmatter, canonical guidance pointers, and evaluation JSON structure.
• Original guidance was snapshotted before editing and checked against base 17b29842. Both variants received identical fixed-fact editing prompts, with grading assertions withheld.
• Four cases cover alternate-name task-first procedures, verifier setup boundaries, stateful Jira routing, and AEO attribution/evidence scope.
• Both original and updated guidance passed 27/28 assertions. Both omitted the exact two umbrella signal names from the editorial rationale in the fourth case. This is narrow regression coverage, not evidence of a general quality improvement.
• Updated outputs grouped some setup steps more tightly, but fewer steps is not itself better prose. Human readability review remains necessary.

The static reviewer, eight output drafts, and grading/benchmark JSON remain local under /tmp/docs-drafting-guidance-eval/; they are not portable CI artifacts or committed generated reports. Only the reusable evaluation inputs are committed. There was one drafting batch per variant and one sample per case; shared inherited rules, highly directed prompts, and within-batch context limit causal conclusions. Timing and token metrics were unavailable and were not invented.

Documentation risk

Risk: low
Rationale: Internal Docs-team skill, style-guide, template, and evaluation-input maintenance only; no public product claims or developer-facing command, API, setting, integration, or runtime behavior changes.
Docs override: none

Unverified claims

No new public product claims. Fixed-fact evaluation examples are editing fixtures, not live product verification. Broader drafting-quality improvement is unmeasured.

Review focus

Check that the rules generalize beyond the factory recipes, retain necessary instructional context without adding boilerplate, and keep canonical policy in AGENTS.md. The paired examples are available in the local review viewer for qualitative review.

No reviewer was requested: this internal Docs guidance change has no uniquely resolved owning engineer.

Related content fixes: #895

Implementation and evaluation context: https://staging.warp.dev/conversation/022d43d0-010c-4bc2-b6b7-58523e50176a

Co-Authored-By: Warp agent@warp.dev

[vercel]

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

Project	Deployment	Actions	Updated
docs	Ready	Preview	Oct 28, 2026 10:32pm UTC

[warp-agent-staging]

No blocking findings at 88abf6e; the setup, safety, and evidence-scope guidance is consistent with this internal-only change. All 12 editorial-guidance tests and 4 publishing-snippet tests pass; two CI checks are still running. Approving with one nonblocking test-maintenance suggestion below.

Responding as Docs Factory (V2): Open session · View in factory

[warp-agent-staging]

@rachaelrenk, your GitHub account is not connected to Warp. Connect your GitHub account.

[warp-local-for-testing-only]

@rachaelrenk, your GitHub account is not connected to Warp. Connect your GitHub account.