一键在 Manus 中运行任何 Skill

doc-quality

星标6

分支0

更新时间2026年6月6日 05:23

Write and edit documentation in the loft repo the way it should read: code comments and doc-comments in `.rs` files, AND prose docs (`.md` — README, onboarding, reference). Use this whenever you add or revise a `///` doc comment, an inline comment, a module `//!` header, or any Markdown doc, and whenever you review the comments in a diff. It keeps comments present-tense (describe the code as it is NOW, not its history), makes a function's description about *why to use it* (not why it was written), strips dead plan-tag/date stamps while keeping live pointers to issues/plans, and keeps prose readable for entry-level and non-native-English readers. Reach for it even when the user only says "document this", "add comments", "write the docstring", "explain this function", "write up the README", or "clean up the comments" — it applies to all of those.

安装

用 Codex 或 Claude 帮你安装复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。

在 Manus 中运行

来源

loft-lang

loft-lang/loft

打开 GitHub 仓库查看创作者相关仓库

下载

在 Manus 中运行

Documentation quality

These rules are three loft goals applied to documentation. Keeping the goals in view is the point — the rules are how they show up when you write a comment:

Goal B — legible on contact: comments and the on-ramp are where a reader first meets the value. If only a senior native speaker can read them, B fails.
Goal F — serve the reader, not the author: a comment exists for whoever reads the code next, not as the author's audit trail. Provenance stamps bill the reader for the author's bookkeeping.
Goal E — the stated thing must match reality: a comment describing a deleted past is a stated model that no longer matches the code — E's exact failure mode. A stale comment hides the present code instead of revealing it.

Full reference (evidence, worked rewrites, the measurement): doc/claude/DOC_QUALITY.md. The goals themselves: doc/claude/GOALS.md §B/E/F.

When to apply

Apply these to the comment or doc you are writing or editing right now. Do not sweep a file to "fix its comments" during unrelated work — that burns effort and risks churn. The Check (below) is a thermometer you run on purpose, not a gate on every edit.

The seven rules

Describe the code as it is now, never the change. If a comment only makes sense to someone who saw the old version, it belongs in the commit message. (Goal E: the comment must match the present code.)
No plan tags, dates, or resolved-bug history in code comments — git blame keeps that. A live pointer to a doc/issue/plan that explains the code is the allowed exception (see "Stamp vs pointer"). (Goal F: serve the reader, not the author's bookkeeping.)
Keep the high-value kinds: rules the code enforces, the odd-but-needed why, cross-file coupling ("change X too"), costs/dangers, and a short module intro. These are what a reader cannot recover from the code itself.
Judge by content, not length. A 70-line module header can be right; a one-line "increment i" is wrong. There is no line limit.
A function /// description says why to use it, not why it was written — what it is for, when to use it, preconditions, trade-offs. For the design reason, link to the issue or plan you implemented it from — you are usually already reading it; do not rewrite it inline or build a new doc home for it. (Goal F.)
Inside a function, comment what the non-obvious code does — a dense or clever block (a bit twiddle, a hand-rolled search, a careful ordering) gets one line on what it achieves. You may point to the problem/issue the block handles.
Write for entry-level and non-native-English readers (code comments + any user-facing or on-ramp doc): common words over fancy ones, short one-idea sentences, no idioms or metaphors, explain a term on first use, lead with a concrete example. Plain and short — not long and simple. (Goal B.)

Two layers, and the prose exception

Function /// description → rule 5: why to use it.
Inline body comment → rule 6: what the non-obvious code does.
Prose docs (.md) → rule 7 (plain language) always applies to user-facing and on-ramp docs. But rules 1–2 are softer here: a changelog, a plan, or GOALS.md legitimately carries dates and plan refs. The stamp ban is a code rule. Maintainer-facing design docs may use denser, project-specific language; do not let that creep into the user-facing surface.

Stamp vs pointer (the one distinction to get right)

Dead stamp — remove it: @PLAN12 phase 3.5a (2026-05-24) — …, a bare prefix recording which plan and when, with nothing to open. Following it tells you only when the line was written.
Live pointer — keep it: a link to a doc, issue, or plan that explains why the code is needed (see LIFETIME.md § locked-store text for why). Following it teaches you about the present code. It counts even if the plan/issue is closed — a finished investigation still explains. Prefer a stable target (an issue URL, or a ref ./scripts/idx resolves) over a raw plan path.

The loft tracker tags (CLAUDE.md § "Tracker tags") belong in plans, design docs, and commit messages — where ./scripts/idx resolves them — not in a .rs comment. The comment carries a link to the tagged plan, not the tag.

Worked example

// BEFORE — the description explains why the function was WRITTEN, under a stamp
/// @PLAN52 (2026-05-30): added during the closure-capture rework to fix the
/// "Write to locked store" panic; re-types text captures. Mirrors
/// flip_scalars_to_box_types.
fn box_captured_names_for_outer_scalars(…) { … }

// AFTER — why to USE it (present tense), design reason as a live pointer
/// Re-types a lambda's captured outer scalars to their cell form so the closure
/// record can hold them by reference. Call after capture analysis, before
/// emitting the closure record. Skips text captures when the parent returns
/// text — see LIFETIME.md § locked-store text for why.
fn box_captured_names_for_outer_scalars(…) { … }

Check (advisory)

A runnable detector backs this standard — progress is evaluated, not asserted (GOALS.md). It is a thermometer; it never fails CI and never edits.

scripts/lint_comments.sh            # full report + biggest offenders
scripts/lint_comments.sh -c         # counts only (the thermometer)
scripts/lint_comments.sh top        # files ranked by flagged count (cleanup)

For adopting on the existing tree without a big-bang cleanup, use the baseline ratchet (accept today's flags, block only new ones, shrink over time):

scripts/lint_comments.sh --baseline   # accept today's flagged lines
scripts/lint_comments.sh --check       # list only NEW flags (CI advisory)
scripts/lint_comments.sh --prune        # after a cleanup pass: drop fixed lines

A flagged #NNN or doc pointer that explains the code is a keeper — only bare plan/date stamps and change-narration should go. The full workflow is in DOC_QUALITY.md § Check.

同仓库更多 Skills

同仓库

draw

loft-lang/loft

Make a considered image or 3D scene from a described intent the iterative-craft way — block in, render, measure, critique against the intent, refine across passes — instead of trying to emit a finished result in one shot. Use this whenever the user wants to DRAW, sketch, illustrate, depict, compose, or paint a 2D picture, OR model / build / lay out a 3D scene, asset, or environment (e.g. a game prop, a room, a character, a landscape), ESPECIALLY when they give a subject, a mood, or a composition to hit ("an old woman at dusk", "a cosy tavern interior", "a low-poly pine tree", "make it feel ominous"). Also use when iterating on or critiquing such an image/scene. Reach for it even if the user doesn't say "iteratively" — the loop is the point, and one-shot guessing is what it replaces. Do NOT use for text-to-image prompts handed to a diffusion model, for charts / plots / diagrams / dashboards (data visualisation), or for UI / web layout.

2026-07-246

loft-write

loft-lang/loft

Reference for writing correct loft code. Apply whenever writing, editing, or reviewing .loft files. Covers types, syntax, known bugs, workarounds, naming rules, and error→fix table.

2026-07-246

loft-plan-workflow

loft-lang/loft

Procedures for plan-shaped work — opening a plan, closing/deferring one, promoting a doc to a plan, choosing the lightest workflow, applying value categories. Apply when the task involves plans, plan directories, a roadmap, or doc-to-plan promotion. The method is tree-agnostic; the concrete paths/templates/tracker that bind it to this repo live in one § at the bottom. Cites source docs for definitions; does not restate.

2026-07-236

engineering-rigor

loft-lang/loft

The shared discipline for any non-trivial change — fixing a bug OR designing/refactoring a load-bearing algorithm. USE THIS when about to fix a non-trivial bug (crash, silent corruption, wrong result), design or refactor a load-bearing algorithm (core representation, runtime, memory, codegen, a public contract or data format), when a change feels fragile or "longer than expected for what it does", or when reaching for an approximation in an exact-invariant domain (geometry, caching, hashing, round-trips) and can't pin the exact construction — ESPECIALLY when a fix already looks obvious (that's the cue, not the exception). It is a SPEED tool, not a brake: a coherent explanation is a hypothesis, not a conclusion, and the fastest route to a fix that sticks is the cheapest probe that could prove your idea wrong (a timing, a grep of a count, one --emit-and-look — seconds). So the moment you can state a cause or a fix, that fluency is the cue to GATHER first, not act — which also lets you fix the SOURCE and delete

2026-07-146

design-protocol

loft-lang/loft

Design Protocol 1 — a design is a testable HYPOTHESIS about an invariant, not a plan you execute. The DESIGN-mode counterpart to the engineering-rigor skill (which routes here for the design half). USE THIS whenever you are about to commit to a load-bearing design — a core representation, runtime, memory model, codegen, a public contract, a data format, or any algorithm that will carry weight: name the ONE invariant, count its re-assertion sites, build the cheapest probe that could FALSIFY each load-bearing claim, then build and validate against the written prediction. And for exact-invariant domains where you cannot even form the invariant (geometry, caching, hashing, store/memory lifetime, round-trips), flip to the constructive instrument — plot a concrete instance of the ANSWER and read the invariant off it. Reach for it when a design feels too clean, when you keep reaching for an approximation, or whenever you catch yourself about to build the first coherent design without probing it.

2026-07-076

loft-ship

loft-lang/loft

Write, bridge, verify, and publish a loft library so it behaves IDENTICALLY on all four targets — the interpreter, --native, --native-wasm, and --html (browser). Use this skill whenever the user is creating, packaging, cross-compiling, or publishing a loft library or package; mentions loft.toml, the target matrix, a wasm bridge, `loft new` / `loft install`, the registry, the sha256/signature, or making a library "work in the browser" / "work in wasm"; or is debugging native-vs-wasm-vs-interpret divergence in a library. Trigger it even when the user doesn't say "all four platforms" — any loft library that has to ship beyond the interpreter belongs here, because the cross-target parity gate and the wasm-bridge pitfalls are exactly where this work silently goes wrong.

2026-07-046

name	doc-quality
description	Write and edit documentation in the loft repo the way it should read: code comments and doc-comments in `.rs` files, AND prose docs (`.md` — README, onboarding, reference). Use this whenever you add or revise a `///` doc comment, an inline comment, a module `//!` header, or any Markdown doc, and whenever you review the comments in a diff. It keeps comments present-tense (describe the code as it is NOW, not its history), makes a function's description about why to use it (not why it was written), strips dead plan-tag/date stamps while keeping live pointers to issues/plans, and keeps prose readable for entry-level and non-native-English readers. Reach for it even when the user only says "document this", "add comments", "write the docstring", "explain this function", "write up the README", or "clean up the comments" — it applies to all of those.
user-invocable	false

Documentation quality

These rules are three loft goals applied to documentation. Keeping the goals in view is the point — the rules are how they show up when you write a comment:

Goal B — legible on contact: comments and the on-ramp are where a reader first meets the value. If only a senior native speaker can read them, B fails.
Goal F — serve the reader, not the author: a comment exists for whoever reads the code next, not as the author's audit trail. Provenance stamps bill the reader for the author's bookkeeping.
Goal E — the stated thing must match reality: a comment describing a deleted past is a stated model that no longer matches the code — E's exact failure mode. A stale comment hides the present code instead of revealing it.

Full reference (evidence, worked rewrites, the measurement): doc/claude/DOC_QUALITY.md. The goals themselves: doc/claude/GOALS.md §B/E/F.

When to apply

The seven rules

Describe the code as it is now, never the change. If a comment only makes sense to someone who saw the old version, it belongs in the commit message. (Goal E: the comment must match the present code.)
No plan tags, dates, or resolved-bug history in code comments — git blame keeps that. A live pointer to a doc/issue/plan that explains the code is the allowed exception (see "Stamp vs pointer"). (Goal F: serve the reader, not the author's bookkeeping.)
Keep the high-value kinds: rules the code enforces, the odd-but-needed why, cross-file coupling ("change X too"), costs/dangers, and a short module intro. These are what a reader cannot recover from the code itself.
Judge by content, not length. A 70-line module header can be right; a one-line "increment i" is wrong. There is no line limit.
A function /// description says why to use it, not why it was written — what it is for, when to use it, preconditions, trade-offs. For the design reason, link to the issue or plan you implemented it from — you are usually already reading it; do not rewrite it inline or build a new doc home for it. (Goal F.)
Inside a function, comment what the non-obvious code does — a dense or clever block (a bit twiddle, a hand-rolled search, a careful ordering) gets one line on what it achieves. You may point to the problem/issue the block handles.
Write for entry-level and non-native-English readers (code comments + any user-facing or on-ramp doc): common words over fancy ones, short one-idea sentences, no idioms or metaphors, explain a term on first use, lead with a concrete example. Plain and short — not long and simple. (Goal B.)

Two layers, and the prose exception

Function /// description → rule 5: why to use it.
Inline body comment → rule 6: what the non-obvious code does.
Prose docs (.md) → rule 7 (plain language) always applies to user-facing and on-ramp docs. But rules 1–2 are softer here: a changelog, a plan, or GOALS.md legitimately carries dates and plan refs. The stamp ban is a code rule. Maintainer-facing design docs may use denser, project-specific language; do not let that creep into the user-facing surface.

Stamp vs pointer (the one distinction to get right)

Dead stamp — remove it: @PLAN12 phase 3.5a (2026-05-24) — …, a bare prefix recording which plan and when, with nothing to open. Following it tells you only when the line was written.
Live pointer — keep it: a link to a doc, issue, or plan that explains why the code is needed (see LIFETIME.md § locked-store text for why). Following it teaches you about the present code. It counts even if the plan/issue is closed — a finished investigation still explains. Prefer a stable target (an issue URL, or a ref ./scripts/idx resolves) over a raw plan path.

Worked example

// BEFORE — the description explains why the function was WRITTEN, under a stamp
/// @PLAN52 (2026-05-30): added during the closure-capture rework to fix the
/// "Write to locked store" panic; re-types text captures. Mirrors
/// flip_scalars_to_box_types.
fn box_captured_names_for_outer_scalars(…) { … }

// AFTER — why to USE it (present tense), design reason as a live pointer
/// Re-types a lambda's captured outer scalars to their cell form so the closure
/// record can hold them by reference. Call after capture analysis, before
/// emitting the closure record. Skips text captures when the parent returns
/// text — see LIFETIME.md § locked-store text for why.
fn box_captured_names_for_outer_scalars(…) { … }

Check (advisory)

A runnable detector backs this standard — progress is evaluated, not asserted (GOALS.md). It is a thermometer; it never fails CI and never edits.

scripts/lint_comments.sh            # full report + biggest offenders
scripts/lint_comments.sh -c         # counts only (the thermometer)
scripts/lint_comments.sh top        # files ranked by flagged count (cleanup)

For adopting on the existing tree without a big-bang cleanup, use the baseline ratchet (accept today's flags, block only new ones, shrink over time):

scripts/lint_comments.sh --baseline   # accept today's flagged lines
scripts/lint_comments.sh --check       # list only NEW flags (CI advisory)
scripts/lint_comments.sh --prune        # after a cleanup pass: drop fixed lines

A flagged #NNN or doc pointer that explains the code is a keeper — only bare plan/date stamps and change-narration should go. The full workflow is in DOC_QUALITY.md § Check.