Refine public developer documentation guidance (#68)

evals/cases/grounded-writing-direct/case.json

@@ -1,6 +1,6 @@
 {
   "id": "grounded-writing-direct",
-  "title": "Turn a raw release note into grounded prose",
+  "title": "Rewrite public quality-setting documentation",
   "family": "writing",
   "target_skills": ["grounded-writing"],
   "expected_skills": ["grounded-writing"],
@@ -10,8 +10,9 @@
   "allowed_write_paths": ["draft.md"],
   "validators": [{"argv": ["python3", "@validators/text_case.py", "grounded-writing-direct"], "timeout_seconds": 30}],
   "rubric": [
-    {"id": "evidence", "text": "The note retains the measured p95 change and its duplicate-parse mechanism"},
-    {"id": "qualification", "text": "The note does not claim universal production improvement before the stated production evidence exists"}
+    {"id": "user-decision", "text": "The documentation explains the visible difference between quality settings and when to choose each one"},
+    {"id": "contract-and-limit", "text": "The documentation retains the public quality contract and meaningful limitation without inventing performance or visual claims"},
+    {"id": "implementation-boundary", "text": "The public documentation removes minimum-pixel interpolation, CPU-mask, and cooldown implementation detail because none is needed to use the API correctly"}
   ],
   "provenance": {"kind": "synthetic"}
 }

evals/cases/grounded-writing-direct/expectations.json

@@ -1,5 +1,5 @@
 {
   "files": ["draft.md"],
-  "must_contain": ["p95", "1.8", "1.1", "duplicate parse"],
-  "must_match": ["(?i)production"]
+  "must_contain": ["Full", "Adaptive", "experimental"],
+  "must_not_contain": ["minimum-pixel", "CPU mask", "cooldown"]
 }

evals/cases/grounded-writing-direct/overlay/draft.md

@@ -0,0 +1,9 @@
+## Rendering quality
+
+`Full` keeps the complete Glass treatment. Choose it when visual fidelity is
+the priority. `Adaptive` reduces the effect during sustained interaction to
+trade some visual detail for steadier performance. Both settings preserve the
+same public API; Adaptive remains experimental on Android backdrops.
+
+Adaptive chooses its interpolation from a minimum-pixel threshold, combines a
+CPU mask with the backdrop, and restores Full after a 250 ms cooldown.

evals/cases/grounded-writing-direct/prompt.md

@@ -1,3 +1,2 @@
-Rewrite `draft.md` as a short, natural release note. Keep the concrete evidence
-and qualification; do not invent results, user reactions, or personal
-experience.
+Rewrite `draft.md` as concise public developer documentation for rendering
+quality. Do not invent results or experience.

evals/cases/grounded-writing-negative/case.json

@@ -1,6 +1,6 @@
 {
   "id": "grounded-writing-negative",
-  "title": "Leave an already-grounded note intact",
+  "title": "Leave an internal technical report intact",
   "family": "writing",
   "target_skills": ["grounded-writing"],
   "expected_skills": ["grounded-writing"],
@@ -10,8 +10,8 @@
   "allowed_write_paths": [],
   "validators": [{"argv": ["python3", "@validators/text_case.py", "grounded-writing-negative"], "timeout_seconds": 30}],
   "rubric": [
-    {"id": "restraint", "text": "The response recognizes that the note already gives evidence, mechanism, and an honest qualification"},
-    {"id": "no-invention", "text": "The response does not add a fabricated user outcome, adoption result, or stronger performance claim"}
+    {"id": "restraint", "text": "The response recognizes that an internal technical report appropriately retains its implementation and diagnostic detail"},
+    {"id": "no-invention", "text": "The response does not add a fabricated user outcome, visual result, or stronger performance claim"}
   ],
   "provenance": {"kind": "synthetic"}
 }

evals/cases/grounded-writing-negative/expectations.json

@@ -1,4 +1,4 @@
 {
   "files": ["draft.md"],
-  "must_contain": ["p95 fell from 1.8 seconds to 1.1 seconds", "duplicate parse", "production data"]
+  "must_contain": ["minimum-pixel interpolation", "CPU mask", "cooldown", "p95", "device matrix"]
 }

evals/cases/grounded-writing-negative/overlay/draft.md

@@ -0,0 +1,8 @@
+# Adaptive quality technical report
+
+The device matrix covers Pixel 8, Pixel 6, and a low-end reference device. For
+each device, capture p50 and p95 frame time during the scrolling trace.
+
+Adaptive uses minimum-pixel interpolation, a CPU mask for backdrop sampling,
+and a 250 ms cooldown before restoring Full. Retain these details so a
+regression can be traced to the implementation stage that changed.

evals/cases/grounded-writing-negative/prompt.md

@@ -1,2 +1,3 @@
-`draft.md` is already approved for publication. Review it and edit only if a
-real clarity or truth problem remains; do not rewrite it for style alone.
+`draft.md` is an approved internal technical report. Review it and edit only if
+a real clarity or truth problem remains; do not rewrite it as public developer
+documentation or remove its diagnostic detail.

evals/cases/grounded-writing-novel/case.json

@@ -1,6 +1,6 @@
 {
   "id": "grounded-writing-novel",
-  "title": "Review an evidence-led release note",
+  "title": "Review public rendering-quality documentation",
   "family": "writing",
   "target_skills": ["grounded-writing"],
   "expected_skills": ["grounded-writing"],
@@ -10,8 +10,9 @@
   "allowed_write_paths": [],
   "validators": [{"argv": ["python3", "@validators/text_case.py", "grounded-writing-novel"], "timeout_seconds": 30}],
   "rubric": [
-    {"id": "voice", "text": "The review recommends concise evidence-led prose rather than marketing language"},
-    {"id": "truth", "text": "The review preserves the stated production-data qualification and does not invent support for a stronger claim"}
+    {"id": "user-decision", "text": "The review asks for the visible difference, setting choice, and practical trade-off that a developer needs"},
+    {"id": "implementation-boundary", "text": "The review recommends moving interpolation and CPU-mask machinery out of public documentation while retaining relevant contracts and limitations"},
+    {"id": "truth", "text": "The review does not invent a performance result or claim that the setting is universally better"}
   ],
   "provenance": {"kind": "synthetic"}
 }

evals/cases/grounded-writing-novel/expectations.json

@@ -1,4 +1,4 @@
 {
   "files": ["draft.md"],
-  "must_contain": ["p95", "1.8 seconds", "1.1 seconds", "duplicate parse", "production data"]
+  "must_contain": ["Full", "Adaptive", "12 pixels", "CPU mask", "experimental"]
 }

evals/cases/grounded-writing-novel/overlay/draft.md

@@ -0,0 +1,5 @@
+## Rendering quality
+
+`Full` uses the complete effect. `Adaptive` samples every 12 pixels, builds a
+CPU mask for the backdrop, and waits for a 250 ms cooldown before restoring
+Full. It is experimental on Android backdrops.

evals/cases/grounded-writing-novel/prompt.md

@@ -1,3 +1,2 @@
 Review `draft.md` and recommend the smallest changes needed before publication.
-Do not edit files. Keep the measured claim separate from what still needs
-production evidence.
+Do not edit files.

evals/tests/test_workflows_writing_matrix.py

@@ -284,14 +284,16 @@ class WorkflowsWritingMatrixTest(unittest.TestCase):
             with self.subTest(case=case.id):
                 self.assertNotIn("do not run agents, commands", case.prompt.lower())
 
-    def test_grounded_writing_validator_accepts_qualified_every_project_language(self):
+    def test_grounded_writing_validator_accepts_public_quality_guidance(self):
         validator = REPO_ROOT / "evals/validators/text_case.py"
         with tempfile.TemporaryDirectory() as temp_dir:
             workspace = Path(temp_dir)
             (workspace / "draft.md").write_text(
-                "Imports avoid a duplicate parse. In the release benchmark, p95 "
-                "fell from 1.8 seconds to 1.1 seconds. Production evidence is still "
-                "needed before claiming the same improvement for every project.\n",
+                "`Full` keeps the complete effect when visual fidelity matters. "
+                "Choose `Adaptive` during sustained interaction when steadier "
+                "performance matters more than the visible detail it reduces. "
+                "The settings preserve the same public API; Adaptive remains "
+                "experimental on Android backdrops.\n",
                 encoding="utf-8",
             )
 

skills/grounded-writing/SKILL.md

@@ -22,29 +22,35 @@ generic, or included only to imitate a personality.
 3. Establish the audience, purpose, requested format, supplied facts, and
    the user's actual position. Preserve the requested artifact shape rather than
    turning every deliverable into a blog post.
-4. Resolve missing material before writing:
+4. In public developer documentation, explain observable behaviour, setting
+   choices, trade-offs, and relevant limitations. Keep implementation and
+   test or diagnostic detail in internal references unless needed to use the
+   API correctly or explicitly requested. Retain public contracts and the
+   context needed to interpret claims. This does not apply to internal design
+   documents or technical reports.
+5. Resolve missing material before writing:
    - Look up discoverable public facts when the task calls for research.
    - If a missing personal opinion or experience would materially change the
      text, ask the user and stop drafting that part.
    - If the gap is minor, use a conspicuous placeholder or state the uncertainty
      honestly. Never invent a first-person claim, result, preference, or memory.
-5. Choose the register from the style profile. Match the length and formality to
+6. Choose the register from the style profile. Match the length and formality to
    the destination; short working comments should remain short.
-6. Shape the reasoning before polishing sentences. Prefer a concrete problem or
+7. Shape the reasoning before polishing sentences. Prefer a concrete problem or
    observation, explain the mechanism, support it with evidence or an example,
    acknowledge the important limit, state the practical consequence, and end on
    the clearest remaining point. Omit any stage the artifact does not need. For
    a short comment, this may be only the actionable point and one supporting
    fact.
-7. Use the user's default language and regional conventions unless the request
+8. Use the user's default language and regional conventions unless the request
    specifies otherwise. Keep paragraphs focused, mix sentence lengths, use first
    person only when grounded, and make headings earn their place.
-8. Edit once for style and once for truth. Remove generic scene-setting,
+9. Edit once for style and once for truth. Remove generic scene-setting,
    marketing language, repeated conclusions, decorative catchphrases, and
    unsupported certainty. Treat the headline and opening claim as substantive:
    remove or qualify promotional framing that the supplied evidence does not
    directly support.
-9. For a no-change review, name the material facts, mechanism, and qualification
+10. For a no-change review, name the material facts, mechanism, and qualification
    that make the existing text publishable. A bare “no edit needed” does not
    show that the truth and clarity checks were completed.