Revise the Code comments standard: wayfinding and headers stay, provenance goes

[mcarter-astronautdev]

Maria reverted part of Avara's #215 comment trim and wants the house standard to match what she kept: wayfinding and guidebook comments stay, provenance (Figma frames, tickets, dates, who decided) goes. Avara PR #229 applies the revision to frontend/; her own Liquid-side revert is Avara commit 79d5701. Replace the Code comments bullet in templates/github/claude-standards.md with the text below, then:

• reword claude.yml's --append-system-prompt item (7), which carries a copy of the old bullet (no apostrophes in that string);
• wave the file to the fleet.

Proposed replacement:

Code comments — Code should be self-describing; comments are written as one senior engineer to another. Comments do two jobs. Guidebook comments say what a file or block is, where it is used, how it works and what it is bound to; they are encouraged when they are clear, concise and make the code easier to understand. Provenance comments say which Figma frame, which ticket, which date, who decided; they do not belong in code.

• Wayfinding stays. A one-line label naming a region or element ({% comment %} Products {% endcomment %}, <!-- True Fit Integration -->, /* Mobile */), a bare Driver or Avara tag on a block we own inside a vendor file, Start/End markers around a third-party script, and the dashed CSS / LIQUID / JAVASCRIPT banners between a file's parts. These may restate the code; that is their job. Drop one only when it repeats the header's words for the same region.
• Headers are guidebooks. Every section and non-trivial file opens with a header that explains it at the top, so nobody reads 250 lines to find out: what it renders and where it is used; how it works when that is not obvious; the metaobjects and metafields that feed it; the file on the other side of a binding (the Liquid a component mounts into, the JS a snippet depends on); one line per param. Length follows the file's complexity. An existing header is kept whole, not compressed or reworded; only provenance lines come out of it. A file with no header gets one.
• Explanation earns its lines. Only for non-obvious code: a coupling, an ordering or timing constraint, a cascade trick, behaviour the code does not show, a unit gloss like /* 11px */. Default two to three full sentences. Compress freely, but the rewrite keeps the vendor or component as its subject, both ends of a coupling (what writes a value and what reads it), and every step of a trade-off, never a slogan in its place, and it never absorbs a neighbouring label. Concrete examples and secondary file pointers may go. No requirements, decisions, tickets, QA rounds, dates or Figma nodes. Do not reword a comment that is already within budget.
• Vendor code keeps its comments. Third-party-authored code (Prestige, Monk, Tolstoy, Narvar, Swym, app embeds) stays as the vendor wrote it, junior comments included, so it remains diffable against the source.
• Disabled code is a code call. Commented-out markup, debug blocks and their stamp or reason line stay until a code change removes them.
• Say it once, one way. History and cross-cutting context live in CLAUDE.md. A mechanism's explanation lives at the code that implements it and is never replaced by a CLAUDE.md pointer. Within a file, a repeated rationale goes.

from: Avara, PR #229

[mcarter-astronautdev]

Part 1 shipped in #71 and waved 2026-10-01: the Code comments bullet in templates/github/claude-standards.md is the revised rule, written generically (client, app, Figma) and shorter than the proposal; every repo carrying the file has it. Part 2 (reword claude.yml's --append-system-prompt item (7), no apostrophes, then release and repin) rides with the next reusable change — noted in docs/HANDOFF.md next steps. Leaving this open for part 2.

[mcarter-astronautdev]

Part 2 shipped in #74 and released as v1.18.0 (waved 2026-10-01): the implementer prompt item (7) is a tight, apostrophe-free summary of the revised standard. Both halves done.