From e237845827b5bfc8aa390bf11ea8cb80cd50c3b9 Mon Sep 17 00:00:00 2001 From: Alex Clarke Date: Fri, 18 Sep 2026 12:31:48 -0600 Subject: [PATCH] feat: Improved comment etiquette for the sisyphus suite --- assets/agents/coder/graph.yaml | 6 ++++-- assets/agents/sisyphus/config.yaml | 4 ++-- assets/skills/comment-discipline/SKILL.md | 2 +- 3 files changed, 7 insertions(+), 5 deletions(-) diff --git a/assets/agents/coder/graph.yaml b/assets/agents/coder/graph.yaml index ba82ef4..00a34c6 100644 --- a/assets/agents/coder/graph.yaml +++ b/assets/agents/coder/graph.yaml @@ -222,7 +222,8 @@ nodes: 3. While reading it, note the repo's comment register per `comment-discipline` (self-documenting / api-documented / comment-heavy) and write comments to match. When the signal is - weak, write NO comment. + weak, write NO comment. Every comment must EARN ITS KEEP — if + the code already tells the reader, don't add it. 4. If the change touches boundaries, error paths, jobs, or state transitions, also note the logging register per `logging-discipline` (logger, message style, payload vs IDs, @@ -323,7 +324,8 @@ nodes: - Suppressed errors (as any, @ts-ignore, #[allow(...)] on unfamiliar lints, empty catch blocks) - Dishonest naming (get_X that mutates, returns wrong type, etc.) - - Useless comments that restate the code + - Useless comments that restate the code, or that otherwise don't earn + their keep (the code already tells the reader) - AI slop (filler prose, multi-paragraph docstrings, defensive handling of impossible cases) diff --git a/assets/agents/sisyphus/config.yaml b/assets/agents/sisyphus/config.yaml index ae966a4..46d6946 100644 --- a/assets/agents/sisyphus/config.yaml +++ b/assets/agents/sisyphus/config.yaml @@ -1,6 +1,6 @@ name: sisyphus description: OpenCode-style orchestrator - classifies intent, delegates to specialists, tracks progress with todos, enforces OMO-grade verification discipline -version: 3.14.0 +version: 3.15.0 agent_session: temp auto_continue: true @@ -575,7 +575,7 @@ instructions: | When you write or modify files yourself (rather than delegating to coder): - - **Calibrate comments before writing.** Load `comment-discipline` and note the repo's comment register (self-documenting / api-documented / comment-heavy) from the sibling files you read; write comments to match. When the signal is weak, write NO comment. + - **Calibrate comments before writing.** Load `comment-discipline` and note the repo's comment register (self-documenting / api-documented / comment-heavy) from the sibling files you read; write comments to match. When the signal is weak, write NO comment. In every register, a comment must EARN ITS KEEP — if the code already tells the reader, don't add it. - **Calibrate logging before writing.** When the change touches boundaries, error paths, jobs, or state transitions, load `logging-discipline` and note the repo's logging register (logger, message style, payload vs IDs, level semantics) from the same sibling reads; match it. No discernible convention → its best-judgment defaults. Never leave a new error path silently swallowed, and never delete existing log lines as drive-by cleanup. - **For editing an existing file**, prefer `fs_patch`. It's a surgical edit that preserves unchanged content. Send only the diff hunks for the lines you want to change; do not re-send the whole file. This is faster, cheaper, and dramatically less prone to accidental data loss than a full rewrite. - **For writing a NEW file or doing a COMPLETE rewrite**, use `fs_write`. Use it only when most of the content is changing or the file doesn't exist yet. diff --git a/assets/skills/comment-discipline/SKILL.md b/assets/skills/comment-discipline/SKILL.md index b14107d..18b7cd5 100644 --- a/assets/skills/comment-discipline/SKILL.md +++ b/assets/skills/comment-discipline/SKILL.md @@ -1,7 +1,7 @@ --- description: Calibrate comment density and style to the repository's existing conventions before writing code. Detects the repo's comment register (self-documenting / api-documented / comment-heavy) from the sibling files you already read for pattern matching, or from a declared policy in workspace instructions, then dictates when a comment is warranted. Default when signal is weak - write NO comment. Complements ai-slop-remover (which bans comments that restate code in every register). --- -You are about to write or modify code. LLMs systematically over-comment — narrating every block, restating signatures, banner-ing sections — and that default is wrong in most repositories. Before writing, determine the repo's **comment register** and match it, exactly the way you already match imports, naming, and error handling. +You are about to write or modify code. LLMs systematically over-comment — narrating every block, restating signatures, banner-ing sections — and that default is wrong in most repositories. Before writing, determine the repo's **comment register** and match it, exactly the way you already match imports, naming, and error handling. Across every register, one test governs each comment you write: it must **earn its keep**. If the code already tells the reader, the comment doesn't get written — don't add comments you don't need; make the code tell them instead. ## Step 0: Check for a declared policy first