Run any Skill in Manus with one click

doc-quality

Stars6

Forks0

UpdatedJune 6, 2026 at 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.

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Run Skill in Manus

Source

loft-lang

loft-lang/loft

View GitHub Repository View Creator Repositories

Download

Run Skill in Manus

Related occupationsSOC

Based on SOC occupation classification

Software DevelopersComputer and Mathematical Occupations·SOC 15-1252

File Explorer

2 files

SKILL.md

readonly

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

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.

More from this repository

same repository

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.