How to write source comments, doc comments, and test names/tags that have lasting value — and what to never write. Consult before adding or editing comments in core/**, examples/**, tools/**, test/**, docs/**, or any shipped source. Handles "write a comment", "is this comment ok", "comment hygiene", and keeping new code from adding the breadcrumbs the cleanup stream removes.
The English summary is being prepared. Showing the original description.
See how to installReview the instructions the agent will receive before you install.
A comment earns its place by explaining something the code cannot say for
itself and that will still be true next year: current behavior, an invariant, a
non-obvious "why", an upstream/vendor/host quirk, a security or compat
constraint, a regression- or RT-safety guard. It must not encode how the code
got here — that provenance belongs in the commit message, planning/,
docs/reports/, the changelog, or a commit trailer. This repo will be
open-sourced; every comment is read by strangers with no access to our issue
tracker or session history.
This skill exists so new code stops adding the exact provenance the repo-wide
cleanup is removing. The cleanup backlog + classification rules are parked at
planning/2026-07-02-comment-hygiene-PAUSED.md.
(Phase 4), Phase N will…,
4f-style sub-phase labels, Tier A Slice 7, Feature 3, plan item 7.2,
item 6.12 follow-up. [phaseN] / [phase3-large] Catch2 tags are forbidden.
Capital-letter+digit plan tags (C2, D6, M1) are the same kind of
breadcrumb — the lint can't safely match them (they collide with MIDI note
names and register labels), so it's on you to keep them out of comments.Codex P1/P2/P0, codex review,
[codex-*], "per the reviewer", "sub-PR", "slice N of".[coverage], [codecov], [requested]
selector tags; no "added for coverage".Reference-Lineage: independent … commit trailer, never
in a source comment. Describe the DAW/host behavior, not how you derived it.#1234 as the explanation. A PR/issue number is not a reason. If the
issue explains a still-live invariant, state the invariant; a durable
[issue-NNN] anchor on a regression test is fine (note: # is reserved in
Catch2 tags — use [issue-NNN]).Future v2 license-key payloads (post-RSA migration) bullet that was already inaccurate — current
crypto is AES-256-GCM.)WIP / "temporary" / "hack for now". Either it's the behavior (describe
it) or it's a tracked task (put it in planning/).CMAKE_BUILD_TYPE paragraph in a
test that no longer checks a build-type field).Provenance that encodes a stable fact gets restated as current behavior, stripped of the phase/PR wrapper. Real before → after cases from the cleanup:
| Before (process provenance) | After (durable behavior) |
|---|---|
Phase 4d adds feedback | feedback needs a previous-block slot |
pulp_build_info.hpp (Tier A Slice 7) | Build info |
test header macOS plan item 7.2 / 7.1b | header describing the current coverage |
| MPE header naming a phase | "describes UMP status handling and shared factories" |
| raw-MIDI sysex case naming a PR | "describes aborted-sysex recovery" |
# in Catch2 tags (reserved). Use [issue-NNN] for a durable regression
anchor, and behavioral tags for what the test covers: [rt-safety],
[parity], [thread]. Never [phaseN], [codecov], [coverage],
[requested], [codex-*], "which session shipped it".TEST_CASE name states what is verified, not when/why-in-the-project it was
added.Scan your own diff for the breadcrumbs above — cheaper than a cleanup PR later:
# stale provenance in ADDED lines of the staged/working diff
git diff --cached -U0 | rg '^\+' | \
rg -n -iE '\b(phase\s?[0-9]|slice [0-9]|tier [a-z] slice|plan item|sub-?pr|codex (p[012]|review)|\[(phase[0-9a-z-]*|codecov|coverage|requested|codex[a-z0-9-]*)\]|future v[0-9]|WIP|clean-?room)\b' \
&& echo "↑ reconsider these — see the code-comments skill" || echo "clean"
# repo-wide evergreen-scope lint (docs/reference/** + skills)
python3 tools/scripts/docs_noise_lint.py --mode=report
Enforcement today: docs_noise_lint.py covers docs/reference/** and
.agents/skills/**/SKILL.md (diff-scoped in CI + pre-push). Source-comment
enforcement is the author's responsibility until the lint's source scope lands —
so run the rg self-check above on any source diff that adds comments.
Write the comment as a present-tense statement of what the code does, why it's
non-obvious, or what external constraint it honors. The narrative of how it was
built goes in the commit and planning/.
No reviews yet. Tell others what you thought.
No login needed. Share how it worked for you, ask a question, or note where it did not run.
No comments yet. Be the first to write one.
Optional AAX support for Pulp, including developer-supplied Avid SDK setup, CMake enablement, DigiShell/AAX Validator workflows, and local AAX builds on macOS or Windows.
The English summary is being prepared. Showing the original description.
Configure, implement, and test Pulp's optional desktop Ableton Link tempo-sync adapter while preserving the developer-supplied SDK, licensing, realtime, latency-compensation, and no-install boundaries.
The English summary is being prepared. Showing the original description.
Maintain Pulp's installed design-time agent capability manifest and public-surface ledger. Use when adding, removing, renaming, or materially changing public audio, MIDI, signal, timebase, or sequence APIs; registering a new algorithm for generators; changing capability support or deprecation state; or repairing agent-capabilities freshness, schema, fingerprint, tombstone, or installed-SDK tests.
The English summary is being prepared. Showing the original description.
Android platform development for Pulp — NDK cross-compilation, Oboe audio, Dawn/Skia GPU rendering, JNI bridge, touch interaction, emulator workflows, and end-to-end smoke validation. Covers build, deploy, debug, and the gotchas discovered during bringup.
The English summary is being prepared. Showing the original description.
Optional ARA support for Pulp, including developer-supplied ARA SDK setup, CMake enablement, adapter companion APIs, validation, and ARA-aware plugin implementation guidance.
The English summary is being prepared. Showing the original description.
The measurement surface for ALL Pulp DSP and audio-pipeline work — read it BEFORE writing or gating DSP, not only when something already sounds wrong. Covers the C++ harness (signal generators, metrics, assertions, RenderScenario, contracts), the offline Audio Doctor (magnitude/frequency response, THD/THD+N, phase/group delay), and their Python sibling the Audio Quality Lab (tools/audio/quality-lab — null residual + alignment, LTAS log-spectral distance, spectral flux/centroid, HNR, Theil-Sen drift slope, Kaiser-sinc resampling, license-guarded corpus, regression-net ratchet). TRIGGER on AUTHORING work — "build/design an oscillator/filter/synth/effect", "add a DSP module", "what should the acceptance gate be", "how do I measure aliasing / anti-aliasing / alias floor", "null against a reference", "is this DSP correct", "choose a tolerance", "golden/regression corpus for audio", "measure drift or jitter", "A/B two renders" — AND on DEBUGGING work — "is there sound / no audio / I hear nothing", "does this filter/compressor/synth/delay produce the right signal", "prove the DSP / prove the contract", "measure the frequency response", "what's the THD / is it distorting", "what's the group delay / phase response / measured latency", "magnitude response curve", "render a test tone and assert", "audio regression", "64-frame works but 128 is silent", "sample-rate change pitch-shifted it", "describe what's in this buffer", "audio doctor", "compare before/after a DSP refactor". Reach for this BEFORE hand-rolling any FFT, null test, alias measurement, pitch tracker, or golden-render script — most of it already exists in one of the two lanes. Test/tool layer over HeadlessHost — deterministic, no audio device, no speakers. Off the realtime thread entirely.
The English summary is being prepared. Showing the original description.