# Comment Loop

> Explicitly selected repo-wide comment-hardening loop: map explanatory gaps and improve high-value code comments without changing behavior. Use when the user chooses $comment-loop or binding task instructions require it. Ordinary documentation edits or local comment changes do not select this loop.

- Skill: `aelaguiz/comment-loop` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add aelaguiz/comment-loop`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aelaguiz/comment-loop/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: aelaguiz (https://skillmd.com/u/aelaguiz)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/aelaguiz/comment-loop

---


# Comment Loop

Use this workflow only after explicit selection as `$comment-loop` or a
binding task instruction requiring it.

## When to use

- The user wants a repo-wide code-comment pass rather than one local comment tweak.
- The user wants the agent to deeply understand the repo before explaining conventions, contracts, or gotchas.
- The user wants to explain shared contracts, subtle behavior, counterintuitive flows, or high-impact conventions in code comments without changing behavior.
- The user wants to run one manual pass now or leave the explanatory hardening loop running in Codex or Claude Code until no credible high-impact comment work remains.

## When not to use

- The task is generic docs cleanup, stale README consolidation, or working-doc retirement. Use `arch-docs`.
- The task is a concrete known bug, crash, regression, or broken behavior. Use `bugs-flow`.
- The work is a repo-wide bug hunt, dead-code pass, or duplication cleanup. Use `audit-loop`.
- The task is a one-off local comment tweak with no need for exhaustive map-first triage.

## Non-negotiables

- `_comment_ledger.md` at repo root is the source of truth. Add it to the root `.gitignore` immediately.
- Triage before comment edits. Do not jump to adding comments because one line looks confusing.
- Exhaustively map shipped code surfaces, the current proof surface, and the current explanatory surface before any comment edits. If the map is incomplete, update the ledger and stop.
- When independent surface families make delegation worthwhile, use bounded
  clean native read-only mapping slices. Otherwise build the same exhaustive
  map sequentially.
- Rank consequence of misunderstanding first, then sharedness and blast radius, then explanation weakness, then confusion and staleness signals.
- Select a comment front from the completed map, not from a hunch.
- Comments explain existing contracts, behavior, and conventions. They do not create or change them.
- If the only honest next move is a bug fix, contract clarification, or broader docs rewrite, log that and stop or route to the owning skill instead of papering over it with comments.
- Verification depth must be proportional to the downstream consequence and blast radius of the surface being explained.
- Prefer authoritative comments at canonical owner boundaries over duplicated call-site narration.
- Do not spend the pass on low-value narration while outcome-critical shared contracts or gotchas remain unexplained.
- Do not add comments that restate names, signatures, or obvious mechanics.
- Update or delete touched stale comments in the same pass. Do not preserve stale explanation for history.
- Keep comments concise and use the smallest local form that makes the truth unmistakable.
- Examples belong only when they are the clearest way to show intended use or a counterintuitive gotcha.
- Unrelated dirty or untracked files are not a blocker. Leave them alone unless they directly conflict with the current comment front or make verification unsafe.
- Default invocation with no mode is `run`.
- `review` is docs-only.
- `auto` is goal-mode friendly. In native goal mode, keep running `run` then `review` until no credible high-impact comment work remains or a real blocker stops it. Outside goal mode, run one bounded pass and name the exact next command.
- No auto commits. Keep the ledger truthful without relying on git history.

## First move

1. Read `references/ledger-contract.md`.
2. Read `references/shared-doctrine.md`.
3. Read `references/commenting-principles.md`.
4. Read `../_shared/agent-orchestration-policy.md` before dispatching any
   mapping or review child.
5. Resolve the mode:
   - `run`
   - `review`
   - `auto`
6. Resolve repo root, root `.gitignore`, and `_comment_ledger.md`.
7. Read the matching mode reference and `references/quality-bar.md`.

## Parent And Child Roles

- The active parent owns comment scope, ledger writes, decomposition, every
  child-result account, synthesis, accepted repair direction, and the final
  controller verdict. Capture current git status and the relevant diff before
  read-only children run, then compare current state before accepting their
  evidence.
- Mapping slices and each independent `review` critic default to new clean
  same-host native children. In Codex set `fork_turns: "none"`; in Claude use
  a clean named or custom subagent, not a bare conversation fork or skill
  `context: fork` shorthand. Use bounded or full inherited context only for a
  named dependency that exists solely in chat; ordinary context travels via
  the ledger, exact paths, and the child brief.
- Give mappers and critics the strongest read-only capability the host exposes
  and explicitly tell them not to edit or write files, including the ledger.
  They may use their own native sub-agents on their own host; they may not start
  external agents.
- Split only across independent code, proof, explanation, or review families.
  Bound fanout by available host slots, shared-file or shared-state collision
  risk, and the parent's capacity to inspect and integrate every return.
- If a controller needs a background or external process after the parent turn
  ends, that transport supplies lifecycle continuity, not critic freshness.
  Choose it only when that concrete lifecycle or another benefit is worth its
  process and integration cost under the shared policy.

## Workflow

### 1) `run`

- Create or repair `_comment_ledger.md` and the `.gitignore` entry.
- Build or refresh the exhaustive map of shipped code surfaces, the current proof surface, and the current explanatory surface.
- If the map is incomplete, record the next unfinished mapping tranche in `Next Area`, update the ledger, and stop without comment edits.
- Once the map is complete, rank comment fronts by consequence of misunderstanding first, then sharedness, then explanation weakness, then confusion and staleness signals.
- Pick the highest-priority unresolved comment front from that ranking and record the pre-edit proof plan.
- Read the implementation before writing explanation. Read tests, callers, and nearby owner boundaries as needed to prove the explanation is truthful.
- Add or repair only the high-leverage comments, docstrings, or doc comments that materially reduce misunderstanding across that front.
- Verify the changed explanation with proof proportional to the front's consequence, update the ledger, and stop only when further useful work would require a genuinely different explanation story, a new reconnaissance pass, or a real blocker.

### 2) `review`

- Stay docs-only.
- Repair the ledger if it is missing or malformed.
- Have a new clean independent critic re-read the ledger and current repo
  state without writing files; the parent spot-checks and integrates its
  return.
- Confirm whether the map is complete, whether the current or next front comes from the ranked map, whether recent comments are truthful and high leverage, and whether verification depth matched the consequence of the touched surfaces.
- Set the controller verdict to `CONTINUE`, `CLEAN`, or `BLOCKED` and name the next mapping tranche, comment front, or blocker plainly.

### 3) `auto`

`auto` is the repeated comment-hardening loop. Native goal mode supplies the
repeated turns; this skill does not install or arm automation hooks.

Workflow:

1. Run one truthful `run` pass. Mapping-only is correct on the first turns.
2. Run a new clean independent `review` critic against `_comment_ledger.md`
   and current repo state, using a same-host native child by default while the
   parent session is active.
3. If review says `CONTINUE`, run the next `$comment-loop run` pass.
4. In native goal mode, keep repeating until review says `CLEAN` or `BLOCKED`.
5. Outside native goal mode, stop after one run/review cycle and print the next exact command.

`comment-loop`-specific rules:

- User-facing invocation is just `comment-loop auto`.
- Dirty or untracked files are not a blocker. Do not refuse to run only because the repo has unrelated dirty or untracked files.
- `auto` must not degrade into low-value narration while outcome-critical shared contracts or gotchas remain unexplained.
- Do not auto-commit changes.

## Output expectations

- Update `_comment_ledger.md` in every mode.
- Keep console output short:
  - comment North Star reminder
  - punchline
  - current mapping tranche, comment front, or verdict
  - evidence or tests run
  - next action

## Reference map

- `references/ledger-contract.md` - root ledger shape, status vocabulary, and cleanup lifecycle
- `references/shared-doctrine.md` - prioritization, explanation discipline, and anti-patterns
- `references/commenting-principles.md` - distilled external best practices for useful comments
- `references/run.md` - mapping-aware comment or cleanup pass
- `references/review.md` - new clean docs-only verdict pass
- `references/comment-loop-controller.md` - comment-loop auto status and verdict source
- `references/quality-bar.md` - strong vs weak triage, findings, comments, and stop decisions