From fe9f1f26e0fee1c4e119adaa1e3ef0d3f2ae9e27 Mon Sep 17 00:00:00 2001 From: Prompeteer Date: Wed, 7 Oct 2026 12:15:24 -0700 Subject: [PATCH 1/3] docs: add source-preserving prose review to documentation skill Keep operational facts and caveats intact when editing documentation. Reference a pinned Zero Slop workflow only as an optional review aid, and add an execution fixture for the preservation checks. --- evals/cases/documentation-and-adrs.json | 17 ++++++++++ .../prose-review/README.md | 19 +++++++++++ .../prose-review/queue.js | 32 +++++++++++++++++++ skills/documentation-and-adrs/SKILL.md | 11 +++++++ 4 files changed, 79 insertions(+) create mode 100644 evals/fixtures/documentation-and-adrs/prose-review/README.md create mode 100644 evals/fixtures/documentation-and-adrs/prose-review/queue.js diff --git a/evals/cases/documentation-and-adrs.json b/evals/cases/documentation-and-adrs.json index 431074eb..8b96d30e 100644 --- a/evals/cases/documentation-and-adrs.json +++ b/evals/cases/documentation-and-adrs.json @@ -39,6 +39,23 @@ "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 implementation, with unsupported assurances removed or flagged and command examples, limits, and caveats preserved", + "files": [ + "documentation-and-adrs/prose-review" + ], + "expectations": [ + "The final README retains the documented queuectl submit jobs.json command and its --max-batch-size 50 option without inventing an alternative 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", + "queue.js remains unchanged, and the agent does not install a tool or send the fixture to a hosted service" + ] } ] } diff --git a/evals/fixtures/documentation-and-adrs/prose-review/README.md b/evals/fixtures/documentation-and-adrs/prose-review/README.md new file mode 100644 index 00000000..e8b65f2c --- /dev/null +++ b/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. diff --git a/evals/fixtures/documentation-and-adrs/prose-review/queue.js b/evals/fixtures/documentation-and-adrs/prose-review/queue.js new file mode 100644 index 00000000..7c6dda6b --- /dev/null +++ b/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 }; diff --git a/skills/documentation-and-adrs/SKILL.md b/skills/documentation-and-adrs/SKILL.md index e37c38f3..1ba9d75f 100644 --- a/skills/documentation-and-adrs/SKILL.md +++ b/skills/documentation-and-adrs/SKILL.md @@ -256,6 +256,16 @@ 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. + +If the team already uses a reviewed version of [Zero Slop](https://github.com/manavmishra/ZeroSlop/tree/43b71836bf2feb8395a84aaeea809bd7ef65e385), its source-preserving editing workflow can assist this pass. This reference pins v2.12.22; do not install or update a tool just to complete the review. Its writing score is heuristic, not proof of factual accuracy or AI authorship. A lower score does not replace the source comparison, and this step does not require sending the document to a hosted editor. + ## Common Rationalizations | Rationalization | Reality | @@ -286,3 +296,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 From 3acf1b8ac0cae5d0a11945832f5da55ef5065a64 Mon Sep 17 00:00:00 2001 From: Prompeteer Date: Wed, 7 Oct 2026 12:21:53 -0700 Subject: [PATCH 2/3] test: require source inspection and flag unverified queue command --- evals/cases/documentation-and-adrs.json | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/evals/cases/documentation-and-adrs.json b/evals/cases/documentation-and-adrs.json index 8b96d30e..1ea78028 100644 --- a/evals/cases/documentation-and-adrs.json +++ b/evals/cases/documentation-and-adrs.json @@ -44,16 +44,17 @@ "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 implementation, with unsupported assurances removed or flagged and command examples, limits, and caveats preserved", + "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 retains the documented queuectl submit jobs.json command and its --max-batch-size 50 option without inventing an alternative interface", + "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" ] } From 30f886278158cad70f6682dcaf7889338bf01444 Mon Sep 17 00:00:00 2001 From: Prompeteer Date: Thu, 8 Oct 2026 06:16:57 -0700 Subject: [PATCH 3/3] docs: keep prose review tool-neutral --- skills/documentation-and-adrs/SKILL.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/skills/documentation-and-adrs/SKILL.md b/skills/documentation-and-adrs/SKILL.md index 1ba9d75f..ecc28cef 100644 --- a/skills/documentation-and-adrs/SKILL.md +++ b/skills/documentation-and-adrs/SKILL.md @@ -264,8 +264,6 @@ After checking the technical content, review the prose for the people who will u 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. -If the team already uses a reviewed version of [Zero Slop](https://github.com/manavmishra/ZeroSlop/tree/43b71836bf2feb8395a84aaeea809bd7ef65e385), its source-preserving editing workflow can assist this pass. This reference pins v2.12.22; do not install or update a tool just to complete the review. Its writing score is heuristic, not proof of factual accuracy or AI authorship. A lower score does not replace the source comparison, and this step does not require sending the document to a hosted editor. - ## Common Rationalizations | Rationalization | Reality |