القائمة
Use when shipping or handing off code — treat docs as a first-class deliverable: present-tense, diagrammed-as-code, verified against reality, reader-tested.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
Use when wiring a project's dev workflow (local stack, test tiers, gates, docs), or when naming make targets in a repo that has siblings — build a thin self-documenting Makefile facade over real scripts, name targets from the shared cross-repo vocabulary, and split env files by owner so targets consume them but never write them.
Use when you need to prove a feature actually delivers its intended outcome to a user or caller, not just that its code paths run — write executable acceptance tests against real, observable outcomes, derived from the spec before or independent of the implementation.
Use when adding any new capability to a working system — ship it behind a flag or optional collaborator that defaults to prior behavior.
Use when a spec, plan, or implementation must be independently reviewed before it is trusted, committed, or advanced to the next phase — dispatch a fresh reviewer per named lens whose job is to refute the artifact, not confirm it.
Use when building automation that edits, tests, or deploys itself — an agent that regenerates its own code, a self-updating pipeline, any loop that modifies the thing running it.
Use when about to call any integration, deployment, or hard guarantee "done" — prove it live end-to-end and capture the run as evidence.
استنادا إلى تصنيف SOC المهني
| name | docs-as-deliverable |
| description | Use when shipping or handing off code — treat docs as a first-class deliverable: present-tense, diagrammed-as-code, verified against reality, reader-tested. |
Documentation is a deliverable, not exhaust. Hold it to the same bar as the code: tight present-tense prose, diagrams expressed as code, every signature and flag verified against the implementation, and comprehension proven by readers — not assumed.
Apply whenever you ship code, hand a project to another team, write or revise a README/ARCHITECTURE/runbook, or change behavior that an existing doc describes. Documentation work belongs in the same change as the code it documents — not a follow-up "docs pass" that never comes.
Red-flag thoughts that mean STOP and apply this skill:
--help dump, a schema export) rather than maintained as a parallel hand-edited copy that rots. The same goes for embedded excerpts of machine artifacts — a workflow file, a config block: link the canonical file or generate the excerpt, because a hand-copied sketch drifts until it describes runners and job names that no longer exist.Docs are the interface a stranger meets before the code. If they are aspirational, unverified, or drifted, the cost is paid later and larger: a new hire burns a day on a flag that was renamed, an on-call engineer follows a runbook into an outage, a client integrates against an endpoint that no longer exists, a reviewer trusts a diagram that lies about the data flow. Verifying against source, generating tables, and binding diagram changes to code changes remove whole classes of drift at the source. Reader-testing converts "I think this is clear" into evidence that someone with no prior context can actually act — which is the only definition of clear that matters.
On the project this was distilled from — a hexagonal, human-in-the-loop AI agent deployed to a cloud runtime — the docs were rewritten as a coherent client-facing deliverable in one focused pass: present-tense, with every function signature, CLI flag, and endpoint re-checked against the live code before being written down. That same pass also deleted the development-history docs (BRIEF, DESIGN, SPECS, PAPER, ...) — the very anti-pattern this skill warns against — and the correction was a delete→restore→banner arc: the artifacts were restored, then marked as historical with a dated one-line banner pointing at the current authoritative doc, so provenance survived without anyone mistaking a stale snapshot for truth. The architecture doc gained four embedded diagrams in a single change: a context view of the whole system, a sequence diagram of the pause/resume handoff to a human, a map of which ports were backed by which adapters, and a container view; the agent-framework view additionally carried a node/edge table beside it so prose, picture, and code stayed mutually checkable. The operations runbook generated its table straight from config rather than hand-copying it — "the table below is generated from it" (docs/OPERATIONS.md). Finally, the docs were graded by context-free reader agents given only the documentation, each reading as a new developer, an SRE, an end user, and a skeptic; their comprehension failures were filed and fixed as documentation defects (recorded in the evaluation write-up). You can apply all of this without knowing that project: write present-tense and verified, embed your diagrams as code and update them with the code, generate your tables, restore-and-banner old docs rather than deleting them, and let fresh readers prove the result.
What a machine can check: drift, in every direction it happens. Docs built in CI with warnings-as-errors plus linkcheck; diagram fences proven rendered — the renderer declared in the docs dependency group, and the built output containing one rendered node per fence; generated tables regenerated in CI and diffed against the committed copy; copy-paste commands smoke-run where feasible. Reader-testing stays human — schedule it like a gate, don't simulate it with a linter.
Related skills: