cookbook-doc-review ยท diff
git:20260901.be06beb to git:20260901.0bb6ca7
124 added, 92 removed. Audit A to A.
---
name: cookbook-doc-review
description: >-
- Review AGS Cookbook documentation from an external AGS user's perspective.
- Use before handing off changes to public READMEs, tutorials, reference
- guides, or example documentation anywhere in this repository. Do not use
- for source-code review or explicit contributor/governance documents.
+ Review AGS Cookbook documentation for language, wording, logic, and Markdown
+ layout from an external AGS user's perspective. Use before handing off
+ changes to public READMEs, tutorials, reference guides, or example
+ documentation anywhere in this repository. Do not use for source-code review
+ or explicit contributor/governance documents.
---
# Review AGS Cookbook Documentation
Review only. Do not edit files during the review pass.
## Review Independence
- For a final handoff review, use a fresh reviewer context when delegation is
- available. Give the reviewer the repository path, diff boundary, and user's
- documentation requirement, but not the implementer's intended verdict,
- suspected findings, or proposed rewrite. If a fresh reviewer is unavailable,
- state that limitation with the result.
+ For a final review, use a fresh reviewer context when delegation is available.
+ Provide the documentation paths, diff boundary, and user's documentation goal,
+ but not the implementer's intended verdict, suspected findings, proposed
+ rewrite, or implementation evidence. If a fresh reviewer is unavailable, state
+ that limitation.
- ## Audience Contract
+ ## Core Question
- Treat the repository's public cookbook surface as documentation for people who
- want to use AGS. The reader is not expected to maintain this repository,
- publish its official artifacts, know its review history, or understand why a
- maintainer chose a particular implementation.
+ Can a user who has only the public documentation understand the goal, prepare
+ the prerequisites, run the steps, recognize success or failure, recover from
+ common problems, and clean up without asking a repository maintainer or
+ inspecting any other repository file?
- This applies to every public example document: CLI and SDK walkthroughs,
- Sandbox workflows, storage and networking guides, browser or mobile examples,
- custom-image instructions, Deployment tutorials, API references, and files
- under `dockerfiles/` or `skills/`. Specialized guides may contain technical
- detail, but they must not turn into instructions for maintaining the
- repository's namespaces, official artifacts, release process, lockfiles,
- labels, or READMEs.
+ Every review decision should help answer this question.
+ ## Audience
+
+ Review every public cookbook document as material for people who want to use
+ AGS. Readers are not expected to maintain this repository, publish its official
+ artifacts, know its review history, or understand internal implementation
+ decisions.
+
+ This applies to CLI and SDK walkthroughs, Sandbox workflows, storage and
+ networking guides, browser and mobile examples, custom-image instructions,
+ Deployment tutorials, API references, and user-facing files under
+ `dockerfiles/` or `skills/`.
+
Explicit contributor and agent-governance files such as `CONTRIBUTING.md`,
`AGENTS.md`, and `docs/agents/` are outside this skill.
- ## Review Boundary
+ ## Review Scope
- Review the changed documentation and the shortest linked path a reader needs
- to complete the task. Use the repository files, commands, configuration, and
- observed behavior as evidence. Do not accept implementation notes or prior
- review conclusions as proof that a reader-facing claim is useful or correct.
+ Treat the documentation as a black box. Read the changed document in full and
+ follow only the public documentation links that the reader must follow to
+ complete the task. Review both the English and translated versions when both
+ exist.
- Identify the subject before applying domain rules. Check CLI behavior against
- the relevant CLI contract, SDK behavior against the SDK boundary, and cloud
- resource behavior against the corresponding API and lifecycle. Do not carry a
- constraint from one cookbook into an unrelated example.
+ Do not inspect source code, tests, scripts, Dockerfiles, lockfiles, CI, issues,
+ pull requests, commits, internal notes, implementation logs, or unrelated
+ repository files. Do not fill a documentation gap from prior product knowledge.
+ If the reader needs information that the reviewed documentation does not
+ provide, report the gap instead of researching the answer elsewhere.
- If the requested base or diff boundary is not given, inspect the current
- documentation changes without widening the review to unrelated files.
+ Use four primary review axes.
- ## Reader Test
+ ### 1. Language
- Read the documentation in order as a new AGS user and check:
+ - English reads as natural technical English, not a literal translation or an
+ internal engineering report.
+ - Chinese reads as natural technical Chinese, not word-for-word English with
+ unnecessary mixed-language filler.
+ - Grammar, punctuation, tense, person, capitalization, and singular/plural use
+ are consistent.
+ - Terms are introduced before use and remain consistent across headings,
+ prose, commands, and translations.
+ - Proper nouns, commands, flags, API fields, headers, versions, and protocol
+ names stay exact.
+ - English is canonical, while Chinese preserves meaning rather than sentence
+ structure.
- 1. **Purpose and entry point**
- - The opening says what the example does and when to use it.
- - Required work is separated from optional inspection, rebuilding, and
- troubleshooting.
+ ### 2. Wording
- 2. **Runnable path**
- - Prerequisites, credentials, permissions, variables, commands, expected
- results, failure recovery, and cleanup are present where needed.
- - Placeholders tell the reader what to replace.
- - Commands target accounts, resources, paths, and artifact destinations the
- reader controls. For example, image publishing uses the reader's registry
- namespace, never the repository's official namespace.
+ - Sentences are direct, concise, and specific about what the reader should do
+ or expect.
+ - Remove filler, repetition, inflated claims, stacked caveats, and details that
+ do not change a user decision.
+ - Avoid AI- or review-report phrasing such as "this proves", "authoritative
+ path", "supported assertion", "comprehensive", or ritual conclusions.
+ - Distinguish requirements, recommendations, optional diagnostics, examples,
+ and observed results without legalistic or contract-heavy prose.
+ - Do not address readers as repository maintainers. Build or publishing guides
+ target resources the reader owns rather than the repository's official
+ namespaces and release workflow.
+ - Preserve necessary warnings, security boundaries, and compatibility limits;
+ simplify their expression instead of deleting them for style.
- 3. **User-relevant detail**
- - Keep implementation detail only when it changes a user action, expected
- behavior, security boundary, compatibility limit, or troubleshooting
- decision.
- - Remove repository-maintenance chores, investigation narratives, internal
- acceptance language, release bookkeeping, and legal or architectural
- reasoning that the evidence does not support.
- - Do not make readers understand repository revisions, internal validation
- history, artifact provenance, or implementation structure unless they
- must act on that detail.
+ ### 3. Logic
- 4. **Plain language**
- - Prefer direct instructions and concrete expected results.
- - Avoid report-like phrases such as "this proves", "authoritative path",
- "supported assertion", or repeated contract disclaimers.
- - Introduce necessary domain terms in context. Preserve exact command, API,
- header, resource, SDK, and protocol names.
+ - The document moves in the order a reader acts: purpose, prerequisites,
+ setup, execution, expected result, recovery, and cleanup where applicable.
+ - A step does not depend on an undefined term, missing value, hidden command,
+ or later explanation.
+ - The document itself supplies every instruction and decision needed after the
+ stated prerequisites; it does not rely on repository knowledge the reader
+ cannot see.
+ - Paragraphs have one clear job. Headings and transitions make the relationship
+ between sections obvious.
+ - Required and optional paths do not interrupt or contradict each other.
+ - Causes and consequences are stated accurately; observed behavior is not
+ promoted into a platform guarantee.
+ - Repeated explanations are consolidated, and cross-references replace
+ unnecessary duplication.
+ - English and Chinese describe the same sequence, conditions, and outcome.
- 5. **Truth and safety**
- - Separate required behavior from optional diagnostics and observed results
- from platform guarantees.
- - Check claims about identity, lifecycle, persistence, concurrency,
- recovery, compatibility, networking, permissions, and billing against the
- contract for the feature being documented. Do not generalize from one
- successful run.
- - Do not expose secrets or encourage tokens in files, command arguments, or
- logs. Cleanup must cover chargeable or long-lived resources created by the
- walkthrough.
+ ### 4. Layout
- 6. **Bilingual consistency**
- - English is canonical; Chinese preserves the same behavior and scope.
- - Shell, JSON, configuration, resource names, versions, image references,
- and expected machine output match across languages.
- - Relative links resolve from each document.
+ - Heading levels reflect the actual hierarchy and make the main path easy to
+ scan.
+ - Paragraphs are short enough to read comfortably; lists are used for genuine
+ sets or sequences, not to fragment ordinary prose.
+ - Tables are used for comparisons or repeated fields, not as decoration.
+ - Commands, configuration, expected output, and explanations stay adjacent.
+ - Code fences, list indentation, blank lines, links, and inline code follow
+ valid Markdown and render cleanly.
+ - Long commands remain copyable. Placeholders are visually clear and explained
+ before execution.
+ - English and translated documents keep matching code, configuration, resource
+ names, image references, and machine output.
- ## Findings Standard
+ ## Documentation-Only Guardrail
- Report a finding only when it has a concrete reader impact. For each finding,
- include:
+ This skill reviews documentation quality and sufficiency, not implementation
+ correctness. Check internal consistency, command continuity, security guidance,
+ and whether the documented result follows from the documented steps. Do not use
+ implementation evidence to rescue unclear or incomplete prose.
+ Preserve necessary secret-handling, permission, lifecycle, compatibility, and
+ cleanup guidance. If a factual claim cannot be assessed from the documentation
+ alone, record it as an unverified residual risk rather than researching other
+ files.
+
+ ## Findings
+
+ Report only concrete reader-facing problems. For each finding include:
+
+ - axis: `Language`, `Wording`, `Logic`, or `Layout`;
- severity and confidence;
- file and line;
- - the reader action or moment that triggers the problem;
- - the likely misunderstanding, failure, or unsafe action;
- - repository evidence;
- - the smallest useful fix.
+ - the problematic text or structure;
+ - how it confuses, slows, misleads, or blocks the reader;
+ - the missing or conflicting information visible from the documentation;
+ - the smallest useful correction direction.
- Do not report vague preferences, generic style advice, or maintenance concerns
- that do not affect an AGS user.
+ One finding may name a secondary axis, but choose one primary axis. Do not
+ report vague preferences, generic style advice, or differences that are merely
+ personal taste.
## Output
Return:
1. `Verdict: PASS` or `Verdict: FAIL`.
- 2. Findings ordered by severity. Write `No findings` when applicable.
- 3. A short reader-journey assessment covering discovery, execution,
- verification, recovery, and cleanup.
- 4. Residual risks or unverified external behavior, if any.
+ 2. A one-line assessment for each axis: Language, Wording, Logic, and Layout.
+ 3. Findings ordered by severity. Write `No findings` when applicable.
+ 4. Claims that remain unverifiable from the documentation alone, if any.
- Use `FAIL` when a material user-facing problem remains or the documented claim
- cannot be supported by available evidence. Use `PASS` only when the reviewed
- reader path is usable without repository-maintainer knowledge.
+ Use `FAIL` when a material issue remains in any primary axis or when an edit
+ would make the documentation factually unsafe. Use `PASS` only when the
+ reviewed path is natural, concise, logically ordered, scannable, and usable
+ from the documentation alone.