Comment policy (FR-22 write-time carrier)

Style: Mode-B-lite. The write-time home of FR-22. Loads for code-writing agents (and their sub-agents) so the rule reaches the writer's context at the moment comments are written — not just at review. Rule body aligns with FR-22 in FLOW_RULES.md; rationale + evidence live in docs/comment-policy.md.

Purpose

Flow source is read by AI agents, not humans line-by-line. WHAT-restating prose, rationale already homed in a decision/ticket/memory, and changelog comments serve an absent audience and cost context budget on every load. The base "match surrounding comment density" instruction is a one-directional ratchet and every Stop-hook gate is comment-blind, so over-commenting is invisible to the loop. This skill delivers the explicit override at write time.

When to invoke

• Writing or editing code in any language.
• Adding, changing, or reviewing your own comments before a commit.
• About to commit a code diff (final comment pass).
• A handoff or task involves implementation, refactor, or scaffold.

Do not invoke when

• Editing prose / docs / specs / decisions / handoffs (these are human-or-AI-read narrative, not code).
• The ticket is non-code (config-only rename, doc-only change with no source edit).
• You want review-time enforcement — that is code-review (the review dimension), not this write-time carrier.

Required inputs

Procedure

For comments introduced or necessarily changed by this task, write only two kinds; remove everything else. Pre-existing comments you did not need to touch stay as they are (flow-skills/zoom-out/references/karpathy-guidelines.md §3); cleaning them is the separate pass in § Escalation path.

1. Tripwire (keep)

A constraint an editing agent could violate without realizing, that is not obvious from local code. One line by default; ≤~4 lines only for security / auth / concurrency / platform-quirk.

# empirical floor — don't lower below 0.82 (decision B2)
threshold = 0.82

# additive — reordering breaks back-compat with serialized v1 payloads
FIELDS = (...)

2. Retrieval pointer (keep)

A ≤1-line tag naming the external WHY-home so an agent whose context is just the open file knows where the rationale lives.

COOLDOWN_S = 30        # (backlog 156)

3. Remove (everything else)

Worked example

Task T42 edits one retry loop in comment-heavy sync.ts.

• New constant MAX_RETRIES = 5 gets a tripwire: # upstream rate limit — keep ≤5 (decision B4).
• A draft # retry the job the task wrote inside the loop restates WHAT → removed before commit.
• The loop's pre-existing # loop over jobs is not changed by the edit → left untouched; mention it for a separate Lightweight cleanup pass.
• The touched line's (backlog 156) pointer stays.

Output: comment-policy review: applied (FR-22).

Delegation push block (for code-writing sub-agents)

When you delegate any code-writing/implementation slice to a sub-agent, paste this block into its prompt (push — sub-agents do not reliably auto-load this skill):

COMMENT POLICY (FR-22) — applies to all code you write:
In comments you introduce or necessarily change, write ONLY two kinds; remove everything else. Leave untouched pre-existing comments alone.
1) TRIPWIRE — a constraint an editor could break unknowingly, not obvious from local code (≤1 line; ≤4 lines only for security/auth/concurrency/platform).
2) RETRIEVAL POINTER — a ≤1-line tag naming the external WHY-home, e.g. "(decision B2)" or "backlog 156".
REMOVE: comments that restate what the code does; rationale already recorded in a decision/ticket/memory; changelog/history (it's in git).
Do NOT match surrounding comment density upward. Keep pointers — they are not duplicates.

Two subtleties (do not over-simplify)

• Do NOT "match surrounding comment density" upward. Comments this task introduces or necessarily changes follow this policy even in comment-heavy files — the FR-22 exception to "Match existing style" in flow-skills/zoom-out/references/karpathy-guidelines.md §3. This clause is what breaks the harness density-ratchet — without it the policy is silently overridden.
• Storage ≠ retrieval — the pointer is NOT a duplicate. When an agent opens a file the external records aren't in its context, so deleting the one-line pointer orphans a correct record the agent now has no trigger to open. Kill the prose; keep the pointer.

Content gate forbidden — artifact-level checks encouraged

Two distinct enforcement layers; do not conflate them (conflating them led maintainers to build nothing):

The "no gate" rule is about comment content only. It does not forbid the safe artifact-level checks that make FR-22 delivered-by-construction and visible to the loop.

Carve-out (trust-critical paths)

Trust-critical paths — auth / identity / session / gate code, DB migrations, and anything in policies/comment-policy.yml: trust_critical_globs — keep their multi-line tripwires. Apply the rule fully to CRUD / routine code. The set is project-settable (architecture-dependent: whether a separate instruction layer is read instead of source varies by project). Run references/audit-prompt.md against a project to derive its set before adopting.

Output artifacts

Failure cases

Escalation path

• Carve-out set unknown for this project → run references/audit-prompt.md; ask the operator in chat text (FR-19) which globs to set in policies/comment-policy.yml.
• Cleaning existing over-commented files → a separate explicit Lightweight pass (FR-21); not retroactive, comments strip from build output so no deploy.

Anti-patterns

• Do not become a regex/lint/gate comment-matcher — tripwire-vs-restate is semantic, not pattern-matchable (FR-22).
• Do not match surrounding comment density upward.
• Do not strip a retrieval pointer as if it were a duplicate.
• Do not apply to prose/doc files — this is the code carrier.
• Do not retroactively rewrite existing files outside an explicit Lightweight pass.

Clean-room note

Original Fusebase Flow content. Designed after reviewing public AI coding workflow patterns; no third-party code, prompts, skill files, or hook scripts are copied. See docs/source-map.md.