Merge #661: preserve source details during prose review in documentation-and-adrs

evals/cases/documentation-and-adrs.json

@@ -39,6 +39,24 @@
         "Trade-offs and rejected options are recorded, not just the winning choice",
         "The ADR records a status from the skill's lifecycle (Proposed, Accepted, Superseded or Deprecated) and a date"
       ]
+    },
+    {
+      "id": 4,
+      "kind": "execution",
+      "prompt": "Review README.md for operators onboarding to this batch queue. Make the prose clearer, check it against queue.js, and keep the operational details and caveats accurate. Do not change the implementation.",
+      "expected_output": "A concise operational README grounded in the inspected implementation, with unsupported assurances removed or flagged, limits and caveats preserved, and the unverified command identified",
+      "files": [
+        "documentation-and-adrs/prose-review"
+      ],
+      "expectations": [
+        "The final README identifies queuectl submit jobs.json --max-batch-size 50 as an unverified documented example because the fixture contains neither the CLI nor jobs.json; it does not invent, silently certify, or replace that interface",
+        "The final README preserves the 50-job batch limit, 72-hour retention period, and at most three retries, distinguishing those units correctly",
+        "The final README preserves the operational caveat that failed jobs require operator review and queue state is not durable across a process restart",
+        "The unsupported claims of guaranteed zero job loss and no need for monitoring are removed or explicitly marked as unsubstantiated rather than restated as facts",
+        "The promotional opening is replaced with a concrete description of the queue without invented users, benchmarks, certifications, or capabilities",
+        "The execution trace shows the agent inspecting queue.js and comparing the README with its batch, retention, retry, and in-memory-state implementation before editing",
+        "queue.js remains unchanged, and the agent does not install a tool or send the fixture to a hosted service"
+      ]
     }
   ]
 }

evals/fixtures/documentation-and-adrs/prose-review/README.md

@@ -0,0 +1,19 @@
+# Batch Queue
+
+Batch Queue is an innovative, enterprise-grade solution that seamlessly unlocks
+the power of batch processing. In today's fast-paced landscape, it is important
+to note that this robust queue empowers operators to take work to the next level.
+
+## Submit a batch
+
+```sh
+queuectl submit jobs.json --max-batch-size 50
+```
+
+A batch contains at most 50 jobs. Queue entries expire after 72 hours. Failed
+jobs are retried at most three times.
+
+Operators review jobs that still fail after retries. Queue state is held in
+memory and is not durable across a process restart.
+
+This guarantees zero job loss and means operators never need to monitor the queue.

evals/fixtures/documentation-and-adrs/prose-review/queue.js

@@ -0,0 +1,32 @@
+'use strict';
+
+const MAX_BATCH_SIZE = 50;
+const RETENTION_MS = 72 * 60 * 60 * 1000;
+const MAX_RETRIES = 3;
+const jobs = new Map();
+
+function submit(batch, now = Date.now()) {
+  if (batch.length > MAX_BATCH_SIZE) throw new Error('Batch exceeds limit');
+  for (const job of batch) {
+    jobs.set(job.id, { ...job, createdAt: now, retries: 0, state: 'queued' });
+  }
+}
+
+function recordFailure(id) {
+  const job = jobs.get(id);
+  if (!job) throw new Error('Unknown job');
+  if (job.retries < MAX_RETRIES) {
+    job.retries += 1;
+    job.state = 'queued';
+  } else {
+    job.state = 'operator-review';
+  }
+}
+
+function expire(now = Date.now()) {
+  for (const [id, job] of jobs) {
+    if (now - job.createdAt >= RETENTION_MS) jobs.delete(id);
+  }
+}
+
+module.exports = { submit, recordFailure, expire, MAX_BATCH_SIZE, RETENTION_MS, MAX_RETRIES };

skills/documentation-and-adrs/SKILL.md

@@ -256,6 +256,14 @@ Special consideration for AI agent context:
 - **ADRs** — Help agents understand why past decisions were made (prevents re-deciding)
 - **Inline gotchas** — Prevent agents from falling into known traps
 
+## Prose Review
+
+After checking the technical content, review the prose for the people who will use it. Clearer wording must not change the decision or its limits.
+
+1. Mark the details that must survive the edit: names, numbers and units, commands, paths, links, conditions, trade-offs, and uncertainty. Check them against the available code and decision context; flag anything you cannot substantiate.
+2. Replace stock introductions, promotional adjectives, and repeated summaries with the concrete information the reader needs. Do not replace an unsupported claim with an invented example or a stronger guarantee. Keep necessary technical repetition and the project's established terminology.
+3. Compare the edited document with the original and its sources. Restore any lost qualifier or caveat, verify command and code examples still work as documented, and explain any unresolved factual question rather than polishing it away.
+
 ## Common Rationalizations
 
 | Rationalization | Reality |
@@ -286,3 +294,4 @@ After documenting:
 - [ ] Known gotchas are documented inline where they matter
 - [ ] No commented-out code remains
 - [ ] Rules files (CLAUDE.md etc.) are current and accurate
+- [ ] Prose edits preserve source details, decision trade-offs, and qualifiers without adding unsupported guarantees